Kurz: Publikování a přihlášení k odběru zpráv pomocí rozhraní WEBSocket API a sady SDK služby Azure Web PubSub

Služba Azure Web PubSub umožňuje snadno vytvářet aplikace pro zasílání zpráv v reálném čase. V tomto kurzu se dozvíte, jak se přihlásit k odběru služby pomocí rozhraní WebSocket API a publikovat zprávy pomocí sady SDK služby Web PubSub.

V tomto návodu se naučíte, jak:

• Vytvoření instance služby Web PubSub
• Vygenerování úplné adresy URL pro navázání připojení WebSocket
• Vytvoření klienta odběratele Web PubSub pro příjem zpráv pomocí standardního protokolu WebSocket
• Vytvoření klienta vydavatele Web PubSub pro publikování zpráv pomocí sady SDK služby Web PubSub

Prerequisites

• Předplatné Azure, vytvořte si bezplatný účet.
• Příkazové prostředí Bash. Použijte buď místní prostředí, nebo prostředí Bash v Azure Cloud Shellu.
• Pokud běží na místním počítači , nainstalujte Azure CLI.

Ke spuštění příkazů v tomto kurzu můžete místo prostředí Bash použít příkazové prostředí windows cmd.exe.

Pokud projekt vytváříte na místním počítači, musíte nainstalovat závislosti pro jazyk, který používáte:

C#

.NET Core

JavaScript

Node.js

Python

Python

Java

• Java Development Kit (JDK).
• Apache Maven

Important

Surové připojovací řetězce jsou v tomto článku uvedeny jen pro demonstrační účely.

Připojovací řetězec obsahuje informace o autorizaci potřebné pro to, aby vaše aplikace měla přístup ke službě Azure Web PubSub. Přístupový klíč uvnitř připojovacího řetězce je podobný kořenovému heslu pro vaši službu. V produkčních prostředích vždy chraňte přístupové klíče. Použijte Azure Key Vault k bezpečné správě a rotaci klíčů a zabezpečte své připojení pomocí WebPubSubServiceClient.

Vyhněte se distribuci přístupových klíčů ostatním uživatelům, jejich pevnému kódování nebo jejich uložení kdekoli ve formátu prostého textu, který je přístupný ostatním uživatelům. Otočte klíče, pokud se domníváte, že mohly být ohroženy.

Příprava prostředí

Místní Azure CLI

Nastavení Azure CLI pro místní vývoj

Pomocí těchto kroků nastavte Azure CLI a prostředí vašeho projektu.

1. Otevřete příkazové prostředí.

2. Upgradujte na nejnovější verzi Azure CLI.

   az upgrade
   

3. Nainstalujte rozšíření Azure CLI pro Web PubSub.

   az extension add --name webpubsub
   

4. Přihlaste se k Azure CLI. Po zobrazení výzvy zadejte své přihlašovací údaje Azure.

   az login
   

Azure Cloud Shell

Vytvoření skupiny zdrojů

Skupina prostředků je logický kontejner, ve kterém se nasazují a spravují prostředky Azure. Pomocí příkazu az group create vytvořte skupinu prostředků s názvem myResourceGroup v eastus umístění.

az group create --name myResourceGroup --location EastUS

---

1. Vytvoření instance Azure Web PubSub

Vytvořte instanci Web PubSub

Pokud chcete vytvořit instanci Web PubSub ve skupině prostředků, kterou jste vytvořili, použijte příkaz Azure CLI az webpubsub create . Následující příkaz vytvoří prostředek Free Web PubSub ve skupině myResourceGroup prostředků v EastUS:

Každý prostředek Web PubSub musí mít jedinečný název. Nahraďte <your-unique-resource-name> názvem vaší instance Web PubSub v následujícím příkazu.

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

Výstup tohoto příkazu ukazuje vlastnosti nově vytvořeného zdroje. Poznamenejte si následující vlastnosti:

• name: Název web pubSub, který jste zadali v parametru --name výše.
• hostName: V příkladu je <your-unique-resource-name>.webpubsub.azure.com/název hostitele .

