Tutoriel : publier et s’abonner à des messages à l’aide de l’API WebSocket et du kit de développement logiciel (SDK) du service Azure Web PubSub

Article
09/03/2024

Le service Azure Web PubSub vous aide à créer facilement des applications web de messagerie en temps réel. Dans ce tutoriel, vous découvrez comment vous abonner au service en utilisant l’API WebSocket et comment publier des messages en utilisant le Kit de développement logiciel (SDK) du service Web PubSub.

Dans ce tutoriel, vous allez apprendre à :

Créer une instance de service Azure Web PubSub
Générer l’URL complète pour établir la connexion WebSocket
Créer un client abonné Web PubSub pour recevoir des messages en utilisant le protocole WebSocket standard
Créer un client éditeur Web PubSub pour publier des messages en utilisant le Kit de développement logiciel (SDK) du service Web PubSub

Prérequis

Créez un compte gratuit d’abonnement à Azure.
Un interpréteur de commandes Bash. Utilisez un interpréteur de commandes local ou l’environnement Bash dans Azure Cloud Shell.
En cas d’exécution sur votre ordinateur local, Installez Azure CLI.

Vous pouvez utiliser l’interpréteur de commandes Windows cmd.exe au lieu d’un interpréteur de commandes Bash pour exécuter les commandes de ce tutoriel.

Si vous créez le projet sur une machine locale, vous devez installer les dépendances pour le langage que vous utilisez :

.NET Core

Configurer Azure CLI pour le développement local

Effectuez les étapes suivantes pour configurer Azure CLI et l’environnement de votre projet.

Ouvrez un interpréteur de commandes.
Effectuez une mise à niveau vers la dernière version d’Azure CLI.
```
az upgrade
```
Installez l’extension Azure CLI pour Web PubSub.
```
az extension add --name webpubsub
```
Connectez-vous à Azure CLI. Après les invites, entrez vos informations d’identification Azure.
```
az login
```

Créer un groupe de ressources

Un groupe de ressources est un conteneur logique dans lequel les ressources Azure sont déployées et gérées. Utilisez la commande az group create pour créer un groupe de ressources nommé myResourceGroup à l’emplacement eastus.

az group create --name myResourceGroup --location EastUS

1. Créer une instance Azure Web PubSub

Créer une instance Web PubSub

Pour créer une instance Web PubSub dans le groupe de ressources que vous avez créé, utilisez la commande Azure CLI az webpubsub create. La commande suivante crée une ressource Web PubSub GRATUITE sous le groupe de ressources myResourceGroup dans la zone EastUS :

Chaque ressource Web PubSub doit avoir un nom unique. Remplacez <your-unique-resource-name> par le nom de votre instance Web PubSub dans les commandes suivantes.

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

La sortie de cette commande affiche les propriétés de la ressource que vous venez de créer. Prenez note des propriétés suivantes :

nom : le nom Web PubSub que vous avez fourni dans le paramètre --name ci-dessus.
Nom d’hôte : dans l’exemple, le nom d’hôte est <your-unique-resource-name>.webpubsub.azure.com/.

À ce stade, votre compte Azure est le seul autorisé à effectuer des opérations sur cette nouvelle ressource.

Obtenir la chaîne de connexion

Important

Une chaîne de connexion contient les informations d’autorisation requises pour que votre application accède au service Azure Web PubSub. La clé d’accès à l’intérieur dans la chaîne de connexion est semblable à un mot de passe racine pour votre service. Veillez toujours à protéger vos clés d’accès dans les environnements de production. Utilisez Azure Key Vault pour gérer et effectuer la rotation de vos clés en toute sécurité. Évitez de distribuer des clés d’accès à d’autres utilisateurs, de les coder en dur ou de les enregistrer en texte brut dans un emplacement accessible à d’autres personnes. Effectuez une rotation de vos clés si vous pensez qu’elles ont pu être compromises.

