Zelfstudie: Berichten publiceren en abonneren met webSocket-API en Azure Web PubSub-service-SDK

Artikel
03/08/2024

Met de Azure Web PubSub-service kunt u eenvoudig realtime webberichtentoepassingen bouwen. In deze zelfstudie leert u hoe u zich abonneert op de service met behulp van webSocket-API en berichten publiceert met behulp van de Web PubSub-service-SDK.

In deze zelfstudie leert u het volgende:

Een Web PubSub-service-exemplaar maken
Genereer de volledige URL om de WebSocket-verbinding tot stand te brengen
Een Web PubSub-abonneeclient maken voor het ontvangen van berichten met behulp van het standaard WebSocket-protocol
Een Web PubSub-uitgeverclient maken voor het publiceren van berichten met behulp van de Web PubSub-service-SDK

Vereisten

Maak een gratis account voor een Azure-abonnement.
Een Bash-opdrachtshell. Gebruik een lokale shell of de Bash-omgeving in Azure Cloud Shell.
Als deze wordt uitgevoerd op uw lokale computer , installeert u de Azure CLI.

U kunt de Windows cmd.exe-opdrachtshell gebruiken in plaats van een Bash-shell om de opdrachten in deze zelfstudie uit te voeren.

Als u het project op een lokale computer maakt, moet u de afhankelijkheden installeren voor de taal die u gebruikt:

.NET Core

Azure CLI instellen voor lokale ontwikkeling

Volg deze stappen om Azure CLI en uw projectomgeving in te stellen.

Open een opdrachtshell.
Voer een upgrade uit naar de nieuwste versie van de Azure CLI.
```
az upgrade
```
Installeer de Azure CLI-extensie voor Web PubSub.
```
az extension add --name webpubsub
```
Meld u aan bij Azure CLI. Voer na de aanwijzingen uw Azure-referenties in.
```
az login
```

Een brongroep maken

Een resourcegroep is een logische container waarin Azure-resources worden geïmplementeerd en beheerd. Gebruik de opdracht az group create om een resourcegroep te maken met de naam myResourceGroup op de eastus locatie.

az group create --name myResourceGroup --location EastUS

1. Een Azure Web PubSub-exemplaar maken

Een Web PubSub-exemplaar maken

Gebruik de azure CLI az webpubsub create command om een Web PubSub te maken in de resourcegroep die u hebt gemaakt. Met de volgende opdracht maakt u een gratis Web PubSub-resource onder de resourcegroep myResourceGroup inEastUS:

Elke Web PubSub-resource moet een unieke naam hebben. Vervang <uw unieke resourcenaam door de naam van uw Web PubSub-exemplaar> in de volgende opdracht.

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

In de uitvoer van deze opdracht ziet u eigenschappen van de zojuist gemaakte resource. Let op de onderstaande twee eigenschappen:

name: De Web PubSub-naam die u hebt opgegeven in de --name bovenstaande parameter.
hostName: In het voorbeeld is <your-unique-resource-name>.webpubsub.azure.com/de hostnaam .

Op dit moment is uw Azure-account de enige die gemachtigd is om bewerkingen uit te voeren op deze nieuwe resource.

De verbindingsreeks ophalen

Belangrijk

Een verbindingsreeks bevat de autorisatiegegevens die nodig zijn voor uw toepassing voor toegang tot de Azure Web PubSub-service. De toegangssleutel in de verbindingsreeks is vergelijkbaar met een hoofdwachtwoord voor uw service. In productieomgevingen moet u altijd voorzichtig zijn met het beveiligen van uw toegangssleutels. Gebruik Azure Key Vault om uw sleutels veilig te beheren en te roteren. Vermijd het distribueren van toegangssleutels naar andere gebruikers, het coderen ervan of het opslaan van ze ergens in tekst zonder opmaak die toegankelijk is voor anderen. Draai uw sleutels als u denkt dat ze mogelijk zijn aangetast.

