Esercitazione: Pubblicare e sottoscrivere messaggi usando l'API WebSocket e l'SDK del servizio Web PubSub di Azure

Il servizio Web PubSub di Azure consente di creare facilmente applicazioni di messaggistica Web in tempo reale. In questa esercitazione si apprenderà come sottoscrivere il servizio usando l'API WebSocket e pubblicare messaggi usando Web PubSub SERVICE SDK.

In questa esercitazione apprenderai a:

• Creare un'istanza del servizio Web PubSub
• Generare l'URL completo per stabilire la connessione WebSocket
• Creare un client sottoscrittore Web PubSub per ricevere messaggi usando il protocollo WebSocket standard
• Creare un client di pubblicazione PubSub Web per pubblicare messaggi con Web PubSub SERVICE SDK

Prerequisiti

• Una sottoscrizione di Azure, creare un account gratuito.
• Shell dei comandi Bash. Usare una shell locale o l'ambiente Bash in Azure Cloud Shell.
• Se in esecuzione nel computer locale installare l'interfaccia della riga di comando di Azure.

È possibile usare la shell dei comandi di Windows cmd.exe anziché una shell Bash per eseguire i comandi in questa esercitazione.

Se si crea il progetto in un computer locale, è necessario installare le dipendenze per la lingua in uso:

C#

.NET Core

JavaScript

Node.js

Python

Python

Java

• Java Development Kit (JDK).
• Apache Maven

Predisporre l'ambiente

Interfaccia della riga di comando di Azure locale

Configurazione dell'interfaccia della riga di comando di Azure per lo sviluppo locale

Seguire questa procedura per configurare l'interfaccia della riga di comando di Azure e l'ambiente del progetto.

1. Aprire una shell dei comandi.

2. Eseguire l'aggiornamento alla versione più recente dell'interfaccia della riga di comando di Azure.

   az upgrade
   

3. Installare l'estensione dell'interfaccia della riga di comando di Azure per Web PubSub.

   az extension add --name webpubsub
   

4. Accedere all'interfaccia della riga di comando di Azure. Seguendo le istruzioni, immettere le credenziali di Azure.

   az login
   

Azure Cloud Shell

Creare un gruppo di risorse

Un gruppo di risorse è un contenitore logico in cui vengono distribuite e gestite le risorse di Azure. Usare il comando az group create per creare un gruppo di risorse denominato myResourceGroup nel eastus percorso.

az group create --name myResourceGroup --location EastUS

---

1. Creare un'istanza di PubSub Web di Azure

Creare un'istanza di Web PubSub

Usare il comando az webpubsub create dell'interfaccia della riga di comando di Azure per creare un Web PubSub nel gruppo di risorse creato. Il comando seguente crea una risorsa PubSub Web gratuita nel gruppo myResourceGroup di risorse in EastUS:

Ogni risorsa Web PubSub deve avere un nome univoco. Sostituire <your-unique-resource-name> con il nome dell'istanza di Web PubSub nel comando seguente.

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

L'output di questo comando mostra le proprietà della risorsa appena creata. Prendere nota delle due proprietà elencate di seguito:

• name: nome Web PubSub specificato nel --name parametro precedente.
• hostName: nell'esempio il nome host è <your-unique-resource-name>.webpubsub.azure.com/.

A questo punto, l'account Azure è l'unico autorizzato a eseguire qualsiasi operazione su questa nuova risorsa.

Ottenere la stringa di connessione

Importante

Un stringa di connessione include le informazioni di autorizzazione necessarie per l'applicazione per accedere al servizio Web PubSub di Azure. La chiave di accesso all'interno del stringa di connessione è simile a una password radice per il servizio. Negli ambienti di produzione, prestare sempre attenzione a proteggere le chiavi di accesso. Usare Azure Key Vault per gestire e ruotare le chiavi in modo sicuro. Evitare di distribuire chiavi di accesso ad altri utenti, hardcodedarli o salvarli in qualsiasi punto del testo normale accessibile ad altri utenti. Ruotare le chiavi se si ritiene che siano state compromesse.

Usare il comando az webpubsub key dell'interfaccia della riga di comando di Azure per ottenere il Connessione ionString del servizio. Sostituire il <your-unique-resource-name> segnaposto con il nome dell'istanza di PubSub Web di Azure.

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

Copiare il stringa di connessione da usare in un secondo momento.

Creare un client sottoscrittore

I client si connettono al servizio Web PubSub di Azure tramite il protocollo WebSocket standard usando l'autenticazione JWT (JSON Web Token). L'SDK del servizio fornisce metodi helper per generare il token. In questa esercitazione il sottoscrittore genera direttamente il token da Connessione ionString. Nelle applicazioni reali, un'applicazione lato server gestisce in genere il flusso di lavoro di autenticazione/autorizzazione. Per comprendere meglio il flusso di lavoro, vedere l'esercitazione Creare un'app di chat.

C#

