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

Articolo
10/15/2024

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

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 Web PubSub per pubblicare messaggi usando l'SDK del servizio Web PubSub

Prerequisiti

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

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

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

.NET Core

Importante

Le stringa di connessione non elaborate vengono visualizzate in questo articolo solo a scopo dimostrativo.

Una stringa di connessione include le informazioni sull'autorizzazione necessarie all'applicazione per l'accesso al servizio Azure Web PubSub. La chiave di accesso all'interno della stringa di connessione è simile a una password radice per il servizio. Negli ambienti di produzione proteggere sempre le chiavi di accesso. Usare Azure Key Vault per gestire e ruotare le chiavi in modo sicuro e proteggere la connessione con WebPubSubServiceClient.

Evitare di distribuire le chiavi di accesso ad altri utenti, impostarle come hardcoded o salvarle in un file di testo normale accessibile ad altri. Ruotare le chiavi se si ritiene che siano state compromesse.

Predisporre l'ambiente

Interfaccia della riga di comando di Azure locale
Azure Cloud Shell

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

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

Aprire una shell dei comandi.
Eseguire l'aggiornamento all'ultima versione dell'interfaccia della riga di comando di Azure.
```
az upgrade
```
Installare l'estensione dell'interfaccia della riga di comando di Azure per Web PubSub.
```
az extension add --name webpubsub
```
Accedere all'interfaccia della riga di comando di Azure. Seguendo le richieste, immettere le credenziali di Azure.
```
az login
```

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 nella posizione eastus.

az group create --name myResourceGroup --location EastUS

1. Creare un'istanza di Azure Web PubSub

Creare un'istanza di Web PubSub

Per creare un'istanza Web PubSub nel gruppo di risorse creato, usare il comando az webpubsub create dell'interfaccia della riga di comando di Azure. Il comando seguente crea una risorsa Web PubSub gratuita nel gruppo di risorse myResourceGroup 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 proprietà seguenti:

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

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

Ottenere la stringa di connessione

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

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

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

Creare un client sottoscrittore

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

Le stringa di connessione non elaborate vengono visualizzate in questo articolo solo a scopo dimostrativo. Negli ambienti di produzione proteggere sempre le chiavi di accesso. Usare Azure Key Vault per gestire e ruotare le chiavi in modo sicuro e proteggere la connessione con WebPubSubServiceClient.

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 terzi che supporta connessioni WebSocket. È possibile usare qualsiasi API/libreria che supporti WebSocket.
- Il pacchetto SDK Azure.Messaging.WebPubSub 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
```

Sostituire il codice in Program.cs con il codice seguente che si connette 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. Concetti chiave contiene la spiegazione dettagliata dei termini usati in Web PubSub.

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

Una volta stabilita la connessione, il client riceve i messaggi tramite la connessione WebSocket. Il client usa client.MessageReceived.Subscribe(msg => ...)); per attendere i messaggi in arrivo.

Per avviare il sottoscrittore eseguire il programma seguente, sostituendo <Web-PubSub-connection-string> con la stringa di connessione copiata in precedenza:
```
dotnet run <Web-PubSub-connection-string> "myHub1"
```

Creare prima di tutto una directory di progetto denominata subscriber progetto e installare le dipendenze necessarie:
```
mkdir subscriber
cd subscriber
npm init -y
npm install --save ws
npm install --save @azure/web-pubsub
```
Usare l'API WebSocket per connettersi al servizio Web PubSub. Creare un file subscribe.js 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. Concetti chiave contiene la spiegazione dettagliata dei termini usati in Web PubSub.

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

Una volta stabilita la connessione, il client riceve i messaggi tramite la connessione WebSocket. Il client usa client.MessageReceived.Subscribe(msg => ...)); per attendere i messaggi in arrivo.
Usare il comando seguente, sostituendo <Web-PubSub-connection-string> con la stringa di connessione copiata in precedenza. Se si usa la shell dei comandi di Windows, è possibile usare set anziché export.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node subscribe.js
```

Creare prima di tutto una directory di progetto denominata subscriber progetto 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

Usare l'API WebSocket per connettersi al servizio Web PubSub. Creare un file subscribe.py 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. Concetti chiave contiene la spiegazione dettagliata dei termini usati in Web PubSub.

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

Una volta stabilita la connessione, il client riceverà i messaggi tramite la connessione WebSocket. Usare await ws.recv() per attendere i messaggi in arrivo.
Usare il comando seguente, sostituendo <Web-PubSub-connection-string> con la stringa di connessione copiata in precedenza:
```
python subscribe.py <Web-PubSub-connection-string> "myHub1"
```

Creare prima di tutto una directory di progetto denominata pubsub per questa esercitazione.
```
mkdir pubsub
cd pubsub
```

All'interno della directory pubsub 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