Utilisez la commande Azure CLI az webpubsub key pour obtenir la valeur ConnectionString du service. Remplacez l’espace réservé <your-unique-resource-name> par le nom de votre instance Azure Web PubSub.

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

Copiez la chaîne de connexion à utiliser plus tard.

Créer un client abonné

Les clients se connectent au service Azure Web PubSub via le protocole WebSocket standard à l’aide de l’authentification JSON Web Token (JWT). Le kit de développement logiciel (SDK) du service fournit des méthodes d’assistance pour générer le jeton. Dans ce tutoriel, l’abonné génère directement le jeton à partir de ConnectionString. Généralement, dans les applications réelles, une application côté serveur gère le flux de travail d’authentification/autorisation. Pour mieux comprendre le flux de travail, essayez le tutoriel Générer une application de conversation.

Tout d’abord, créez un répertoire de projet appelé subscriber pour ce projet et installez les dépendances requises :
- Le package Websocket.Client est un package tiers qui prend en charge les connexions WebSocket. Vous pouvez utiliser n’importe quelle API ou bibliothèque qui prend en charge WebSocket.
- Le package du kit de développement logiciel (SDK) Azure.Messaging.WebPubSub permet de générer le jeton 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
```

Remplacez le code dans le fichier Program.cs par le code suivant, qui se connecte au 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();
            }
        }
    }
}

Le code crée une connexion WebSocket qui est connectée à un hub dans Web PubSub. Le hub est une unité logique dans Web PubSub où vous pouvez publier des messages sur un groupe de clients. Les concepts clés contiennent une explication détaillée sur les termes utilisés dans Web PubSub.

Le service Web PubSub utilise l’authentification JWT (JSON Web Token). L’exemple de code utilise WebPubSubServiceClient.GetClientAccessUri() dans le Kit de développement logiciel (SDK) Web PubSub pour générer une URL pour le service qui contient l’URL complète avec un jeton d’accès valide.

Une fois la connexion établie, votre client reçoit des messages via la connexion WebSocket. Le client utilise client.MessageReceived.Subscribe(msg => ...)); pour écouter les messages entrants.

Pour démarrer l’abonné, exécutez la commande pour remplacer <Web-PubSub-connection-string> par la chaîne de connexion que vous avez copiée précédemment :
```
dotnet run <Web-PubSub-connection-string> "myHub1"
```

Tout d’abord, créez un répertoire de projet appelé subscriber et installez les dépendances requises :
```
mkdir subscriber
cd subscriber
npm init -y
npm install --save ws
npm install --save @azure/web-pubsub
```
Utilisez l’API WebSocket pour vous connecter au service Web PubSub. Créez un fichier subscribe.js avec le code suivant :
```
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();
```
Le code crée une connexion WebSocket qui est connectée à un hub dans Web PubSub. Le hub est une unité logique dans Web PubSub où vous pouvez publier des messages sur un groupe de clients. Les concepts clés contiennent une explication détaillée sur les termes utilisés dans Web PubSub.

Le service Web PubSub utilise l’authentification JWT (JSON Web Token). L’exemple de code utilise WebPubSubServiceClient.GetClientAccessUri() dans le Kit de développement logiciel (SDK) Web PubSub pour générer une URL pour le service qui contient l’URL complète avec un jeton d’accès valide.

Une fois la connexion établie, votre client reçoit des messages via la connexion WebSocket. Le client utilise client.MessageReceived.Subscribe(msg => ...)); pour écouter les messages entrants.
Exécutez la commande pour remplacer <Web-PubSub-connection-string> par la chaîne de connexion que vous avez copiée précédemment. Si vous utilisez l’interpréteur de commandes Windows, vous pouvez utiliser set au lieu de export.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node subscribe.js
```

Tout d’abord, créez un répertoire de projet appelé subscriber et installez les dépendances requises :

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

pip install azure-messaging-webpubsubservice
pip install websockets