1. Creare prima di tutto una directory di progetto denominata subscriber per questo progetto e installare le dipendenze necessarie:

   • Il pacchetto Websocket.Client è un pacchetto di terze parti che supporta le connessioni WebSocket. È possibile usare qualsiasi API/libreria che supporti WebSocket.
   • Il pacchetto Azure.Messaging.WebPubSub SDK consente di generare il token 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. Sostituire il codice in Program.cs con il codice seguente che si connetterà al servizio:

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

   Il codice crea una connessione WebSocket connessa a un hub in Web PubSub. Un hub è un'unità logica in Web PubSub in cui è possibile pubblicare messaggi in un gruppo di client. I concetti chiave contengono la spiegazione dettagliata dei termini usati in Web PubSub.

   Il servizio Web PubSub usa l'autenticazione JWT (JSON Web Token). Il codice di esempio usa WebPubSubServiceClient.GetClientAccessUri() in Web PubSub SDK per generare un URL per il servizio che contiene l'URL completo con un token di accesso valido.

   Dopo aver stabilito la connessione, il client riceve i messaggi tramite la connessione WebSocket. Il client usa per restare in ascolto client.MessageReceived.Subscribe(msg => ...)); dei messaggi in arrivo.

3. Per avviare il sottoscrittore, eseguire il comando seguente sostituendo <Web-PubSub-connection-string> con il stringa di connessione copiato in precedenza:

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

JavaScript

1. Creare prima di tutto una directory di progetto denominata subscriber e installare le dipendenze necessarie:

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

2. Usare l'API WebSocket per connettersi al servizio Web PubSub. Creare un subscribe.js file con il codice seguente:

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

   Il codice crea una connessione WebSocket connessa a un hub in Web PubSub. Un hub è un'unità logica in Web PubSub in cui è possibile pubblicare messaggi in un gruppo di client. I concetti chiave contengono la spiegazione dettagliata dei termini usati in Web PubSub.

   Il servizio Web PubSub usa l'autenticazione JWT (JSON Web Token). Il codice di esempio usa WebPubSubServiceClient.GetClientAccessUri() in Web PubSub SDK per generare un URL per il servizio che contiene l'URL completo con un token di accesso valido.

   Dopo aver stabilito la connessione, il client riceve i messaggi tramite la connessione WebSocket. Il client usa per restare in ascolto client.MessageReceived.Subscribe(msg => ...)); dei messaggi in arrivo.

3. Eseguire il comando seguente sostituendo <Web-PubSub-connection-string> con il stringa di connessione copiato in precedenza. Se si usa la shell dei comandi di exportWindows, è possibile usare set anziché .

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

Python

1. Creare prima di tutto una directory di progetto denominata subscriber e installare le dipendenze necessarie:

   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. Usare l'API WebSocket per connettersi al servizio Web PubSub. Creare un subscribe.py file con il codice seguente:

   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
   
   

   Il codice crea una connessione WebSocket connessa a un hub in Web PubSub. Un hub è un'unità logica in Web PubSub in cui è possibile pubblicare messaggi in un gruppo di client. I concetti chiave contengono la spiegazione dettagliata dei termini usati in Web PubSub.

   Il servizio Web PubSub usa l'autenticazione JWT (JSON Web Token). Il codice di esempio usa WebPubSubServiceClient.GetClientAccessUri() in Web PubSub SDK per generare un URL per il servizio che contiene l'URL completo con un token di accesso valido.

   Dopo aver stabilito la connessione, il client riceverà messaggi tramite la connessione WebSocket. Usare await ws.recv() per ascoltare i messaggi in arrivo.

3. Eseguire il comando seguente sostituendo <Web-PubSub-connection-string> con il stringa di connessione copiato in precedenza:

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

Java

1. Creare prima di tutto una directory di progetto denominata pubsub per questa esercitazione.

   mkdir pubsub
   cd pubsub
   

2. All'interno della pubsub directory usare Maven per creare una nuova app console denominata webpubsub-quickstart-subscriber, quindi passare alla directory 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. Aggiungere WebSocket e Azure Web PubSub SDK al dependencies nodo in pom.xml:

   • azure-messaging-webpubsub: Sdk del servizio Web PubSub per Java
   • Java-WebSocket: SDK client WebSocket per 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>
   
   

   In Web PubSub è possibile connettersi al servizio e sottoscrivere i messaggi tramite connessioni WebSocket. WebSocket è un canale di comunicazione full-duplex che consente al servizio di eseguire il push dei messaggi al client in tempo reale. È possibile usare qualsiasi API o libreria che supporti WebSocket. Per questo esempio viene usato il pacchetto Java-WebSocket.

4. Passare alla directory /src/main/java/com/webpubsub/quickstart .