Aggiungere WebSocket e l'SDK Azure Web PubSub al nodo dependencies in pom.xml:
- azure-messaging-webpubsub: SDK del servizio Web PubSub per Java
- Java-WebSocket: SDK del 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.
Passare alla directory /src/main/java/com/webpubsub/quickstart.

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 Azure Web PubSub. Un hub è un'unità logica in Azure Web PubSub in cui è possibile pubblicare messaggi in un gruppo di client. Concetti chiave contiene la spiegazione dettagliata dei termini usati in Azure Web PubSub.

Una volta stabilita la connessione, il client riceverà i messaggi tramite la connessione WebSocket. Usare onMessage(String message) per attendere i messaggi in arrivo.

Per avviare l'app sottoscrittore, passare alla directory webpubsub-quickstart-subscriber e usare il comando seguente. Sostituire <Web-PubSub-connection-string> con la stringa di connessione copiata 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 publisher usando l'SDK Azure Web PubSub per pubblicare un messaggio nel client connesso. Per questo progetto è necessario aprire un'altra shell dei comandi.

Creare prima di tutto una directory di progetto denominata publisher progetto e installare le dipendenze necessarie:
```
mkdir publisher
cd publisher
dotnet new console
dotnet add package Azure.Messaging.WebPubSub
```

Aggiornare il file Program.cs per usare la classe WebPubSubServiceClient 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 chiamata SendToAllAsync() invia semplicemente un messaggio a tutti i client connessi nell'hub.

Inviare un messaggio usando il comando seguente. Sostituire <Web-PubSub-connection-string> con la stringa di connessione copiata in precedenza.
```
dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"
```
Assicurarsi che la shell dei comandi del sottoscrittore riceva il messaggio:
```
Message received: Hello World
```

Creare prima di tutto una directory di progetto denominata publisher progetto e installare le dipendenze necessarie:
```
mkdir publisher
cd publisher
npm init -y
npm install --save @azure/web-pubsub
```

Usare l'SDK Azure Web PubSub per pubblicare un messaggio nel servizio. Creare un file publish.js 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 chiamata service.sendToAll() invia semplicemente un messaggio a tutti i client connessi in un hub.

Per inviare un messaggio, usare il comando seguente, sostituendo <Web-PubSub-connection-string> con la stringa di connessione copiata in precedenza. Se si usa la shell dei comandi di Windows, è possibile usare set anziché export.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node publish "Hello World"
```
È possibile vedere che il sottoscrittore ha ricevuto il messaggio:
```
Message received: Hello World
```

Creare prima di tutto una directory di progetto denominata publisher progetto 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

Usare l'SDK Azure Web PubSub per pubblicare un messaggio nel servizio. Creare un file publish.py 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)

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

Per inviare un messaggio, usare il comando seguente, sostituendo <Web-PubSub-connection-string> con la stringa di connessione copiata in precedenza.
```
python publish.py <Web-PubSub-connection-string> "myHub1" "Hello World"
```
Controllare la shell dei comandi precedente per assicurarsi che il sottoscrittore abbia ricevuto il messaggio:
```
Received message: Hello World
```

Passare alla directory pubsub. Usare Maven per creare un'app console publisher webpubsub-quickstart-publisher 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

Aggiungere la dipendenza dell'SDK Azure Web PubSub nel nodo dependencies di pom.xml:

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

Usare l'SDK Azure Web PubSub 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 chiamata sendToAll() invia un messaggio a tutti i client connessi in un hub.

Per inviare un messaggio, passare alla directory webpubsub-quickstart-publisher ed eseguire il progetto usando il comando seguente. Sostituire <Web-PubSub-connection-string> con la stringa di connessione copiata 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'"
```
È possibile vedere 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 le 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>. Usare il comando seguente, sostituendo <CloudShellResourceGroup> con il nome del gruppo Cloud Shell.

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

Attenzione

L'eliminazione dei 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.

Controllare altre esercitazioni per approfondire come usare il servizio.

Esercitazione: Creare una chatroom semplice con Azure Web PubSub

Esplorare altri esempi di Azure Web PubSub

Condividi tramite

Prerequisiti

Predisporre l'ambiente

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

Creare un gruppo di risorse

1. Creare un'istanza di Azure Web PubSub

Creare un'istanza di Web PubSub

Ottenere la stringa di connessione

Creare un client sottoscrittore

2. Pubblicare messaggi con l'SDK del servizio

Pulizia

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

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

Prerequisiti

Predisporre l'ambiente

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

Creare un gruppo di risorse

1. Creare un'istanza di Azure Web PubSub

Creare un'istanza di Web PubSub

Ottenere la stringa di connessione

Creare un client sottoscrittore

2. Pubblicare messaggi con l'SDK del servizio

Pulizia

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive