Учебник: публикация и подписка на сообщения с помощью API WebSocket и пакета SDK для службы Web PubSub Azure

Статья
09/03/2024

Служба Azure Web PubSub помогает легко создавать приложения веб-обмена сообщениями в режиме реального времени. В этом руководстве описано, как подписаться на службу с помощью API WebSocket и опубликовать сообщения с помощью пакета SDK службы Web PubSub.

В этом руководстве описано следующее:

Создание экземпляра службы Web PubSub.
Создание полного URL-адреса для установки подключения WebSocket
Создание клиента подписчика Web PubSub для получения сообщений с помощью стандартного протокола WebSocket
Создание клиента издателя Web PubSub для публикации сообщений с помощью пакета SDK службы Web PubSub

Необходимые компоненты

Подписка Azure создает бесплатную учетную запись.
Командная оболочка Bash. Используйте локальную оболочку или среду Bash в Azure Cloud Shell.
При запуске на локальном компьютере установите Azure CLI.

Командную оболочку Windows cmd.exe можно использовать вместо оболочки Bash для выполнения команд в этом руководстве.

Если вы создаете проект на локальном компьютере, необходимо установить зависимости для используемого языка:

.NET Core

Подготовка среды

Локальный интерфейс командной строки Azure
Azure Cloud Shell

Настройка Azure CLI для локальной разработки

Выполните следующие действия, чтобы настроить Azure CLI и среду проекта.

Откройте командную оболочку.
Обновите до последней версии Azure CLI.
```
az upgrade
```
Установите расширение Azure CLI для Web PubSub.
```
az extension add --name webpubsub
```
Войдите в Azure CLI. После запроса введите учетные данные Azure.
```
az login
```

Создание или изменение группы ресурсов

Группа ресурсов — это логический контейнер, в котором происходит развертывание ресурсов Azure и управление ими. Используйте команду az group create, чтобы создать группу ресурсов с именем myResourceGroup в расположенииeastus.

az group create --name myResourceGroup --location EastUS

1. Создание экземпляра Azure Web PubSub

Создание экземпляра Web PubSub

Чтобы создать экземпляр Web PubSub в созданной группе ресурсов, используйте команду azure CLI az webpubsub create . Следующая команда создает ресурс Free Web PubSub в группе myResourceGroup ресурсов:EastUS

Каждый ресурс Web PubSub должен иметь уникальное имя. Замените <имя уникального ресурса> именем экземпляра Web PubSub в следующей команде.

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

В выходных данных команды будут показаны свойства созданного ресурса. Обратите внимание на следующие веревки:

name: Имя Web PubSub, указанное в приведенном выше параметре --name .
hostName: в примере имя узла <your-unique-resource-name>.webpubsub.azure.com/.

На данном этапе любые операции в этом новом ресурсе могут выполняться только с использованием вашей учетной записи Azure.

Получение строки подключения

Внимание

Строка подключения содержит сведения об авторизации, требуемые для доступа приложения к службе Azure Web PubSub. Ключ доступа в строке подключения аналогичен паролю привилегированного пользователя для службы. В рабочих средах всегда следует тщательно защищать ключи доступа. Для безопасного управления ключами и их замены воспользуйтесь Azure Key Vault. Старайтесь не распространять ключи доступа среди других пользователей, жестко программировать их или где-то сохранять в виде обычного текста в открытом доступе для других пользователей. Меняйте свои ключи постоянно, если предполагаете, что они могут быть подобраны.

Выполните команду 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

Скопируйте строка подключения для последующего использования.

Создание клиента подписчика

Клиенты подключаются к службе Web PubSub Azure через стандартный протокол WebSocket, используя проверку подлинности JSON Web Token (JWT). Пакет SDK для службы предоставляет вспомогательные методы для создания токена. В этом учебнике подписчик напрямую создает токен из ConnectionString. В реальных приложениях серверное приложение обычно обрабатывает рабочий процесс проверки подлинности и авторизации. Чтобы лучше понять рабочий процесс, ознакомьтесь с руководством по созданию приложения чата.