V tuto chvíli je váš účet Azure jediný, který má povolení provádět jakékoli operace s tímto novým zdrojem.

Získejte připojovací řetězec

K získání připojovacího řetězce služby použijte příkaz azure CLI az webpubsub key. <your-unique-resource-name> Zástupný symbol nahraďte názvem vaší instance Azure Web PubSub.

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

Zkopírujte připojovací řetězec pro pozdější použití.

Vytvořit klienta odběratele

Klienti se připojují ke službě Azure Web PubSub prostřednictvím standardního protokolu WebSocket pomocí ověřování JSON Web Token (JWT ). Sada SDK služby poskytuje pomocné metody pro vygenerování tokenu. V tomto kurzu odběratel přímo vygeneruje token z ConnectionString. V reálných aplikacích obvykle aplikace na straně serveru zpracovává pracovní postup ověřování/autorizace. Pokud chcete lépe porozumět pracovnímu postupu, podívejte se na kurz Vytvoření chatovací aplikace.

Surové připojovací řetězce jsou v tomto článku uvedeny jen pro demonstrační účely. V produkčních prostředích vždy chraňte přístupové klíče. Použijte Azure Key Vault k bezpečné správě a rotaci klíčů a zabezpečte své připojení pomocí WebPubSubServiceClient.

C#

1. Nejprve vytvořte adresář projektu s názvem subscriber pro tento projekt a nainstalujte požadované závislosti:

   • Balíček Websocket.Client je balíček třetí strany podporující připojení WebSocket. Můžete použít libovolné rozhraní API nebo knihovnu, která podporuje WebSocket.
   • Balíček Azure.Messaging.WebPubSub SDK pomáhá generovat 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. Nahraďte kód v Program.cs následujícím kódem, který se připojuje ke službě:

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

   Kód vytvoří připojení WebSocket, které je připojeno k centru ve službě Web PubSub. Hub je logická jednotka v Web PubSub, kde můžete publikovat zprávy do skupiny klientů. Klíčové koncepty obsahuje podrobné vysvětlení termínů použitých ve službě Web PubSub.

   Služba Web PubSub používá ověřování pomocí webového tokenu JSON (JWT ). Ukázkový kód používá WebPubSubServiceClient.GetClientAccessUri() v sadě Web PubSub SDK k vygenerování adresy URL služby, která obsahuje úplnou adresu URL s platným přístupovým tokenem.

   Po navázání připojení klient obdrží zprávy prostřednictvím připojení WebSocket. Klient používá client.MessageReceived.Subscribe(msg => ...)); k naslouchání příchozím zprávům.

3. Pokud chcete spustit odběratele, spusťte následující příkaz, který nahradíte <Web-PubSub-connection-string> připojovacím řetězcem, který jste zkopírovali dříve:

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

JavaScript

1. Nejprve vytvořte adresář projektu s názvem subscriber a nainstalujte požadované závislosti:

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

2. Pomocí rozhraní WEBSocket API se připojte ke službě Web PubSub. Vytvořte subscribe.js soubor s následujícím kódem:

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

   Kód vytvoří připojení WebSocket, které je připojeno k centru ve službě Web PubSub. Hub je logická jednotka v Web PubSub, kde můžete publikovat zprávy do skupiny klientů. Klíčové koncepty obsahuje podrobné vysvětlení termínů použitých ve službě Web PubSub.

   Služba Web PubSub používá ověřování pomocí webového tokenu JSON (JWT ). Ukázkový kód používá WebPubSubServiceClient.GetClientAccessUri() v sadě Web PubSub SDK k vygenerování adresy URL služby, která obsahuje úplnou adresu URL s platným přístupovým tokenem.

   Po navázání připojení klient obdrží zprávy prostřednictvím připojení WebSocket. Klient používá client.MessageReceived.Subscribe(msg => ...)); k naslouchání příchozím zprávům.