Gebruik de opdracht Azure CLI az webpubsub key om de Verbinding maken ionString van de service op te halen. Vervang de <your-unique-resource-name> tijdelijke aanduiding door de naam van uw Azure Web PubSub-exemplaar.

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

Kopieer de verbindingsreeks om later te gebruiken.

Een abonneeclient maken

Clients maken verbinding met de Azure Web PubSub-service via het standaard WebSocket-protocol met behulp van JSON Web Token-verificatie (JWT ). De service-SDK biedt helpermethoden voor het genereren van het token. In deze zelfstudie genereert de abonnee het token rechtstreeks vanuit Verbinding maken ionString. In echte toepassingen verwerkt een toepassing aan de serverzijde meestal de verificatie-/autorisatiewerkstroom. Zie de zelfstudie Een chat-app bouwen voor een beter begrip van de werkstroom.

Maak eerst een projectmap met de naam subscriber van dit project en installeer de vereiste afhankelijkheden:
- Het pakket Websocket.Client is een pakket van derden dat WebSocket-verbindingen ondersteunt. U kunt elke API/bibliotheek gebruiken die ondersteuning biedt voor WebSocket.
- Het SDK-pakket Azure.Messaging.WebPubSub helpt bij het genereren van het JWT-token.
```
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
```

Vervang de code in de Program.cs code door de volgende code die verbinding maakt met de service:

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

De code maakt een WebSocket-verbinding die is verbonden met een hub in Web PubSub. Een hub is een logische eenheid in Web PubSub waar u berichten naar een groep clients kunt publiceren. De belangrijkste concepten bevatten de gedetailleerde uitleg over de termen die worden gebruikt in Web PubSub.

De Web PubSub-service maakt gebruik van JSON Web Token-verificatie (JWT ). De voorbeeldcode gebruikt WebPubSubServiceClient.GetClientAccessUri() in de Web PubSub SDK om een URL te genereren naar de service die de volledige URL met een geldig toegangstoken bevat.

Nadat de verbinding tot stand is gebracht, ontvangt uw client berichten via de WebSocket-verbinding. De client gebruikt client.MessageReceived.Subscribe(msg => ...)); om te luisteren naar binnenkomende berichten.

Als u de abonnee wilt starten, voert u de volgende opdracht uit, waarbij u <Web-PubSub-connection-string> de verbindingsreeks die u eerder hebt gekopieerd, vervangt:
```
dotnet run <Web-PubSub-connection-string> "myHub1"
```

Maak eerst een projectmap met de naam subscriber en installeer de vereiste afhankelijkheden:

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

Gebruik de WebSocket-API om verbinding te maken met de Web PubSub-service. Maak een subscribe.js bestand met de volgende code:
```
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();
```
De code maakt een WebSocket-verbinding die is verbonden met een hub in Web PubSub. Een hub is een logische eenheid in Web PubSub waar u berichten naar een groep clients kunt publiceren. De belangrijkste concepten bevatten de gedetailleerde uitleg over de termen die worden gebruikt in Web PubSub.

De Web PubSub-service maakt gebruik van JSON Web Token-verificatie (JWT ). De voorbeeldcode gebruikt WebPubSubServiceClient.GetClientAccessUri() in de Web PubSub SDK om een URL te genereren naar de service die de volledige URL met een geldig toegangstoken bevat.

