快速入门：使用 Azure Web PubSub 服务 SDK 发布消息

项目
04/08/2023

Azure Web PubSub 可帮助你管理 WebSocket 客户端。本快速入门介绍如何使用 Azure Web PubSub 服务 SDK 将消息发布到 WebSocket 客户端。

先决条件

一个 Azure 订阅。如果你没有订阅，请创建一个试用订阅。
Bash 和 PowerShell 命令 shell。 Python、JavaScript 和 Java 示例需要 Bash 命令 shell。
一个文件编辑器，例如 VSCode。
Azure CLI：安装 Azure CLI

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

安装 .NET Core SDK 以及 aspnetcore 和 .NET 运行时。

.NET Core

1. 设置

若要从 CLI 登录到 Azure，请运行以下命令，然后按照提示完成身份验证过程。

az login

确保通过升级命令运行最新版本的 CLI。

az upgrade

接下来，使用 az upgrade 安装或更新 CLI 的 Azure Web PubSub 扩展（如果未安装）。

az extension add --name webpubsub --upgrade

1. 创建资源组

设置以下环境变量。将 <占位符> 替换为唯一的 Web PubSub 名称。

Bash
Azure PowerShell

RESOURCE_GROUP="webpubsub-resource-group"
LOCATION="China East 2"
WEB_PUBSUB_NAME="<your-unique-name>"

$ResourceGroupName = 'webpubsub-resource-group'
$Location = 'China East 2'
$WebPubSubName = '<YourUniqueName>'

为 Web PubSub 项目创建资源组。

Bash
Azure PowerShell

az group create \
  --name $RESOURCE_GROUP \
  --location $LOCATION

az group create --location $Location --name $ResourceGroupName

2. 部署 Web PubSub 服务实例

使用 az webpubsub create 命令创建并部署 Web PubSub 服务实例。

Bash
Azure PowerShell

az webpubsub create \
  --name $WEB_PUBSUB_NAME \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --sku Free_F1

az webpubsub create `
  --name $WebPubSubName `
  --location $Location `
  --resource-group $ResourceGroupName `
  --sku Free_F1

保存服务的连接字符串。服务 SDK 使用该连接字符串来发布消息。

重要

在生产环境中，应使用 Azure 密钥保管库安全存储连接字符串。

Bash
Azure PowerShell

az webpubsub key show --name $WEB_PUBSUB_NAME --resource-group $RESOURCE_GROUP --query primaryConnectionString

az webpubsub key show --name $WebPubSubName --resource-group $ResourceGroupName --query primaryConnectionString

3. 将客户端连接到服务实例

创建 Web PubSub 客户端。该客户端将与服务保持连接，直到被终止。

使用 az webpubsub client 命令启动 WebSocket 客户端与服务的连接。客户端始终连接到中心，因此请为客户端提供它要连接到的中心名称。

Bash
Azure PowerShell

az webpubsub client start \
  --name $WEB_PUBSUB_NAME \
  --resource-group $RESOURCE_GROUP \
  --hub-name "myHub1" \
  --user-id "user1"

az webpubsub client start `
  --name $WebPubSubName `
  --resource-group $ResourceGroupName `
  --hub-name 'myHub1' `
  --user-id 'user1'

如果看到一条 JSON 消息，指出客户端现已成功连接并为其分配了唯一的 connectionId，则表示与 Web PubSub 服务建立了连接：

{"type":"system","event":"connected","userId":"user1","connectionId":"<your_unique_connection_id>"}

4. 使用服务 SDK 发布消息

你将使用 Azure Web PubSub SDK 向连接到中心的所有客户端发布消息。可以在 C#、JavaScript、Python 和 Java 之间进行选择。每种语言的依赖项在适用于该语言的步骤中安装。 Python、JavaScript 和 Java 需要 bash shell 才能运行本快速入门中的命令。

设置项目以发布消息

为此项目打开一个新的命令 shell。
从客户端 shell 保存连接字符串。将 <your_connection_string> 占位符替换为前面步骤中显示的连接字符串。
- Bash
- Azure PowerShell
```
connection_string="<your_connection_string>"
```
```
$connection_string = "<your_connection_string>"
```
现在，为项目选择语言。

添加名为 publisher 的新项目和 SDK 包 Azure.Messaging.WebPubSub。

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

更新 Program.cs 文件，以使用 WebPubSubServiceClient 类将消息发送到客户端。将 Program.cs 文件中的代码替换为以下代码。

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];

            var service = new WebPubSubServiceClient(connectionString, hub);

            // Send messages to all the connected clients
            // You can also try SendToConnectionAsync to send messages to the specific connection
            await service.SendToAllAsync(message);
        }
    }
}

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

运行以下命令以将消息发布到服务。

dotnet run $connection_string "myHub1" "Hello World"