3. Spuštěním následujícího příkazu nahraďte <Web-PubSub-connection-string> připojovacím řetězcem, který jste zkopírovali dříve. Pokud používáte příkazové prostředí Windows, můžete místo něj setpoužít export .

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

Python

1. Nejprve vytvořte adresář projektu s názvem subscriber a nainstalujte požadované závislosti:

   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. Pomocí rozhraní WEBSocket API se připojte ke službě Web PubSub. Vytvořte subscribe.py soubor s následujícím kódem:

   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
   
   

   Kód vytvoří připojení WebSocket, které je připojeno k centru ve službě Web PubSub. Hub je logická jednotka v Web PubSub, kde můžete publikovat zprávy do skupiny klientů. Klíčové koncepty obsahuje podrobné vysvětlení termínů použitých ve službě Web PubSub.

   Služba Web PubSub používá ověřování pomocí webového tokenu JSON (JWT ). Ukázkový kód používá WebPubSubServiceClient.GetClientAccessUri() v sadě Web PubSub SDK k vygenerování adresy URL služby, která obsahuje úplnou adresu URL s platným přístupovým tokenem.

   Po navázání připojení klient obdrží zprávy prostřednictvím připojení WebSocket. Pomocí await ws.recv() naslouchejte příchozím zprávám.

3. Spusťte následující příkaz, který nahradíte <Web-PubSub-connection-string> připojovacím řetězcem, který jste zkopírovali dříve:

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

Java

1. Nejprve vytvořte adresář projektu s názvem pubsub pro tento kurz.

   mkdir pubsub
   cd pubsub
   

2. V adresáři pubsub použijte Maven k vytvoření nové konzolové aplikace s názvem webpubsub-quickstart-subscriber, a poté přejděte do adresáře 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. Přidejte sadu WebSocket a SDK pro Azure Web PubSub do uzlu dependencies:

   • azure-messaging-webpubsub: SDK služby Web PubSub pro Javu
   • Java-WebSocket: Klientská sada SDK protokolu WebSocket pro Javu

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

   Ve službě Web PubSub se můžete připojit ke službě a přihlásit se k odběru zpráv prostřednictvím připojení WebSocket. WebSocket je plně duplexní komunikační kanál, který službě umožňuje odesílat zprávy klientovi v reálném čase. Můžete použít libovolné rozhraní API nebo knihovnu, která podporuje Protokol WebSocket. Pro tuto ukázku používáme balíček Java-WebSocket.

4. Přejděte do adresáře /src/main/java/com/webpubsub/quickstart .

5. Obsah souboru App.java nahraďte následujícím kódem:

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

   Tento kód vytvoří připojení WebSocket, které je připojené k centru ve službě Azure Web PubSub. Centrum je logická jednotka ve službě Azure Web PubSub, kde můžete publikovat zprávy do skupiny klientů. Klíčové koncepty obsahují podrobné vysvětlení termínů používaných ve službě Azure Web PubSub.

   Služba Web PubSub používá ověřování pomocí webového tokenu JSON (JWT ). Ukázkový kód používá WebPubSubServiceClient.GetClientAccessUri() v sadě Web PubSub SDK k vygenerování adresy URL služby, která obsahuje úplnou adresu URL s platným přístupovým tokenem.

   Po navázání připojení klient obdrží zprávy prostřednictvím připojení WebSocket. Pomocí onMessage(String message) naslouchejte příchozím zprávám.

6. Pokud chcete spustit aplikaci odběratele, přejděte do adresáře webpubsub-quickstart-subscriber a spusťte následující příkaz. Nahraďte <Web-PubSub-connection-string> připojovacím řetězcem, který jste zkopírovali dříve.

   mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1'"
   

2. Publikování zpráv pomocí sady SDK služby

Vytvořte vydavatele pomocí sady Azure Web PubSub SDK k publikování zprávy do připojeného klienta. Pro tento projekt je potřeba otevřít další příkazové prostředí.

C#

1. Nejprve vytvořte adresář projektu s názvem publisher a nainstalujte požadované závislosti:

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

