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

Служба 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 для выполнения команд в этом руководстве.

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

C#

.NET Core

JavaScript

Node.js

Python

Python

Java

• Пакет средств разработки Java (JDK)
• Apache Maven

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

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

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

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

1. Откройте командную оболочку.

2. Обновите до последней версии Azure CLI.

   az upgrade
   

3. Установите расширение Azure CLI для Web PubSub.

   az extension add --name webpubsub
   

4. Войдите в Azure CLI. После запроса введите учетные данные Azure.

   az login
   

Azure Cloud Shell

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

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

az group create --name myResourceGroup --location EastUS

---

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

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

Используйте команду azure CLI az webpubsub create , чтобы создать web PubSub в созданной группе ресурсов. Следующая команда создает ресурс 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. В реальных приложениях серверное приложение обычно обрабатывает рабочий процесс проверки подлинности и авторизации. Чтобы лучше понять рабочий процесс, ознакомьтесь с руководством по созданию приложения чата.

C#

1. Сначала создайте каталог проекта с именем 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
   

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();
               }
           }
       }
   }
   
   

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

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

   После установки подключения клиент получает сообщения через подключение WebSocket. Клиент использует для client.MessageReceived.Subscribe(msg => ...)); прослушивания входящих сообщений.

3. Чтобы запустить подписчик, выполните следующую команду, заменив <Web-PubSub-connection-string> строка подключения скопированной ранее:

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

JavaScript

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

   mkdir subscriber
   cd subscriber
   npm init -y
   npm install --save ws
   npm install --save @azure/web-pubsub
   
   

2. Используйте 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 => ...)); прослушивания входящих сообщений.

3. Выполните следующую команду, заменив <Web-PubSub-connection-string> строка подключения скопированной ранее. Если вы используете командную оболочку Windows, вместо этого exportможно использоватьset.

   export WebPubSubConnectionString=<Web-PubSub-connection-string>
   node subscribe.js
   

Python

1. Сначала создайте каталог проекта с именем 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
   
   

2. Используйте 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() для прослушивания входящих сообщений.

3. Выполните следующую команду, заменив <Web-PubSub-connection-string> строка подключения скопированной ранее:

   python subscribe.py <Web-PubSub-connection-string> "myHub1"
   

Java

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

   mkdir pubsub
   cd pubsub
   

2. В каталоге 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
   

3. Добавьте в узел пакет 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.

4. Перейдите в каталог /src/main/java/com/webpubsub/quickstart .

5. Измените содержимое файла 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) для прослушивания входящих сообщений.

6. Чтобы запустить приложение подписчика, перейдите в каталог 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 для публикации сообщения в подключенном клиенте. Для этого проекта необходимо открыть другую командную оболочку.

C#

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
   

JavaScript

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

   mkdir publisher
   cd publisher
   npm init -y
   npm install --save @azure/web-pubsub
   
   

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

3. Чтобы отправить сообщение, выполните следующую команду, заменив <Web-PubSub-connection-string> строка подключения скопированной ранее. Если вы используете командную оболочку Windows, вместо этого exportможно использоватьset.

   export WebPubSubConnectionString=<Web-PubSub-connection-string>
   node publish "Hello World"
   

4. Вы можете увидеть, что подписчик получил сообщение:

   Message received: Hello World
   

Python

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

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

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

3. Чтобы отправить сообщение, выполните следующую команду, заменив <Web-PubSub-connection-string> строка подключения скопированной ранее.

   python publish.py <Web-PubSub-connection-string> "myHub1" "Hello World"
   

4. Проверьте предыдущую командную оболочку, чтобы подписчик получил сообщение:

   Received message: Hello World
   

Java

1. Перейдите в 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
   

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

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

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

4. Чтобы отправить сообщение, перейдите в каталог 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'"
   

5. Вы можете увидеть, что подписчик получил сообщение:

   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