Сначала создайте каталог проекта с именем subscriber этого проекта и установите необходимые зависимости:
- Пакет Websocket.Client — это сторонний пакет, поддерживающий подключения WebSocket. Вы можете использовать любой API или библиотеку, которая поддерживает WebSocket.
- Пакет 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
```
Замените код в следующем коде 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();
            }
        }
    }
}
```
Код создает подключение WebSocket, подключенное к концентратору в Web PubSub. Концентратор — это логическая единица в Web PubSub, где можно публиковать сообщения в группе клиентов. Основные понятия содержат подробное описание терминов, используемых в Web PubSub.

Служба Web PubSub использует проверку подлинности веб-маркера JSON (JWT ). Пример кода используется WebPubSubServiceClient.GetClientAccessUri() в пакете SDK web PubSub для создания URL-адреса службы, содержащей полный URL-адрес с допустимым маркером доступа.

После установки подключения клиент получает сообщения через подключение WebSocket. Клиент использует для client.MessageReceived.Subscribe(msg => ...)); прослушивания входящих сообщений.
Чтобы запустить подписчик, выполните следующую команду, заменив <Web-PubSub-connection-string> строка подключения скопированной ранее:
```
dotnet run <Web-PubSub-connection-string> "myHub1"
```

Сначала создайте каталог проекта с именем subscriber и установите необходимые зависимости:
```
mkdir subscriber
cd subscriber
npm init -y
npm install --save ws
npm install --save @azure/web-pubsub
```
Используйте API WebSocket для подключения к службе Web PubSub. Создайте файл subscribe.js со следующим кодом:
```
const WebSocket = require('ws');
const { WebPubSubServiceClient } = require('@azure/web-pubsub');

async function main() {
  const hub = "pubsub";
  let service = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);
  let token = await service.getClientAccessToken();
  let ws = new WebSocket(token.url);
  ws.on('open', () => console.log('connected'));
  ws.on('message', data => console.log('Message received: %s', data));
}

main();
```
Код создает подключение WebSocket, подключенное к концентратору в Web PubSub. Концентратор — это логическая единица в Web PubSub, где можно публиковать сообщения в группе клиентов. Основные понятия содержат подробное описание терминов, используемых в Web PubSub.

Служба Web PubSub использует проверку подлинности веб-маркера JSON (JWT ). Пример кода используется WebPubSubServiceClient.GetClientAccessUri() в пакете SDK web PubSub для создания URL-адреса службы, содержащей полный URL-адрес с допустимым маркером доступа.

После установки подключения клиент получает сообщения через подключение WebSocket. Клиент использует для client.MessageReceived.Subscribe(msg => ...)); прослушивания входящих сообщений.
Выполните следующую команду, заменив <Web-PubSub-connection-string> строка подключения скопированной ранее. Если вы используете командную оболочку Windows, вместо этого exportможно использоватьset.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node subscribe.js
```

Сначала создайте каталог проекта с именем subscriber и установите необходимые зависимости:

mkdir subscriber
cd subscriber
# Create venv
python -m venv env
# Activate venv
source ./env/bin/activate

pip install azure-messaging-webpubsubservice
pip install websockets

Используйте API WebSocket для подключения к службе Web PubSub. Создайте файл subscribe.py со следующим кодом:
```
import asyncio
import sys
import websockets

from azure.messaging.webpubsubservice import WebPubSubServiceClient


async def connect(url):
    async with websockets.connect(url) as ws:
        print('connected')
        while True:
            print('Received message: ' + await ws.recv())

if __name__ == '__main__':

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

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

    service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
    token = service.get_client_access_token()

    try:
        asyncio.get_event_loop().run_until_complete(connect(token['url']))
    except KeyboardInterrupt:
        pass