2. Program.cs Aktualizujte soubor tak, aby používal WebPubSubServiceClient třídu a odesílal zprávy klientům.

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

   Volání SendToAllAsync() jednoduše odešle zprávu všem připojeným klientům v centru.

3. Odešlete zprávu spuštěním následujícího příkazu. Nahraďte <Web-PubSub-connection-string> připojovacím řetězcem, který jste zkopírovali dříve.

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

4. Ověřte, že příkazové prostředí odběratele obdrží zprávu:

   Message received: Hello World
   

JavaScript

1. Nejprve vytvořte adresář projektu s názvem publisher a nainstalujte požadované závislosti:

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

2. Pomocí sady AZURE Web PubSub SDK publikujte zprávu do služby. Vytvořte publish.js soubor s následujícím kódem:

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

   Volání service.sendToAll() jednoduše odešle zprávu všem připojeným klientům v centru.

3. Pokud chcete odeslat zprávu, spusťte následující příkaz, který nahradíte <Web-PubSub-connection-string> připojovacím řetězcem, který jste zkopírovali dříve. Pokud používáte příkazové prostředí Windows, můžete místo něj setpoužít export .

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

4. Uvidíte, že odběratel obdržel zprávu:

   Message received: Hello World
   

Python

1. Nejprve vytvořte adresář projektu s názvem publisher a nainstalujte požadované závislosti:

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

2. Pomocí sady Azure Web PubSub SDK publikujte zprávu do služby. Vytvořte publish.py soubor s následujícím kódem:

   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)
   

   Zpráva send_to_all() se odešle všem připojeným klientům v centru.

3. Pokud chcete odeslat zprávu, spusťte následující příkaz, který nahradíte <Web-PubSub-connection-string> připojovacím řetězcem, který jste zkopírovali dříve.

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

4. Zkontrolujte předchozí příkazové prostředí, ve které odběratel obdržel zprávu:

   Received message: Hello World
   

Java

1. Přejděte do pubsub adresáře. Pomocí Mavenu vytvořte konzolovou aplikaci webpubsub-quickstart-publisher vydavatele a přejděte do adresáře 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. Přidejte závislost sady Azure Web PubSub SDK do dependencies uzlu pom.xml:

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

3. Pomocí sady Azure Web PubSub SDK publikujte zprávu do služby. Přejděte do adresáře /src/main/java/com/webpubsub/quickstart , otevřete soubor App.java v editoru a nahraďte obsah následujícím kódem:

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

   Volání sendToAll() odešle zprávu všem připojeným klientům v centru.

4. Pokud chcete odeslat zprávu, přejděte do adresáře webpubsub-quickstart-publisher a spusťte projekt pomocí následujícího příkazu. Nahraďte <Web-PubSub-connection-string> připojovacím řetězcem, který jste zkopírovali dříve.

   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. Uvidíte, že odběratel obdržel zprávu:

   Message received: Hello World
   

Cleanup

Prostředky, které jste vytvořili v tomto rychlém startu, můžete odstranit odstraněním skupiny prostředků, která je obsahuje.

az group delete --name myResourceGroup --yes

Pokud nechcete azure Cloud Shell dál používat, můžete se vyhnout kumulování nákladů odstraněním skupiny prostředků, která obsahuje přidružený účet úložiště. Skupina prostředků má název cloud-shell-storage-<your-region>. Spusťte následující příkaz a nahraďte <CloudShellResourceGroup> názvem skupiny Cloud Shellu.

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

Caution

Odstraněním skupin prostředků se odstraní všechny prostředky, včetně prostředků vytvořených mimo rozsah tohoto kurzu.

Další kroky

Tento kurz vám poskytne základní představu o tom, jak se připojit ke službě Web PubSub a publikovat zprávy do připojených klientů.

Projděte si další kurzy, ve které se dozvíte, jak službu používat.

Kurz: Vytvoření chatovací místnosti pomocí azure Web PubSub

Prozkoumání dalších ukázek Azure Web PubSub