通过

教程：使用 WebSocket API 和 Azure Web PubSub 服务 SDK 发布和订阅消息

  • 项目

Azure Web PubSub 服务可帮助你轻松生成实时 Web 消息传递应用程序。 本教程介绍如何使用 WebSocket API 订阅服务，以及如何使用 Web PubSub 服务 SDK 发布消息。

本教程介绍如何执行下列操作：

  • 创建 Web PubSub 服务实例
  • 生成完整 URL 以建立 WebSocket 连接
  • 创建 Web PubSub 订阅服务器客户端以使用标准 WebSocket 协议接收消息
  • 创建 Web PubSub 发布服务器客户端以使用 Web PubSub 服务 SDK 发布消息

先决条件

你可以使用 Windows cmd.exe 命令 shell 而不是 Bash shell 来运行本教程中的命令。

如果在本地计算机上创建项目，则需要安装所用语言的依赖项：

准备环境

用于本地开发的 Azure CLI 设置

按照以下步骤设置 Azure CLI 和项目环境。

  1. 打开命令行界面。

  2. 升级到最新版本的 Azure CLI。

    az upgrade

  3. 安装 Web PubSub 的 Azure CLI 扩展。

    az extension add --name webpubsub

  4. 登录到 Azure CLI。 按照提示输入你的 Azure 凭据。

    az login

创建资源组

资源组是在其中部署和管理 Azure 资源的逻辑容器。 使用 az group create 命令在 chinaeast 位置创建名为 myResourceGroup 的资源组。

az group create --name myResourceGroup --location ChinaEast

1. 创建 Azure Web PubSub 实例

创建 Web PubSub 实例

若要在创建的资源组中创建 Web PubSub 实例，请使用 Azure CLI az webpubsub create 命令。 以下命令在 ChinaEast 的资源组 myResourceGroup 下创建一个免费的 Web PubSub 资源：

每个 Web PubSub 资源必须具有唯一名称。 在以下命令中，将 <your-unique-resource-name> 替换为 Web PubSub 实例的名称。

az webpubsub create --resource-group myResourceGroup --name <your-unique-resource-name> --location ChinaEast --sku Free_F1

此命令的输出会显示新建的资源的属性。 记录以下属性：

  • 名称：在上面的 --name 参数中提供的 Web PubSub 名称。
  • 主机名：在本例中，主机名为 <your-unique-resource-name>.webpubsub.azure.com/。

目前，只有你的 Azure 帐户才有权对这个新资源执行任何操作。

获取连接字符串

重要

连接字符串包括应用程序访问 Azure Web PubSub 服务所需的授权信息。 连接字符串中的访问密钥类似于服务的根密码。 在生产环境中，请始终小心保护访问密钥。 使用 Azure 密钥保管库安全地管理和轮换密钥。 避免将访问密钥分发给其他用户、对其进行硬编码或将其以纯文本形式保存在其他人可以访问的任何位置。 如果你认为访问密钥可能已泄露，请轮换密钥。

使用 Azure CLI az webpubsub key 命令获取服务的 ConnectionString。 将 <your-unique-resource-name> 占位符替换为 Azure Web PubSub 实例的名称。

az webpubsub key show --resource-group myResourceGroup --name <your-unique-resource-name> --query primaryConnectionString --output tsv

复制主连接字符串以供稍后使用。

创建订阅服务器客户端

客户端使用 JSON Web 令牌 (JWT) 身份验证通过标准 WebSocket 协议连接到 Azure Web PubSub 服务。 服务 SDK 提供帮助程序方法来生成令牌。 在本教程中，订阅者直接根据 ConnectionString 生成令牌。 在真实应用程序中，服务器端应用程序通常会处理身份验证/授权工作流。 若要更好地了解该工作流，请参阅教程生成聊天应用。

  1. 首先，为此项目创建一个名为 subscriber 的项目目录，并安装所需的依赖项：

    • Websocket.Client 包是支持 WebSocket 连接的第三方包。 可以使用任何支持 WebSocket 的 API 或库。
    • SDK 包 Azure.Messaging.WebPubSub 可帮助生成 JWT 令牌。
    mkdir subscriber