Nadat de verbinding tot stand is gebracht, ontvangt uw client berichten via de WebSocket-verbinding. De client gebruikt client.MessageReceived.Subscribe(msg => ...)); om te luisteren naar binnenkomende berichten.
Voer de volgende opdracht uit, waarbij u <Web-PubSub-connection-string> de verbindingsreeks die u eerder hebt gekopieerd, vervangt. Als u windows-opdrachtshell gebruikt, kunt set u in plaats van export.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node subscribe.js
```

Maak eerst een projectmap met de naam subscriber en installeer de vereiste afhankelijkheden:

mkdir subscriber
cd subscriber
# Create venv
python -m venv env
# Activate venv
source ./env/bin/activate

pip install azure-messaging-webpubsubservice
pip install websockets

Gebruik de WebSocket-API om verbinding te maken met de Web PubSub-service. Maak een subscribe.py bestand met de volgende code:
```
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
```
De code maakt een WebSocket-verbinding die is verbonden met een hub in Web PubSub. Een hub is een logische eenheid in Web PubSub waar u berichten naar een groep clients kunt publiceren. De belangrijkste concepten bevatten de gedetailleerde uitleg over de termen die worden gebruikt in Web PubSub.

De Web PubSub-service maakt gebruik van JSON Web Token-verificatie (JWT ). De voorbeeldcode gebruikt WebPubSubServiceClient.GetClientAccessUri() in de Web PubSub SDK om een URL te genereren naar de service die de volledige URL met een geldig toegangstoken bevat.

Nadat de verbinding tot stand is gebracht, ontvangt uw client berichten via de WebSocket-verbinding. Gebruik await ws.recv() deze functie om te luisteren naar binnenkomende berichten.
Voer de volgende opdracht uit, waarbij u <Web-PubSub-connection-string> de verbindingsreeks die u eerder hebt gekopieerd, vervangt:
```
python subscribe.py <Web-PubSub-connection-string> "myHub1"
```

Maak eerst een projectmap met de naam pubsub voor deze zelfstudie.
```
mkdir pubsub
cd pubsub
```

Gebruik Maven in de map om een nieuwe console-app met de pubsub naam webpubsub-quickstart-subscriberte maken en ga vervolgens naar de map 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

Voeg WebSocket en Azure Web PubSub SDK toe aan het dependencies knooppunt in pom.xml:
- azure-messaging-webpubsub: Web PubSub-service-SDK voor Java
- Java-WebSocket: WebSocket-client-SDK voor 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 kunt u verbinding maken met de service en u abonneren op berichten via WebSocket-verbindingen. WebSocket is een full-duplex communicatiekanaal waarmee de service in realtime berichten naar uw client kan pushen. U kunt elke API of bibliotheek gebruiken die ondersteuning biedt voor WebSocket. Voor dit voorbeeld gebruiken we pakket Java-WebSocket.
Ga naar de map /src/main/java/com/webpubsub/quickstart .

Bewerk de inhoud van het App.java-bestand door de volgende code:

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

Met deze code maakt u een WebSocket-verbinding die is verbonden met een hub in Azure Web PubSub. Een hub is een logische eenheid in Azure Web PubSub waar u berichten kunt publiceren naar een groep clients. De belangrijkste concepten bevatten de gedetailleerde uitleg over de termen die worden gebruikt in Azure Web PubSub.

Nadat de verbinding tot stand is gebracht, ontvangt uw client berichten via de WebSocket-verbinding. Gebruik onMessage(String message) deze functie om te luisteren naar binnenkomende berichten.

Als u de abonnee-app wilt starten, gaat u naar de map webpubsub-quickstart-subscriber en voert u de volgende opdracht uit. Vervang <Web-PubSub-connection-string> door de verbindingsreeks die u eerder hebt gekopieerd.
```
mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1'"
```

2. Berichten publiceren met behulp van service-SDK

Maak een uitgever met behulp van de Azure Web PubSub SDK om een bericht te publiceren naar de verbonden client. Voor dit project moet u een andere opdrachtshell openen.

Maak eerst een projectmap met de naam publisher en installeer de vereiste afhankelijkheden:

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

Werk het Program.cs bestand bij om de WebPubSubServiceClient klasse te gebruiken en berichten naar de clients te verzenden.

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

De SendToAllAsync() oproep verzendt gewoon een bericht naar alle verbonden clients in de hub.

Verzend een bericht door de volgende opdracht uit te voeren. Vervang <Web-PubSub-connection-string> door de verbindingsreeks die u eerder hebt gekopieerd.
```
dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"
```
Controleer de opdrachtshell van de abonnee om te zien dat het bericht is ontvangen:
```
Message received: Hello World
```

Maak eerst een projectmap met de naam publisher en installeer de vereiste afhankelijkheden:
```
mkdir publisher
cd publisher
npm init -y
npm install --save @azure/web-pubsub
```

Gebruik de Azure Web PubSub SDK om een bericht naar de service te publiceren. Maak een publish.js bestand met de onderstaande code:

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

De service.sendToAll() oproep verzendt gewoon een bericht naar alle verbonden clients in een hub.

Als u een bericht wilt verzenden, voert u de volgende opdracht uit die wordt <Web-PubSub-connection-string> vervangen door de verbindingsreeks die u eerder hebt gekopieerd. Als u windows-opdrachtshell gebruikt, kunt set u in plaats van export.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node publish "Hello World"
```
U kunt zien dat de abonnee het bericht heeft ontvangen:
```
Message received: Hello World
```