```
Код создает подключение WebSocket, подключенное к концентратору в Web PubSub. Концентратор — это логическая единица в Web PubSub, где можно публиковать сообщения в группе клиентов. Основные понятия содержат подробное описание терминов, используемых в Web PubSub.

Служба Web PubSub использует проверку подлинности веб-маркера JSON (JWT ). Пример кода используется WebPubSubServiceClient.GetClientAccessUri() в пакете SDK web PubSub для создания URL-адреса службы, содержащей полный URL-адрес с допустимым маркером доступа.

После установки подключения клиент получит сообщения через подключение WebSocket. Используется await ws.recv() для прослушивания входящих сообщений.
Выполните следующую команду, заменив <Web-PubSub-connection-string> строка подключения скопированной ранее:
```
python subscribe.py <Web-PubSub-connection-string> "myHub1"
```

Сначала создайте каталог проекта с именем pubsub этого руководства.
```
mkdir pubsub
cd pubsub
```

В каталоге pubsub используйте Maven для создания нового консольного приложения webpubsub-quickstart-subscriber, а затем перейдите в каталог webpubsub-quickstart-subscriber :

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

Добавьте в узел пакет SDK dependencies WebSocket и Azure Web PubSub:pom.xml
- azure-messaging-webpubsub: пакет SDK службы Web PubSub для Java
- Java-WebSocket: клиентский пакет SDK WebSocket для Java
```
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.0.0</version>
</dependency>

<dependency>
    <groupId>org.java-websocket</groupId>
    <artifactId>Java-WebSocket</artifactId>
    <version>1.5.1</version>
</dependency>
```
В Web PubSub можно подключиться к службе и подписаться на сообщения через подключения WebSocket. WebSocket — это полно дуплексный канал связи, позволяющий службе отправлять сообщения клиенту в режиме реального времени. Вы можете использовать любой API или библиотеку, которая поддерживает WebSocket. В этом примере мы используем пакет Java-WebSocket.
Перейдите в каталог /src/main/java/com/webpubsub/quickstart .

Измените содержимое файла App.java следующим кодом:

package com.webpubsub.quickstart;

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

import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;

/**
* Connect to Azure Web PubSub service using WebSocket protocol
*/
public class App 
{
    public static void main( String[] args ) throws IOException, URISyntaxException
    {
        if (args.length != 2) {
            System.out.println("Expecting 2 arguments: <connection-string> <hub-name>");
            return;
        }

        WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
            .connectionString(args[0])
            .hub(args[1])
            .buildClient();

        WebPubSubClientAccessToken token = service.getClientAccessToken(new GetClientAccessTokenOptions());

        WebSocketClient webSocketClient = new WebSocketClient(new URI(token.getUrl())) {
            @Override
            public void onMessage(String message) {
                System.out.println(String.format("Message received: %s", message));
            }

            @Override
            public void onClose(int arg0, String arg1, boolean arg2) {
                // TODO Auto-generated method stub
            }

            @Override
            public void onError(Exception arg0) {
                // TODO Auto-generated method stub
            }

            @Override
            public void onOpen(ServerHandshake arg0) {
                // TODO Auto-generated method stub
            }

        };

        webSocketClient.connect();
        System.in.read();
    }
}

Этот код создает подключение WebSocket, подключенное к концентратору в Azure Web PubSub. Концентратор — это логическая единица в Azure Web PubSub, где можно публиковать сообщения в группе клиентов. Основные понятия содержат подробное описание терминов, используемых в Azure Web PubSub.

Служба Web PubSub использует проверку подлинности веб-маркера JSON (JWT ). Пример кода используется WebPubSubServiceClient.GetClientAccessUri() в пакете SDK web PubSub для создания URL-адреса службы, содержащей полный URL-адрес с допустимым маркером доступа.

После установки подключения клиент получит сообщения через подключение WebSocket. Используется onMessage(String message) для прослушивания входящих сообщений.

Чтобы запустить приложение подписчика, перейдите в каталог webpubsub-quickstart-subscriber и выполните следующую команду. Замените <Web-PubSub-connection-string> строка подключения скопированных ранее.
```
mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1'"
```

2. Публикация сообщений с помощью пакета SDK службы

Создайте издателя с помощью пакета SDK azure Web PubSub для публикации сообщения в подключенном клиенте. Для этого проекта необходимо открыть другую командную оболочку.

Сначала создайте каталог проекта с именем publisher и установите необходимые зависимости:
```
mkdir publisher
cd publisher
dotnet new console
dotnet add package Azure.Messaging.WebPubSub
```

Обновите файл 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() просто отправляет сообщение всем подключенным клиентам в концентраторе.

Отправьте сообщение, выполнив следующую команду. Замените <Web-PubSub-connection-string> строка подключения скопированных ранее.
```
dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"
```
Убедитесь, что командная оболочка подписчика получает сообщение:
```
Message received: Hello World
```

Сначала создайте каталог проекта с именем publisher и установите необходимые зависимости:
```
mkdir publisher
cd publisher
npm init -y
npm install --save @azure/web-pubsub
```
Используйте пакет SDK azure Web PubSub для публикации сообщения в службе. Создайте файл publish.js со следующим кодом:
```
const { WebPubSubServiceClient } = require('@azure/web-pubsub');