cd subscriber
dotnet new console
dotnet add package Websocket.Client --version 4.3.30
dotnet add package Azure.Messaging.WebPubSub --version 1.0.0

  2. 将 Program.cs 中的代码替换为以下会连接到服务的代码：

    using System;
using System.Threading.Tasks;

using Azure.Messaging.WebPubSub;

using Websocket.Client;

namespace subscriber
{
    class Program
    {
        static async Task Main(string[] args)
        {
            if (args.Length != 2)
            {
                Console.WriteLine("Usage: subscriber <connectionString> <hub>");
                return;
            }
            var connectionString = args[0];
            var hub = args[1];

            // Either generate the URL or fetch it from server or fetch a temp one from the portal
            var serviceClient = new WebPubSubServiceClient(connectionString, hub);
            var url = serviceClient.GetClientAccessUri();

            using (var client = new WebsocketClient(url))
            {
                // Disable the auto disconnect and reconnect because the sample would like the client to stay online even no data comes in
                client.ReconnectTimeout = null;
                client.MessageReceived.Subscribe(msg => Console.WriteLine($"Message received: {msg}"));
                await client.Start();
                Console.WriteLine("Connected.");
                Console.Read();
            }
        }
    }
}

    该代码创建与 Web PubSub 中某个中心的 WebSocket 连接。 中心是 Web PubSub 中的一个逻辑单元，你可以在其中向一组客户端发布消息。 关键概念包含有关 Web PubSub 中使用的术语的详细解释。

    Web PubSub 服务使用 JSON Web 令牌 (JWT) 身份验证。 示例代码使用 Web PubSub SDK 中的 WebPubSubServiceClient.GetClientAccessUri() 生成服务的 URL，其中包含完整 URL 和有效的访问令牌。

    建立连接后，客户端将通过 WebSocket 连接接收消息。 客户端使用 client.MessageReceived.Subscribe(msg => ...)); 侦听传入的消息。

  3. 若要启动订阅服务器，请运行以下命令，将 <Web-PubSub-connection-string> 替换为之前复制的连接字符串：

    dotnet run <Web-PubSub-connection-string> "myHub1"

2. 使用服务 SDK 发布消息

使用 Azure Web PubSub SDK 创建发布服务器，以将消息发布到连接的客户端。 对于此项目，需要打开另一个命令 shell。

  1. 首先，创建一个名为 publisher 的项目目录，并安装所需的依赖项：

    mkdir publisher
cd publisher
dotnet new console
dotnet add package Azure.Messaging.WebPubSub

  2. 更新 Program.cs 文件，以使用 WebPubSubServiceClient 类并将消息发送到客户端。

    using System;
using System.Threading.Tasks;
using Azure.Messaging.WebPubSub;

namespace publisher
{
    class Program
    {
        static async Task Main(string[] args)
        {
            if (args.Length != 3) {
                Console.WriteLine("Usage: publisher <connectionString> <hub> <message>");
                return;
            }
            var connectionString = args[0];
            var hub = args[1];
            var message = args[2];

            // Either generate the token or fetch it from server or fetch a temp one from the portal
            var serviceClient = new WebPubSubServiceClient(connectionString, hub);
            await serviceClient.SendToAllAsync(message);
        }
    }
}

    SendToAllAsync() 调用会直接将消息发送到中心内所有已连接的客户端。

  3. 运行以下命令，发送消息。 将 <Web-PubSub-connection-string> 替换为先前复制的连接字符串。

    dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"

  4. 验证订阅者的命令行界面是否收到消息：

    Message received: Hello World

清理

可以删除在本快速入门中创建的资源，只需删除包含这些资源的资源组即可。

az group delete --name myResourceGroup --yes

az group delete --name <CloudShellResourceGroup> --yes

注意

删除资源组会删除所有资源，包括在本教程范围之外创建的资源。

后续步骤

本教程大致介绍了如何连接到 Web PubSub 服务以及如何将消息发布到连接的客户端。

请查看其他教程，进一步深入了解如何使用该服务。

教程：使用 Azure Web PubSub 创建聊天室

了解更多 Azure Web PubSub 示例