以上包含 Web PubSub 客户端的命令 shell 会显示收到的消息。
```
{"type":"message","from":"server","dataType":"text","data":"Hello World"}
```

为此项目创建名为 publisher 的新文件夹，并安装所需的依赖项：
```
mkdir publisher
cd publisher
npm init -y
npm install --save @azure/web-pubsub
```

使用 Azure Web PubSub SDK 将消息发布到服务。创建包含以下代码的 publish.js 文件：

const { WebPubSubServiceClient } = require('@azure/web-pubsub');

if (process.argv.length !== 3) {
  console.log('Usage: node publish <message>');
  return 1;
}
const hub = "myHub1";
let service = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);
// by default it uses `application/json`, specify contentType as `text/plain` if you want plain-text
service.sendToAll(process.argv[2], { contentType: "text/plain" });

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

运行以下命令以将消息发布到服务：

export WebPubSubConnectionString=$connection_string
node publish "Hello World"

以上包含 Web PubSub 客户端的命令 shell 会显示收到的消息。
```
{"type":"message","from":"server","dataType":"text","data":"Hello World"}
```

为此项目创建名为 publisher 的新文件夹，并安装所需的依赖项：

mkdir publisher
cd publisher
# Create venv
python -m venv env
# Active venv
source ./env/bin/activate
pip install azure-messaging-webpubsubservice

使用 Azure Web PubSub SDK 将消息发布到服务。使用以下代码创建一个 publish.py 文件：

import sys
from azure.messaging.webpubsubservice import WebPubSubServiceClient

if __name__ == '__main__':

    if len(sys.argv) != 4:
        print('Usage: python publish.py <connection-string> <hub-name> <message>')
        exit(1)

    connection_string = sys.argv[1]
    hub_name = sys.argv[2]
    message = sys.argv[3]

    service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
    res = service.send_to_all(message, content_type='text/plain')
    print(res)

service.send_to_all() 方法会将消息发送到中心内所有已连接的客户端。

运行以下命令以将消息发布到服务：

python publish.py $connection_string "myHub1" "Hello World"

以上包含 Web PubSub 客户端的命令 shell 会显示收到的消息。
```
{"type":"message","from":"server","dataType":"text","data":"Hello World"}
```

使用 Maven 创建名为 webpubsub-quickstart-publisher 的新控制台应用，并转到 webpubsub-quickstart-publisher 目录：

mvn archetype:generate --define interactiveMode=n --define groupId=com.webpubsub.quickstart --define artifactId=webpubsub-quickstart-publisher --define archetypeArtifactId=maven-archetype-quickstart --define archetypeVersion=1.4
cd webpubsub-quickstart-publisher

将 Azure Web PubSub SDK 添加到 pom.xml 的 dependencies 节点：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.0.0</version>
</dependency>

转到 src/main/java/com/webpubsub/quickstart 目录。

将 App.java 文件中的内容替换为以下代码：

package com.webpubsub.quickstart;

import com.azure.messaging.webpubsub.*;
import com.azure.messaging.webpubsub.models.*;

/**
* Publish messages using Azure Web PubSub service SDK
*
*/
public class App 
{
    public static void main( String[] args )
    {
        if (args.length != 3) {
            System.out.println("Expecting 3 arguments: <connection-string> <hub-name> <message>");
            return;
        }

        WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
            .connectionString(args[0])
            .hub(args[1])
            .buildClient();
        service.sendToAll(args[2], WebPubSubContentType.TEXT_PLAIN);
    }
}

此代码使用 Azure Web PubSub SDK 将消息发布到服务。 service.sendToAll() 调用会将消息发送到中心内所有已连接的客户端。

返回包含 pom.xml 文件的 webpubsub-quickstart-publisher 目录，并使用以下 mvn 命令编译项目。
```
mvn compile
```
生成包。
```
mvn package
```

运行以下 mvn 命令执行应用，以将消息发布到服务：

mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args=" '$connection_string' 'myHub1' 'Hello World'"

以上包含 Web PubSub 客户端的命令 shell 会显示收到的消息。
```
{"type":"message","from":"server","dataType":"text","data":"Hello World"}
```

清理

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

Bash
Azure PowerShell

az group delete --name $RESOURCE_GROUP --yes

az group delete --name $ResourceGroup --yes

后续步骤

本快速入门提供如何连接到 Web PubSub 服务以及如何将消息发布到连接的客户端的基本想法。

在现实应用程序中，你可以使用各种语言的 SDK 来生成自己的应用程序。我们还提供了函数扩展，供你轻松生成无服务器应用程序。

使用这些资源开始生成自己的应用程序：

教程：在 Azure Web PubSub 中发布和订阅消息

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

教程：使用服务支持的子协议进行客户端流式处理

教程：使用 Azure Functions 和 Web PubSub 生成无服务器聊天

教程：配置事件侦听器

体验实时演示

了解更多 Azure Web PubSub 示例

通过