Utilisez l’API WebSocket pour vous connecter au service Web PubSub. Créez un fichier subscribe.py avec le code suivant :
```
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
```
Le code crée une connexion WebSocket qui est connectée à un hub dans Web PubSub. Le hub est une unité logique dans Web PubSub où vous pouvez publier des messages sur un groupe de clients. Les concepts clés contiennent une explication détaillée sur les termes utilisés dans Web PubSub.

Le service Web PubSub utilise l’authentification JWT (JSON Web Token). L’exemple de code utilise WebPubSubServiceClient.GetClientAccessUri() dans le Kit de développement logiciel (SDK) Web PubSub pour générer une URL pour le service qui contient l’URL complète avec un jeton d’accès valide.

Une fois la connexion établie, votre client recevra des messages via la connexion WebSocket. Utilisez await ws.recv() pour écouter les messages entrants.
Exécutez la commande suivante pour remplacer <Web-PubSub-connection-string> par la chaîne de connexion que vous avez copiée précédemment :
```
python subscribe.py <Web-PubSub-connection-string> "myHub1"
```

Tout d’abord, créez un répertoire de projet nommé pubsub pour ce didacticiel.
```
mkdir pubsub
cd pubsub
```

Dans le répertoire pubsub, utilisez Maven pour créer une application console appelée webpubsub-quickstart-subscriber, puis accédez au répertoire 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

Ajoutez WebSocket et le Kit de développement logiciel (SDK) Azure Web PubSub au nœud dependencies dans pom.xml :
- azure-messaging-webpubsub : kit de développement logiciel (SDK) du service Web PubSub pour Java
- Java-WebSocket : kit de développement logiciel (SDK) client WebSocket pour 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>
```
Dans Web PubSub, vous pouvez vous connecter au service et vous abonner à des messages via des connexions WebSocket. WebSocket est un canal de communication en duplex intégral afin que le service puisse envoyer des messages à votre client en temps réel. Vous pouvez utiliser n’importe quelle API ou bibliothèque qui prend en charge WebSocket. Pour cet échantillon, nous utilisons le package Java-WebSocket.
Accédez au répertoire /src/main/java/com/webpubsub/quickstart.

Éditez le remplacement du contenu du fichier App.java par le code suivant :

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

Ce code crée une connexion WebSocket qui est connectée à un hub dans Azure Web PubSub. Un hub est une unité logique dans Azure Web PubSub où vous pouvez publier des messages sur un groupe de clients. Les concepts clés contiennent une explication détaillée sur les termes utilisés dans Azure Web PubSub.

Une fois la connexion établie, votre client reçoit des messages via la connexion WebSocket. Utilisez onMessage(String message) pour écouter les messages entrants.

Pour démarrer l’application abonné, accédez au répertoire webpubsub-quickstart-subscriber et exécutez la commande suivante. Remplacez <Web-PubSub-connection-string> par la chaîne de connexion que vous avez copiée précédemment.
```
mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1'"
```

2. Publier des messages à l’aide du Kit de développement logiciel (SDK) de service

Créez un éditeur à l’aide du Kit de développement logiciel (SDK) Azure Web PubSub pour publier un message sur le client connecté. Pour ce projet, vous devez ouvrir un autre interpréteur de commandes.

Tout d’abord, créez un répertoire de projet appelé publisher et installez les dépendances requises :
```
mkdir publisher
cd publisher
dotnet new console
dotnet add package Azure.Messaging.WebPubSub
```

Mettez à jour le fichier Program.cs de façon à utiliser la classe WebPubSubServiceClient et à envoyer des messages aux clients.

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

L’appel SendToAllAsync() envoie simplement un message à tous les clients connectés dans le hub.

Envoyez un message en exécutant la commande suivante. Remplacez <Web-PubSub-connection-string> par la chaîne de connexion que vous avez copiée précédemment.
```
dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"
```
Vérifiez que l’interpréteur de commandes de l’abonné reçoit le message :
```
Message received: Hello World
```

Tout d’abord, créez un répertoire de projet appelé publisher et installez les dépendances requises :
```
mkdir publisher
cd publisher
npm init -y
npm install --save @azure/web-pubsub
```

Utilisez le Kit de développement logiciel (SDK) Azure Web PubSub pour publier un message sur le service. Créez un fichier publish.js avec le code suivant :

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

L’appel service.sendToAll() envoie simplement un message à tous les clients connectés dans un hub.

Pour envoyer un message, exécutez la commande suivante pour remplacer <Web-PubSub-connection-string> par la chaîne de connexion que vous avez copiée précédemment. Si vous utilisez l’interpréteur de commandes Windows, vous pouvez utiliser set au lieu de export.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node publish "Hello World"
```
Vous pouvez voir que l’abonné précédent a reçu le message :
```
Message received: Hello World
```