Maak eerst een projectmap met de naam publisher en installeer de vereiste afhankelijkheden:

mkdir publisher
cd publisher
# Create venv
python -m venv env
# Active venv
source ./env/bin/activate

pip install azure-messaging-webpubsubservice

Gebruik de Azure Web PubSub SDK om een bericht naar de service te publiceren. Maak een publish.py bestand met de onderstaande code:

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)

Het send_to_all() bericht verzenden naar alle verbonden clients in een hub.

Als u een bericht wilt verzenden, voert u de volgende opdracht uit die wordt <Web-PubSub-connection-string> vervangen door de verbindingsreeks die u eerder hebt gekopieerd.
```
python publish.py <Web-PubSub-connection-string> "myHub1" "Hello World"
```
Controleer de vorige opdrachtshell op de melding dat de abonnee het bericht heeft ontvangen:
```
Received message: Hello World
```

Ga naar de pubsub map. Gebruik Maven om een uitgeverconsole-app webpubsub-quickstart-publisher te maken en ga naar de map 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

Voeg de Azure Web PubSub SDK-afhankelijkheid toe aan het dependencies knooppunt van pom.xml:

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

Gebruik de Azure Web PubSub SDK om een bericht naar de service te publiceren. Ga naar de map /src/main/java/com/webpubsub/quickstart , open het App.java-bestand in uw editor en vervang de inhoud door de volgende code:


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

De sendToAll() oproep verzendt een bericht naar alle verbonden clients in een hub.

Als u een bericht wilt verzenden, gaat u naar de map webpubsub-quickstart-publisher en voert u het project uit met behulp van de volgende opdracht. Vervang de <Web-PubSub-connection-string> verbindingsreeks die u eerder hebt gekopieerd.
```
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'"
```
U kunt zien dat de abonnee het bericht heeft ontvangen:
```
Message received: Hello World
```

Opschonen

U kunt de resources die u in deze quickstart hebt gemaakt verwijderen door de resourcegroep met deze resources te verwijderen.

az group delete --name myResourceGroup --yes

Als u niet van plan bent om Azure Cloud Shell te blijven gebruiken, kunt u kosten vermijden door de resourcegroep te verwijderen die het gekoppelde opslagaccount bevat. De resourcegroep heeft de naam cloud-shell-storage-<your-region>. Voer de volgende opdracht uit, waarbij u <CloudShellResourceGroup> de naam van de Cloud Shell-groep vervangt.

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

Let op

Als u resourcegroepen verwijdert, worden alle resources verwijderd, inclusief resources die buiten het bereik van deze zelfstudie zijn gemaakt.

Volgende stappen

In deze zelfstudie krijgt u een basisidee van het maken van verbinding met de Web PubSub-service en het publiceren van berichten naar de verbonden clients.

Bekijk andere zelfstudies voor meer informatie over het gebruik van de service.

Zelfstudie: Een chatroom maken met Azure Web PubSub

Meer Voorbeelden van Azure Web PubSub verkennen