const hub = "pubsub";
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" });
```
Вызов service.sendToAll() просто отправляет сообщение всем подключенным клиентам в концентраторе.
Чтобы отправить сообщение, выполните следующую команду, заменив <Web-PubSub-connection-string> строка подключения скопированной ранее. Если вы используете командную оболочку Windows, вместо этого exportможно использоватьset.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node publish "Hello World"
```
Вы можете увидеть, что подписчик получил сообщение:
```
Message received: Hello World
```

Сначала создайте каталог проекта с именем publisher и установите необходимые зависимости:
```
mkdir publisher
cd publisher
# Create venv
python -m venv env
# Active venv
source ./env/bin/activate

pip install azure-messaging-webpubsubservice
```

Используйте пакет SDK azure Web PubSub для публикации сообщения в службе. Создайте файл 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)

send_to_all() отправляет сообщение всем подключенным клиентам в концентраторе.

Чтобы отправить сообщение, выполните следующую команду, заменив <Web-PubSub-connection-string> строка подключения скопированной ранее.
```
python publish.py <Web-PubSub-connection-string> "myHub1" "Hello World"
```
Проверьте предыдущую командную оболочку, чтобы подписчик получил сообщение:
```
Received message: Hello World
```

Перейдите в pubsub каталог. Используйте 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

Добавьте зависимость пакета SDK azure Web PubSub в dependencies узел pom.xml:

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

Используйте пакет SDK azure Web PubSub для публикации сообщения в службе. Перейдите в каталог /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);
    }
}

Вызов sendToAll() отправляет сообщение всем подключенным клиентам в центре.

Чтобы отправить сообщение, перейдите в каталог webpubsub-quickstart-publisher и запустите проект с помощью следующей команды. Замените <Web-PubSub-connection-string> строка подключения скопированным ранее.
```
mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1' 'Hello World'"
```
Вы можете увидеть, что подписчик получил сообщение:
```
Message received: Hello World
```

Очистка

Вы можете удалить ресурсы, созданные в этом кратком руководстве, удалив группу ресурсов, содержащую их.

az group delete --name myResourceGroup --yes

Если вы не планируете продолжать использовать Azure Cloud Shell, вы можете избежать накапливаемых затрат, удалив группу ресурсов, содержащую связанную учетную запись хранения. Группа ресурсов называется cloud-shell-storage-<your-region>. Выполните следующую команду, заменив <CloudShellResourceGroup> имя группы Cloud Shell.

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

Внимание

Удаление групп ресурсов приведет к удалению всех ресурсов, включая ресурсы, созданные вне области работы этого руководства.

Следующие шаги

В этом руководстве вы узнаете, как подключиться к службе Web PubSub и публиковать сообщения на подключенных клиентах.

Дополнительные сведения об использовании службы см. в других руководствах.

Руководство по созданию чат-комнаты с помощью Azure Web PubSub

Другие примеры Azure Web PubSub

Поделиться через