5. Modificare sostituire il contenuto del file App.java con il codice seguente:

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

   Questo codice crea una connessione WebSocket connessa a un hub in PubSub Web di Azure. Un hub è un'unità logica in PubSub Web di Azure in cui è possibile pubblicare messaggi in un gruppo di client. I concetti chiave contengono la spiegazione dettagliata dei termini usati in Azure Web PubSub.

   Il servizio Web PubSub usa l'autenticazione JWT (JSON Web Token). Il codice di esempio usa WebPubSubServiceClient.GetClientAccessUri() in Web PubSub SDK per generare un URL per il servizio che contiene l'URL completo con un token di accesso valido.

   Dopo aver stabilito la connessione, il client riceverà messaggi tramite la connessione WebSocket. Usare onMessage(String message) per ascoltare i messaggi in arrivo.

6. Per avviare l'app sottoscrittore, passare alla directory webpubsub-quickstart-subscriber ed eseguire il comando seguente. Sostituire <Web-PubSub-connection-string> con il stringa di connessione copiato in precedenza.

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

2. Pubblicare messaggi con l'SDK del servizio

Creare un server di pubblicazione usando Azure Web PubSub SDK per pubblicare un messaggio nel client connesso. Per questo progetto, è necessario aprire un'altra shell dei comandi.

C#

1. Creare prima di tutto una directory di progetto denominata publisher e installare le dipendenze necessarie:

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

2. Aggiornare il Program.cs file per usare la WebPubSubServiceClient classe e inviare messaggi ai client.

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

   La SendToAllAsync() chiamata invia semplicemente un messaggio a tutti i client connessi nell'hub.

3. Inviare un messaggio eseguendo il comando seguente. Sostituire <Web-PubSub-connection-string> con il stringa di connessione copiato in precedenza.

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

4. Controllare la shell dei comandi del sottoscrittore per verificare che abbia ricevuto il messaggio:

   Message received: Hello World
   

JavaScript

1. Creare prima di tutto una directory di progetto denominata publisher e installare le dipendenze necessarie:

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

2. Usare Azure Web PubSub SDK per pubblicare un messaggio nel servizio. Creare un publish.js file con il codice seguente:

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

   La service.sendToAll() chiamata invia semplicemente un messaggio a tutti i client connessi in un hub.

3. Per inviare un messaggio, eseguire il comando seguente sostituendo <Web-PubSub-connection-string> con il stringa di connessione copiato in precedenza. Se si usa la shell dei comandi di exportWindows, è possibile usare set anziché .

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

4. È possibile notare che il sottoscrittore ha ricevuto il messaggio:

   Message received: Hello World
   

Python

1. Creare prima di tutto una directory di progetto denominata publisher e installare le dipendenze necessarie:

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

2. Usare Azure Web PubSub SDK per pubblicare un messaggio nel servizio. Creare un publish.py file con il codice seguente:

   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)
   

   Invia send_to_all() il messaggio a tutti i client connessi in un hub.

3. Per inviare un messaggio, eseguire il comando seguente sostituendo <Web-PubSub-connection-string> con il stringa di connessione copiato in precedenza.

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

4. Controllare la shell dei comandi precedente in modo che il sottoscrittore abbia ricevuto il messaggio:

   Received message: Hello World
   

Java

1. Passare alla pubsub directory . Usare Maven per creare un'app webpubsub-quickstart-publisher console di pubblicazione e passare alla directory 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. Aggiungere la dipendenza di Azure Web PubSub SDK nel dependencies nodo di pom.xml:

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

3. Usare Azure Web PubSub SDK per pubblicare un messaggio nel servizio. Passare alla directory /src/main/java/com/webpubsub/quickstart , aprire il file App.java nell'editor e sostituire il contenuto con il codice seguente:

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

   La sendToAll() chiamata invia un messaggio a tutti i client connessi in un hub.

4. Per inviare un messaggio, passare alla directory webpubsub-quickstart-publisher ed eseguire il progetto usando il comando seguente. <Web-PubSub-connection-string> Sostituire con il stringa di connessione copiato in precedenza.

   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. È possibile notare che il sottoscrittore ha ricevuto il messaggio:

   Message received: Hello World
   

Pulizia

È possibile eliminare le risorse create in questa guida introduttiva eliminando il gruppo di risorse che li contiene.

az group delete --name myResourceGroup --yes

Se non si prevede di continuare a usare Azure Cloud Shell, è possibile evitare di accumulare costi eliminando il gruppo di risorse che contiene l'account di archiviazione associato. Il gruppo di risorse è denominato cloud-shell-storage-<your-region>. Eseguire il comando seguente, sostituendo <CloudShellResourceGroup> con il nome del gruppo di Cloud Shell.

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

Attenzione

L'eliminazione di gruppi di risorse eliminerà tutte le risorse, incluse le risorse create all'esterno dell'ambito di questa esercitazione.

Passaggi successivi

Questa esercitazione offre un'idea di base su come connettersi al servizio Web PubSub e pubblicare messaggi ai client connessi.

Vedere altre esercitazioni per approfondire come usare il servizio.

Esercitazione: Creare una chatroom con PubSub Web di Azure

Esplorare altri esempi di PubSub Web di Azure