Учебник: публикация и подписка на сообщения с помощью 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 Web PubSub. Ключ доступа в строке подключения аналогичен паролю привилегированного пользователя для службы. В рабочих средах всегда защищать ключи доступа. Используйте Azure Key Vault для безопасного управления ключами и защиты подключения.WebPubSubServiceClient

Старайтесь не распространять ключи доступа среди других пользователей, жестко программировать их или где-то сохранять в виде обычного текста в открытом доступе для других пользователей. Меняйте свои ключи постоянно, если предполагаете, что они могут быть подобраны.

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

Локальный интерфейс командной строки 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

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

Необработанные строка подключения отображаются в этой статье только для демонстрационных целей. В рабочих средах всегда защищать ключи доступа. Используйте Azure Key Vault для безопасного управления ключами и защиты подключения.WebPubSubServiceClient

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