Tout d’abord, créez un répertoire de projet appelé publisher et installez les dépendances requises :

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

pip install azure-messaging-webpubsubservice

Utilisez le Kit de développement logiciel (SDK) Azure Web PubSub pour publier un message sur le service. Créez un fichier publish.py avec le code suivant :

import sys
from azure.messaging.webpubsubservice import WebPubSubServiceClient

if __name__ == '__main__':

    if len(sys.argv) != 4:
        print('Usage: python publish.py <connection-string> <hub-name> <message>')
        exit(1)

    connection_string = sys.argv[1]
    hub_name = sys.argv[2]
    message = sys.argv[3]

    service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
    res = service.send_to_all(message, content_type='text/plain')
    print(res)

send_to_all() envoie le message à tous les clients connectés dans un hub.

Pour envoyer un message, exécutez la commande suivante pour remplacer <Web-PubSub-connection-string> par la chaîne de connexion que vous avez copiée précédemment.
```
python publish.py <Web-PubSub-connection-string> "myHub1" "Hello World"
```
Vérifiez que l’interpréteur de commandes précédent indique que l’abonné a reçu le message :
```
Received message: Hello World
```

Accédez au répertoire pubsub. Utilisez Maven pour créer une application console d’éditeur nommée webpubsub-quickstart-publisher et accédez au répertoire 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

Ajoutez la dépendance du Kit de développement logiciel (SDK) Azure Web PubSub dans le nœud dependencies de pom.xml :

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

Utilisez le Kit de développement logiciel (SDK) Azure Web PubSub pour publier un message sur le service. Accédez au répertoire /src/main/java/com/webpubsub/quickstart, ouvrez le fichier App.java dans votre éditeur et remplacez le contenu par le code qui suit :


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

L’appel sendToAll() envoie un message à tous les clients connectés dans un hub.

Pour envoyer un message, accédez au répertoire webpubsub-quickstart-publisher et exécutez le projet à l’aide de la commande suivante. Remplacez <Web-PubSub-connection-string> par la chaîne de connexion que vous avez copiée précédemment.
```
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'"
```
Vous pouvez voir que l’abonné précédent a reçu le message :
```
Message received: Hello World
```

Nettoyage

Vous pouvez supprimer les ressources que vous avez créées dans ce guide de démarrage rapide en supprimant le groupe de ressources qui les contient.

az group delete --name myResourceGroup --yes

Si vous n’envisagez pas de continuer à utiliser Azure Cloud Shell, vous pouvez éviter d’accumuler des coûts en supprimant le groupe de ressources qui contient le compte de stockage associé. Le groupe de ressources est nommé cloud-shell-storage-<your-region>. Exécutez la commande suivante en remplaçant <CloudShellResourceGroup> par le nom du groupe Cloud Shell.

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

Attention

La suppression de groupes de ressources supprime toutes les ressources, y compris les ressources créées en dehors de l’étendue de ce didacticiel.

Étapes suivantes

Ce tutoriel vous donne une idée de base de la façon de se connecter au service Web PubSub et de publier des messages sur les clients connectés.

Pour plus d’informations sur l’utilisation du service, consultez les autres didacticiels.

Tutoriel : créer un salon de conversation avec Azure Web PubSub

Explorer d’autres exemples Azure Web PubSub

Partage via