Tutoriel : Création d’une application de conversation avec le service Azure Web PubSub

Article
04/17/2024

Dans le tutoriel Publication de messages et abonnement, vous apprenez les bases de la publication de messages et de l’abonnement aux messages avec Azure Web PubSub. Dans ce tutoriel, vous découvrez le système d’événements d’Azure Web PubSub et vous l’utilisez pour créer une application web complète avec une fonctionnalité de communication en temps réel.

Dans ce tutoriel, vous allez apprendre à :

Créer une instance de service Azure Web PubSub
Configurer les paramètres du gestionnaire d’événements pour Azure Web PubSub
Gérez les événements dans le serveur d’application et créez une application de conversation en temps réel

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit Azure avant de commencer.

Prérequis

Utilisez l’environnement Bash dans Azure Cloud Shell. Pour plus d’informations, consultez Démarrage rapide pour Bash dans Azure Cloud Shell.
Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Guide pratique pour exécuter Azure CLI dans un conteneur Docker.
- Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour connaître les autres options de connexion, consultez Se connecter avec Azure CLI.
- Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser des extensions avec Azure CLI.
- Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.

La version 2.22.0 (ou une version ultérieure) d’Azure CLI est requise pour cette configuration. Si vous utilisez Azure Cloud Shell, la version la plus récente est déjà installée.

Création d’une instance Azure Web PubSub

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

Créer une instance Web PubSub

Exécutez la commande az extension add pour installer ou mettre à niveau l’extension webpubsub vers la version actuelle.

az extension add --upgrade --name webpubsub

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

Important

Chaque ressource Web PubSub doit avoir un nom unique. Remplacez <your-unique-keyvault-name> par le nom de votre Web PubSub dans les exemples suivants.

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

La sortie de cette commande affiche les propriétés de la ressource que vous venez de créer. Notez les deux propriétés ci-dessous :

Nom de la ressource : nom que vous avez fourni au 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.

Récupération de la chaîne de connexion pour une utilisation ultérieure

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.

Copiez la ConnectionString extraite et définissez-la dans la variable d’environnement WebPubSubConnectionString, que le didacticiel lit ultérieurement. Remplacez <connection-string> ci-dessous par la ConnectionString que vous avez récupérée.

export WebPubSubConnectionString="<connection-string>"

SET WebPubSubConnectionString=<connection-string>

Configuration du projet

Prérequis

ASP.NET Core 8

Création de l'application

Dans Azure Web PubSub, il existe deux rôles : serveur et client. Ce concept est similaire aux rôles serveur et client d’une application web. Le serveur est chargé de gérer les clients, d’écouter et de répondre aux messages clients. Le client est chargé d’envoyer et de recevoir les messages de l’utilisateur(-trice) à partir du serveur et de les visualiser pour l’utilisateur(-trice) final(e).

Dans ce tutoriel, nous créons une application web de conversation en temps réel. Dans une application web réelle, la responsabilité du serveur implique également d’authentifier les clients et de traiter les pages web statiques pour l’interface utilisateur de l’application.

Nous utilisons ASP.NET Core 8 pour héberger les pages web et gérer les requêtes entrantes.

Commençons par créer une application web ASP.NET Core dans un dossier chatapp.

Créez une application web.

mkdir chatapp
cd chatapp
dotnet new web

Ajoutez app.UseStaticFiles() Program.cs pour prendre en charge l’hébergement de pages web statiques.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseStaticFiles();

app.Run();

Créez un fichier HTML et enregistrez-le sous wwwroot/index.html. Nous l’utilisons par la suite pour l’interface utilisateur de l’application de conversation.
```
<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
  </body>
</html>
```

Vous pouvez tester le serveur en exécutant dotnet run --urls http://localhost:8080 et en accédant à http://localhost:8080/index.html dans le navigateur.

Nous utilisons express.js, une infrastructure web populaire pour Node.js pour héberger les pages web et gérer les requêtes entrantes.

Commençons par créer une application web express dans un dossier chatapp.

Installez express.js.

mkdir chatapp
cd chatapp
npm init -y
npm install --save express

Ensuite, créez un serveur express et enregistrez-le sous le nom server.js.

const express = require('express');

const app = express();
app.use(express.static('public'));
app.listen(8080, () => console.log('server started'));

Créez également un fichier HTML et enregistrez-le sous public/index.html. Nous l’utilisons par la suite pour l’interface utilisateur de l’application de conversation.
```
<html>

<body>
  <h1>Azure Web PubSub Chat</h1>
</body>

</html>
```

Vous pouvez tester le serveur en exécutant node server et en accédant à http://localhost:8080 dans le navigateur.

Nous utilisons l’infrastructure web Javalin pour héberger les pages web et gérer les requêtes entrantes.

Utilisez Maven pour créer une application webpubsub-tutorial-chat et basculer vers le dossier webpubsub-tutorial-chat :

mvn archetype:generate --define interactiveMode=n --define groupId=com.webpubsub.tutorial --define artifactId=webpubsub-tutorial-chat --define archetypeArtifactId=maven-archetype-quickstart --define archetypeVersion=1.4
cd webpubsub-tutorial-chat

Ajoutez la dépendance de l’infrastructure web javalin dans le nœud dependencies de pom.xml :

javalin : framework web simple pour Java
slf4j-simple : enregistreur d’événements pour Java

<!-- https://mvnrepository.com/artifact/io.javalin/javalin -->
<dependency>
    <groupId>io.javalin</groupId>
    <artifactId>javalin</artifactId>
    <version>6.1.3</version>
</dependency>

<!-- https://mvnrepository.com/artifact/org.slf4j/slf4j-simple -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.12</version>
</dependency>

Accédez au répertoire /src/main/java/com/webpubsub/tutorial. Ouvrez le fichier App.java dans votre éditeur. Utilisez Javalin.create pour servir des fichiers statiques :

package com.webpubsub.tutorial;

import io.javalin.Javalin;

public class App {
    public static void main(String[] args) {
        // start a server
        Javalin app = Javalin.create(config -> {
            config.staticFiles.add("public");
        }).start(8080);
    }
}

Selon votre configuration, vous devrez peut-être définir explicitement le niveau de langage sur Java 8. Cette étape peut être effectuée dans pom.xml. Ajoutez l’extrait de code suivant :

<build>
    <plugins>
        <plugin>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.8.0</version>
          <configuration>
            <source>1.8</source>
            <target>1.8</target>
          </configuration>
        </plugin>
    </plugins>
</build>

Créez un fichier HTML et enregistrez-le dans /src/main/resources/public/index.html. Nous l’utilisons par la suite pour l’interface utilisateur de l’application de conversation.
```
<html>
<body>
  <h1>Azure Web PubSub Chat</h1>
</body>

</html>
```

Vous pouvez tester le serveur en exécutant la commande suivante sous le répertoire contenant le fichier pom.xml et en accédant à http://localhost:8080 dans le navigateur.

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.tutorial.App" -Dexec.cleanupDaemonThreads=false

Nous utilisons flask, une infrastructure web populaire pour Python pour accomplir ce travail.

Commencez par créer un dossier de projet chatapp avec Flask prêt.

Créez et activez ensuite l’environnement

mkdir chatapp
cd chatapp
python3 -m venv .venv
. .venv/bin/activate

Dans l’environnement activé, installez Flask
```
pip install Flask
```

Créez ensuite un serveur Flask et enregistrez-le sous le nom de server.py

from flask import (
    Flask, 
    send_from_directory,
)

app = Flask(__name__)

@app.route('/<path:filename>')
def index(filename):
    return send_from_directory('public', filename)

if __name__ == '__main__':
    app.run(port=8080)

Créez également un fichier HTML et enregistrez-le sous public/index.html. Nous l’utilisons par la suite pour l’interface utilisateur de l’application de conversation.
```
<html>

<body>
  <h1>Azure Web PubSub Chat</h1>
</body>

</html>
```

Vous pouvez tester le serveur en exécutant python server.py et en accédant à http://127.0.0.1:8080/index.html dans le navigateur.

Ajouter un point de terminaison de négociation

Dans le didacticiel Publier et s’abonner au message, l’abonné(e) consomme directement la chaîne de connexion. Dans une application réelle, il n’est pas sûr de partager la chaîne de connexion avec n’importe quel client, car la chaîne de connexion a le privilège d’effectuer n’importe quelle opération sur le service. À présent, supposons que votre serveur consomme la chaîne de connexion et expose un point de terminaison negotiate pour que le client obtienne l’URL complète avec le jeton d’accès. De cette façon, le serveur peut ajouter un intergiciel d’authentification avant le point de terminaison negotiate pour empêcher l’accès non autorisé.

Tout d’abord, installez les dépendances.

dotnet add package Microsoft.Azure.WebPubSub.AspNetCore

Nous allons maintenant ajouter un point de terminaison /negotiate pour que le client appelle pour générer le jeton.

using Azure.Core;
using Microsoft.Azure.WebPubSub.AspNetCore;
using Microsoft.Azure.WebPubSub.Common;
using Microsoft.Extensions.Primitives;

// Read connection string from environment
var connectionString = Environment.GetEnvironmentVariable("WebPubSubConnectionString");
if (connectionString == null)
{
    throw new ArgumentNullException(nameof(connectionString));
}

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddWebPubSub(o => o.ServiceEndpoint = new WebPubSubServiceEndpoint(connectionString))
    .AddWebPubSubServiceClient<Sample_ChatApp>();
var app = builder.Build();

app.UseStaticFiles();

// return the Client Access URL with negotiate endpoint
app.MapGet("/negotiate", (WebPubSubServiceClient<Sample_ChatApp> service, HttpContext context) =>
{
    var id = context.Request.Query["id"];
    if (StringValues.IsNullOrEmpty(id))
    {
        context.Response.StatusCode = 400;
        return null;
    }
    return new
    {
        url = service.GetClientAccessUri(userId: id).AbsoluteUri
    };
});
app.Run();

sealed class Sample_ChatApp : WebPubSubHub
{
}

AddWebPubSubServiceClient<THub>() est utilisé pour injecter le client de service WebPubSubServiceClient<THub>, que nous pouvons utiliser dans l’étape de négociation pour générer un jeton de connexion client et dans les méthodes du hub pour appeler des API REST de service lorsque des événements du hub sont déclenchés. Ce code de génération de jeton est similaire à celui que nous avons utilisé dans le tutoriel Publication de messages et abonnement, à ceci près qu’un argument de plus (userId) est transmis lors de la génération du jeton. L’ID d’utilisateur peut servir à identifier l’identité du client. Ainsi, lorsque vous recevez un message, vous en connaissez l’origine.

Le code lit la chaîne de connexion à partir de la variable d’environnement WebPubSubConnectionString que nous avons définie à l’étape précédente.

Réexécutez le serveur à l’aide de dotnet run --urls http://localhost:8080.

Tout d’abord, installez le kit SDK Azure Web PubSub :

npm install --save @azure/web-pubsub

Ajoutez maintenant une /negotiateAPI au fichier pour générer le jeton.

const express = require('express');
const { WebPubSubServiceClient } = require('@azure/web-pubsub');

const app = express();
const hubName = 'Sample_ChatApp';

let serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hubName);

app.get('/negotiate', async (req, res) => {
    let id = req.query.id;
    if (!id) {
    res.status(400).send('missing user id');
    return;
    }
    let token = await serviceClient.getClientAccessToken({ userId: id });
    res.json({
    url: token.url
    });
});

app.use(express.static('public'));
app.listen(8080, () => console.log('server started'));

Ce code de génération de jeton est similaire à celui que nous avons utilisé dans le tutoriel Publication de messages et abonnement, à ceci près qu’un argument de plus (userId) est transmis lors de la génération du jeton. L’ID d’utilisateur peut servir à identifier l’identité du client. Ainsi, lorsque vous recevez un message, vous en connaissez l’origine.

Le code lit la chaîne de connexion à partir de la variable d’environnement WebPubSubConnectionString que nous avons définie à l’étape précédente.

Réexécutez le serveur en exécutant node server.

Tout d’abord, ajoutez la dépendance du kit de développement logiciel (SDK) Azure Web PubSub et gson dans le nœud dependencies de pom.xml :

<!-- https://mvnrepository.com/artifact/com.azure/azure-messaging-webpubsub -->
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.2.12</version>
</dependency>
<!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>

Ajoutez maintenant une /negotiateAPI au fichier App.java pour générer le jeton :

package com.webpubsub.tutorial;
    
import com.azure.messaging.webpubsub.WebPubSubServiceClient;
import com.azure.messaging.webpubsub.WebPubSubServiceClientBuilder;
import com.azure.messaging.webpubsub.models.GetClientAccessTokenOptions;
import com.azure.messaging.webpubsub.models.WebPubSubClientAccessToken;
import com.azure.messaging.webpubsub.models.WebPubSubContentType;
import com.google.gson.Gson;
import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import io.javalin.Javalin;

public class App {
    public static void main(String[] args) {
        String connectionString = System.getenv("WebPubSubConnectionString");

        if (connectionString == null) {
            System.out.println("Please set the environment variable WebPubSubConnectionString");
            return;
        }

        // create the service client
        WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
                .connectionString(connectionString)
                .hub("Sample_ChatApp")
                .buildClient();

        // start a server
        Javalin app = Javalin.create(config -> {
            config.staticFiles.add("public");
        }).start(8080);
        
        // Handle the negotiate request and return the token to the client
        app.get("/negotiate", ctx -> {
            String id = ctx.queryParam("id");
            if (id == null) {
                ctx.status(400);
                ctx.result("missing user id");
                return;
            }
            GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
            option.setUserId(id);
            WebPubSubClientAccessToken token = service.getClientAccessToken(option);
            ctx.contentType("application/json");
            Gson gson = new Gson();
            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("url", token.getUrl());
            String response = gson.toJson(jsonObject);
            ctx.result(response);
            return;
        });
    }
}

Ce code de génération de jeton est similaire à celui que nous avons utilisé dans le tutoriel Publication de messages et abonnement, à ceci près que la méthode setUserId est appelée pour définir l’ID d’utilisateur lors de la génération du jeton. L’ID d’utilisateur peut servir à identifier l’identité du client. Ainsi, lorsque vous recevez un message, vous en connaissez l’origine.

Le code lit la chaîne de connexion à partir de la variable d’environnement WebPubSubConnectionString que nous avons définie à l’étape précédente.

Relancez le serveur à l’aide des commandes suivantes :

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.tutorial.App" -Dexec.cleanupDaemonThreads=false

Tout d’abord, installez le kit SDK Azure Web PubSub.

pip install azure-messaging-webpubsubservice

Ajoutez maintenant une API /negotiate au serveur pour générer le jeton.

import os

from flask import (
    Flask, 
    request, 
    send_from_directory,
)

from azure.messaging.webpubsubservice import (
    WebPubSubServiceClient
)

hub_name = 'Sample_ChatApp'
connection_string = os.environ.get('WebPubSubConnectionString')

app = Flask(__name__)
service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)

@app.route('/<path:filename>')
def index(filename):
    return send_from_directory('public', filename)


@app.route('/negotiate')
def negotiate():
    id = request.args.get('id')
    if not id:
        return 'missing user id', 400

    token = service.get_client_access_token(user_id=id)
    return {
        'url': token['url']
    }, 200

if __name__ == '__main__':
    app.run(port=8080)

Ce code de génération de jeton est similaire à celui que nous avons utilisé dans le tutoriel Publication de messages et abonnement, à ceci près qu’un argument de plus (user_id) est transmis lors de la génération du jeton. L’ID d’utilisateur peut servir à identifier l’identité du client. Ainsi, lorsque vous recevez un message, vous en connaissez l’origine.

Le code lit la chaîne de connexion à partir de la variable d’environnement WebPubSubConnectionString que nous avons définie à l’étape précédente.

Réexécutez le serveur à l’aide de python server.py.

Pour tester cette API, accédez à http://localhost:8080/negotiate?id=user1. Vous obtenez ainsi l’URL complète d’Azure Web PubSub avec un jeton d’accès.

Gérez les événements

Dans Azure Web PubSub, lorsque certaines activités se produisent côté client (par exemple, un client se connecte, se connecte, se déconnecte, ou un client envoie des messages), le service envoie des notifications au serveur afin qu’il puisse réagir à ces événements.

Les événements sont remis au serveur sous la forme d’un Webhook. Celui-ci est traité et exposé par le serveur d’applications, et inscrit du côté du service Azure Web PubSub. Le service appelle le Webhook chaque fois qu’un événement se produit.

Azure Web PubSub suit CloudEvents pour décrire les données d’événement.

Ci-dessous, nous gérons les événements système connected lorsqu’un client est connecté et qu’il gère message événements utilisateur lorsqu’un client envoie des messages pour générer l’application de conversation.

Le Kit de développement logiciel (SDK) Web PubSub pour AspNetCore Microsoft.Azure.WebPubSub.AspNetCore que nous avons installé à l’étape précédente peut également aider à analyser et traiter les requêtes CloudEvents.

Tout d’abord, ajoutez des gestionnaires d’événements avant app.Run(). Spécifiez le chemin du point de terminaison des événements, par exemple /eventhandler.

app.MapWebPubSubHub<Sample_ChatApp>("/eventhandler/{*path}");
app.Run();

À présent, dans la classe Sample_ChatApp que nous avons créée à l’étape précédente, ajoutez un constructeur pour travailler avec WebPubSubServiceClient<Sample_ChatApp> que nous utilisons pour appeler le service Web PubSub. Et OnConnectedAsync() pour répondre lorsque connected événement est déclenché, OnMessageReceivedAsync() pour gérer les messages du client.

sealed class Sample_ChatApp : WebPubSubHub
{
    private readonly WebPubSubServiceClient<Sample_ChatApp> _serviceClient;

    public Sample_ChatApp(WebPubSubServiceClient<Sample_ChatApp> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override async Task OnConnectedAsync(ConnectedEventRequest request)
    {
        Console.WriteLine($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
    }

    public override async ValueTask<UserEventResponse> OnMessageReceivedAsync(UserEventRequest request, CancellationToken cancellationToken)
    {
        await _serviceClient.SendToAllAsync(RequestContent.Create(
        new
        {
            from = request.ConnectionContext.UserId,
            message = request.Data.ToString()
        }),
        ContentType.ApplicationJson);

        return new UserEventResponse();
    }
}

Dans le code ci-dessus, nous utilisons le client de service pour diffuser un message de notification au format JSON à tous ceux qui sont liés à SendToAllAsync.

Le Kit de développement logiciel (SDK) Web PubSub pour les @azure/web-pubsub-express express permet d’analyser et de traiter les requêtes CloudEvents.

npm install --save @azure/web-pubsub-express

Mettez à jour server.js avec le code suivant pour exposer une API REST dans /eventhandler (ce qui est effectué par le middleware express fourni par le kit SDK Web PubSub) et ainsi gérer l’événement client connecté :

const express = require("express");
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");

const app = express();
const hubName = "Sample_ChatApp";

let serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hubName);

let handler = new WebPubSubEventHandler(hubName, {
  path: "/eventhandler",
  onConnected: async (req) => {
    console.log(`${req.context.userId} connected`);
  },
  handleUserEvent: async (req, res) => {
    if (req.context.eventName === "message")
      await serviceClient.sendToAll({
        from: req.context.userId,
        message: req.data,
      });
    res.success();
  },
});
app.get("/negotiate", async (req, res) => {
  let id = req.query.id;
  if (!id) {
    res.status(400).send("missing user id");
    return;
  }
  let token = await serviceClient.getClientAccessToken({ userId: id });
  res.json({
    url: token.url,
  });
});

app.use(express.static("public"));
app.use(handler.getMiddleware());

app.listen(8080, () => console.log("server started"));

Le code ci-dessus affiche onConnectedsimplement un message sur la console lorsqu’un client est connecté. Comme vous pouvez le constater, req.context.userId est utilisé pour voir l’identité du client connecté. Et handleUserEvent est appelée lorsqu’un client envoie un message. Il utilise WebPubSubServiceClient.sendToAll() pour diffuser le message dans un objet JSON à tous les clients. Comme vous pouvez le constater, handleUserEvent possède également un objet res dans lequel vous pouvez renvoyer le message à l’expéditeur de l’événement. Ici, nous appelons simplement res.success() pour que le WebHook retourne 200. (Notez que cet appel est requis même s’il ne faut rien renvoyer au client. Sinon, le WebHook ne retourne jamais rien, et la connexion cliente ferme).

Pour l’instant, vous devez implémenter le gestionnaire d’événements par votre propre en Java. Les étapes sont simples et suivent les spécifications du protocole et sont illustrées dans la liste ci-dessous :

Ajoutez le gestionnaire HTTP pour le chemin du gestionnaire d’événements, par exemple /eventhandler.
Il faut tout d’abord gérer les demandes OPTIONS de protection contre les abus. Pour cela, vérifiez si l’en-tête contient un en-tête WebHook-Request-Origin et retournez l’en-tête WebHook-Allowed-Origin. Pour simplifier la démonstration, nous retournons * pour autoriser toutes les origines.
```
// validation: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#protection
app.options("/eventhandler", ctx -> {
    ctx.header("WebHook-Allowed-Origin", "*");
});
```
Il s’agit ensuite de vérifier si les demandes entrantes correspondent aux événements attendus. Intéressons-nous maintenant à l’événement système connected, qui doit contenir l’en-tête ce-typeazure.webpubsub.sys.connected. Nous ajoutons la logique après la protection contre les abus pour diffuser l’événement connecté à tous les clients afin qu’ils puissent voir qui a rejoint le salon de conversation.
```
// validation: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#protection
app.options("/eventhandler", ctx -> {
    ctx.header("WebHook-Allowed-Origin", "*");
});

// handle events: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#events
app.post("/eventhandler", ctx -> {
    String event = ctx.header("ce-type");
    if ("azure.webpubsub.sys.connected".equals(event)) {
        String id = ctx.header("ce-userId");
        System.out.println(id + " connected.");
    }
    ctx.status(200);
});
```
Le code ci-dessus affiche simplement un message sur la console lorsqu’un client est connecté. Comme vous pouvez le constater, ctx.header("ce-userId") est utilisé pour voir l’identité du client connecté.

La ce-type de l’événement message est toujours azure.webpubsub.user.message. Les détails s’affichent message d’événement. Nous mettons à jour la logique de gestion des messages : lorsqu’un message arrive, nous le diffusons au format JSON à tous les clients connectés.

// handle events: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#events
app.post("/eventhandler", ctx -> {
    String event = ctx.header("ce-type");
    if ("azure.webpubsub.sys.connected".equals(event)) {
        String id = ctx.header("ce-userId");
        System.out.println(id + " connected.");
    } else if ("azure.webpubsub.user.message".equals(event)) {
        String id = ctx.header("ce-userId");
        String message = ctx.body();
        Gson gson = new Gson();
        JsonObject jsonObject = new JsonObject();
        jsonObject.addProperty("from", id);
        jsonObject.addProperty("message", message);
        String messageToSend = gson.toJson(jsonObject);
        service.sendToAll(messageToSend, WebPubSubContentType.APPLICATION_JSON);
    }
    ctx.status(200);
});

Pour l’instant, vous devez implémenter le gestionnaire d’événements par votre propre en Python. Les étapes sont simples et suivent les spécifications du protocole et sont illustrées dans la liste ci-dessous :

Ajoutez le gestionnaire HTTP pour le chemin du gestionnaire d’événements, par exemple /eventhandler.

Il faut tout d’abord gérer les demandes OPTIONS de protection contre les abus. Pour cela, vérifiez si l’en-tête contient un en-tête WebHook-Request-Origin et retournez l’en-tête WebHook-Allowed-Origin. Pour simplifier la démonstration, nous retournons * pour autoriser toutes les origines.

# validation: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#protection
@app.route('/eventhandler', methods=['OPTIONS'])
def handle_event():
    if request.method == 'OPTIONS':
        if request.headers.get('WebHook-Request-Origin'):
            res = Response()
            res.headers['WebHook-Allowed-Origin'] = '*'
            res.status_code = 200
            return res

Il s’agit ensuite de vérifier si les demandes entrantes correspondent aux événements attendus. Intéressons-nous maintenant à l’événement système connected, qui doit contenir l’en-tête ce-typeazure.webpubsub.sys.connected. Ajoutez la logique après la protection contre les abus :

# validation: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#protection
# handle events: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#events
@app.route('/eventhandler', methods=['POST', 'OPTIONS'])
def handle_event():
    if request.method == 'OPTIONS':
        if request.headers.get('WebHook-Request-Origin'):
            res = Response()
            res.headers['WebHook-Allowed-Origin'] = '*'
            res.status_code = 200
            return res
    elif request.method == 'POST':
        user_id = request.headers.get('ce-userid')
        if request.headers.get('ce-type') == 'azure.webpubsub.sys.connected':
            return user_id + ' connected', 200
        else:
            return 'Not found', 404

Le code ci-dessus affiche simplement un message sur la console lorsqu’un client est connecté. Comme vous pouvez le constater, request.headers.get('ce-userid') est utilisé pour voir l’identité du client connecté.

@app.route('/eventhandler', methods=['POST', 'OPTIONS'])
def handle_event():
    if request.method == 'OPTIONS':
        if request.headers.get('WebHook-Request-Origin'):
            res = Response()
            res.headers['WebHook-Allowed-Origin'] = '*'
            res.status_code = 200
            return res
    elif request.method == 'POST':
        user_id = request.headers.get('ce-userid')
        type = request.headers.get('ce-type')
        if type == 'azure.webpubsub.sys.connected':
            print(f"{user_id} connected")
            return '', 204
        elif type == 'azure.webpubsub.user.message':
            # default uses JSON
            service.send_to_all(message={
                'from': user_id,
                'message': request.data.decode('UTF-8')
            })
            # returned message is also received by the client
            return {
                'from': "system",
                'message': "message handled by server"
            }, 200
        else:
            return 'Bad Request', 400

Mettez à jour la page web

Mettons maintenant à jour index.html pour ajouter la logique de connexion, d’envoi de message et d’affichage des messages reçus dans la page.

<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
    <input id="message" placeholder="Type to chat...">
    <div id="messages"></div>
    <script>
      (async function () {
        let id = prompt('Please input your user name');
        let res = await fetch(`/negotiate?id=${id}`);
        let data = await res.json();
        let ws = new WebSocket(data.url);
        ws.onopen = () => console.log('connected');

        let messages = document.querySelector('#messages');
        
        ws.onmessage = event => {
          let m = document.createElement('p');
          let data = JSON.parse(event.data);
          m.innerText = `[${data.type || ''}${data.from || ''}] ${data.message}`;
          messages.appendChild(m);
        };

        let message = document.querySelector('#message');
        message.addEventListener('keypress', e => {
          if (e.charCode !== 13) return;
          ws.send(message.value);
          message.value = '';
        });
      })();
    </script>
  </body>

</html>

Vous pouvez voir dans le code ci-dessus que nous connectons utiliser l’API WebSocket native dans le navigateur et utiliser WebSocket.send() pour envoyer des messages et des WebSocket.onmessage pour écouter les messages reçus.

Vous pouvez également utiliser sdk client pour vous connecter au service, ce qui vous permet de vous reconnecter automatiquement, de gérer les erreurs et bien plus encore.

Il y a maintenant une étape à gauche pour que la conversation fonctionne. Nous allons configurer les événements auxquels nous nous soucions et où envoyer les événements dans le service Web PubSub.

Configuration du gestionnaire d’événements

Nous définissons le gestionnaire d’événements dans le service Web PubSub pour indiquer au service où envoyer les événements.

Lorsque le serveur web s’exécute localement, comment le service Web PubSub appelle l’hôte local s’il n’a aucun point de terminaison accessible par Internet ? Il existe généralement deux façons. Il s’agit d’exposer localhost au public à l’aide d’un outil de tunnel général, et l’autre consiste à utiliser tunnel awps-tunnel pour tunneliser le trafic du service Web PubSub via l’outil vers votre serveur local.

Dans cette section, nous utilisons Azure CLI pour définir les gestionnaires d’événements et utiliser le tunnel awps-tunnel pour acheminer le trafic vers localhost.

Configurer les paramètres d’un hub

Nous définissons le modèle d’URL pour utiliser un tunnel schéma afin que Web PubSub route les messages via la connexion tunnel de awps-tunnel. Les gestionnaires d’événements peuvent être définis à partir du portail ou de l’interface CLI, comme décrit dans cet article. Ici, nous le définissons dans l’interface CLI. Étant donné que nous écoutons les événements dans le chemin d’accès /eventhandler comme jeu d’étapes précédentes, nous définissons le modèle d’URL sur tunnel:///eventhandler.

Utilisez la commande Azure CLI az webpubsub hub create pour créer les paramètres du gestionnaire d’événements pour le hub Sample_ChatApp.

Important

Remplacez <your-unique-resource-name> par le nom de votre ressource Web PubSub créée précédemment.

az webpubsub hub create -n "<your-unique-resource-name>" -g "myResourceGroup" --hub-name "Sample_ChatApp" --event-handler url-template="tunnel:///eventhandler" user-event-pattern="*" system-event="connected"

Exécutez awps-tunnel localement

Téléchargez et installez awps-tunnel

L’outil fonctionne avec la version 16 ou supérieure de Node.js.

npm install -g @azure/web-pubsub-tunnel-tool

Utilisez la chaîne de connexion du service et exécutez

export WebPubSubConnectionString="<your connection string>"
awps-tunnel run --hub Sample_ChatApp --upstream http://localhost:8080

Exécutez le serveur web

Maintenant, tout est configuré. Exécutez le serveur web et jouer avec l’application de conversation en action.

Exécutez maintenant le serveur à l’aide de dotnet run --urls http://localhost:8080.

L’exemple de code complet de ce tutoriel est disponible ici.

Exécutez maintenant le serveur à l’aide de la commande ci-dessous :

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.tutorial.App" -Dexec.cleanupDaemonThreads=false

L’exemple de code complet de ce tutoriel est disponible ici.

Ouvrez http://localhost:8080/index.html. Vous pouvez entrer votre nom d’utilisateur et commencer à discuter.

Authentification différée avec le gestionnaire d’événements `connect`

Dans les sections précédentes, nous avons démontré comment utiliser le point de terminaison negotiate pour retourner l’URL du service Web PubSub et le jeton d’accès JWT afin que les clients se connectent au service Web PubSub. Dans certains cas, par exemple, pour les périphériques qui ont des ressources limitées, les clients peuvent préférer se connecter directement aux ressources Web PubSub. Dans ce cas, vous pouvez configurer le gestionnaire d’événements connect pour authentifier les clients de manière différée, attribuer des identifiants utilisateur aux clients, spécifier les groupes auxquels les clients se joignent une fois connectés, configurer les autorisations dont disposent les clients et le sous-protocole WebSocket comme réponse WebSocket au client, etc. Pour plus d’informations, reportez-vous aux spécifications du gestionnaire d’événements connect.

Nous allons maintenant utiliser le gestionnaire d’événements connect pour obtenir le même résultat que ce que la section négocier .

Mettre à jour les paramètres du hub

Tout d’abord, nous allons mettre à jour les paramètres du hub pour inclure aussi un gestionnaire d’événements connect. Nous devons également autoriser la connexion anonyme afin que les clients sans jeton d’accès JWT puissent se connecter au service.

Utilisez la commande Azure CLI az webpubsub hub update pour créer les paramètres du gestionnaire d’événements pour le hub Sample_ChatApp.

Important

Remplacez <your-unique-resource-name> par le nom de votre ressource Web PubSub créée précédemment.

az webpubsub hub update -n "<your-unique-resource-name>" -g "myResourceGroup" --hub-name "Sample_ChatApp" --allow-anonymous true --event-handler url-template="tunnel:///eventhandler" user-event-pattern="*" system-event="connected" system-event="connect"

Mettre à jour la logique en amont pour gérer l’événement de connexion

Nous allons maintenant mettre à jour la logique en amont pour gérer l’événement de connexion. Nous pourrions également supprimer le point de terminaison de négociation maintenant.

De manière similaire à ce que nous faisons dans le point de terminaison negotiate à des fins de démonstration, nous allons également lire l'identifiant à partir des paramètres de la requête. Dans l’événement connect, la requête d’origine du client est conservée dans le corps de la requête de l’événement connect.

À l’intérieur de la classe Sample_ChatApp, remplacez OnConnectAsync() pour gérer l’événement connect :

sealed class Sample_ChatApp : WebPubSubHub
{
    private readonly WebPubSubServiceClient<Sample_ChatApp> _serviceClient;

    public Sample_ChatApp(WebPubSubServiceClient<Sample_ChatApp> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override ValueTask<ConnectEventResponse> OnConnectAsync(ConnectEventRequest request, CancellationToken cancellationToken)
    {
        if (request.Query.TryGetValue("id", out var id))
        {
            return new ValueTask<ConnectEventResponse>(request.CreateResponse(userId: id.FirstOrDefault(), null, null, null));
        }

        // The SDK catches this exception and returns 401 to the caller
        throw new UnauthorizedAccessException("Request missing id");
    }

    public override async Task OnConnectedAsync(ConnectedEventRequest request)
    {
        Console.WriteLine($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
    }

    public override async ValueTask<UserEventResponse> OnMessageReceivedAsync(UserEventRequest request, CancellationToken cancellationToken)
    {
        await _serviceClient.SendToAllAsync(RequestContent.Create(
        new
        {
            from = request.ConnectionContext.UserId,
            message = request.Data.ToString()
        }),
        ContentType.ApplicationJson);

        return new UserEventResponse();
    }
}

Mettez à jour server.js pour gérer l’événement de connexion du client :

const express = require("express");
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");

const app = express();
const hubName = "Sample_ChatApp";

let serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hubName);

let handler = new WebPubSubEventHandler(hubName, {
  path: "/eventhandler",
  handleConnect: async (req, res) => {
    if (req.context.query.id){
      res.success({ userId: req.context.query.id });
    } else {
      res.fail(401, "missing user id");
    }
  },
  onConnected: async (req) => {
    console.log(`${req.context.userId} connected`);
  },
  handleUserEvent: async (req, res) => {
    if (req.context.eventName === "message")
      await serviceClient.sendToAll({
        from: req.context.userId,
        message: req.data,
      });
    res.success();
  },
});
app.use(express.static("public"));
app.use(handler.getMiddleware());

app.listen(8080, () => console.log("server started"));

Nous allons maintenant ajouter la logique pour gérer l’événement de connexion azure.webpubsub.sys.connect :


// validation: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#protection
app.options("/eventhandler", ctx -> {
    ctx.header("WebHook-Allowed-Origin", "*");
});

// handle events: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#connect
app.post("/eventhandler", ctx -> {
    String event = ctx.header("ce-type");
    if ("azure.webpubsub.sys.connect".equals(event)) {
        String body = ctx.body();
        System.out.println("Reading from request body...");
        Gson gson = new Gson();
        JsonObject requestBody = gson.fromJson(body, JsonObject.class); // Parse JSON request body
        JsonObject query = requestBody.getAsJsonObject("query");
        if (query != null) {
            System.out.println("Reading from request body query:" + query.toString());
            JsonElement idElement = query.get("id");
            if (idElement != null) {
                JsonArray idInQuery = query.get("id").getAsJsonArray();
                if (idInQuery != null && idInQuery.size() > 0) {
                    String id = idInQuery.get(0).getAsString();
                    ctx.contentType("application/json");
                    Gson response = new Gson();
                    JsonObject jsonObject = new JsonObject();
                    jsonObject.addProperty("userId", id);
                    ctx.result(response.toJson(jsonObject));
                    return;
                }
            }
        } else {
            System.out.println("No query found from request body.");
        }
        ctx.status(401).result("missing user id");
    } else if ("azure.webpubsub.sys.connected".equals(event)) {
        String id = ctx.header("ce-userId");
        System.out.println(id + " connected.");
        ctx.status(200);
    } else if ("azure.webpubsub.user.message".equals(event)) {
        String id = ctx.header("ce-userId");
        String message = ctx.body();
        service.sendToAll(String.format("{\"from\":\"%s\",\"message\":\"%s\"}", id, message), WebPubSubContentType.APPLICATION_JSON);
        ctx.status(200);
    }
});

Intéressons-nous maintenant à l’événement système connect, qui doit contenir l’en-tête ce-type comme azure.webpubsub.sys.connect. Ajoutez la logique après la protection contre les abus :

@app.route('/eventhandler', methods=['POST', 'OPTIONS'])
def handle_event():
    if request.method == 'OPTIONS' or request.method == 'GET':
        if request.headers.get('WebHook-Request-Origin'):
            res = Response()
            res.headers['WebHook-Allowed-Origin'] = '*'
            res.status_code = 200
            return res
    elif request.method == 'POST':
        user_id = request.headers.get('ce-userid')
        type = request.headers.get('ce-type')
        print("Received event of type:", type)
        # Sample connect logic if connect event handler is configured
        if type == 'azure.webpubsub.sys.connect':
            body = request.data.decode('utf-8')
            print("Reading from connect request body...")
            query = json.loads(body)['query']
            print("Reading from request body query:", query)
            id_element = query.get('id')
            user_id = id_element[0] if id_element else None
            if user_id:
                return {'userId': user_id}, 200
            return 'missing user id', 401
        elif type == 'azure.webpubsub.sys.connected':
            return user_id + ' connected', 200
        elif type == 'azure.webpubsub.user.message':
            service.send_to_all(content_type="application/json", message={
                'from': user_id,
                'message': request.data.decode('UTF-8')
            })
            return Response(status=204, content_type='text/plain')
        else:
            return 'Bad Request', 400

Mettre à jour index.html pour vous connecter directement

Nous allons maintenant mettre à jour la page web pour se connecter directement au service Web PubSub. Une chose à mentionner est que maintenant, à des fins de démonstration, le point de terminaison du service Web PubSub est codé en dur dans le code client. Mettez à jour le nom d’hôte du service <the host name of your service> dans le code html ci-dessous avec la valeur de votre propre service. Il peut toujours être utile d’extraire la valeur du point de terminaison de service Web PubSub à partir de votre serveur. Cela vous offre plus de flexibilité et de contrôle sur l’emplacement où le client se connecte.

<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
    <input id="message" placeholder="Type to chat...">
    <div id="messages"></div>
    <script>
      (async function () {
        // sample host: mock.webpubsub.azure.com
        let hostname = "<the host name of your service>";
        let id = prompt('Please input your user name');
        let ws = new WebSocket(`wss://${hostname}/client/hubs/Sample_ChatApp?id=${id}`);
        ws.onopen = () => console.log('connected');

        let messages = document.querySelector('#messages');
        
        ws.onmessage = event => {
          let m = document.createElement('p');
          let data = JSON.parse(event.data);
          m.innerText = `[${data.type || ''}${data.from || ''}] ${data.message}`;
          messages.appendChild(m);
        };

        let message = document.querySelector('#message');
        message.addEventListener('keypress', e => {
          if (e.charCode !== 13) return;
          ws.send(message.value);
          message.value = '';
        });
      })();
    </script>
  </body>

</html>

Réexécuter le serveur

Maintenant réexécutez le serveur et visitez la page web en suivant les instructions précédentes. Si vous avez arrêté awps-tunnel, veuillez également réexécuter l’outil de tunnel.

Étapes suivantes

Ce tutoriel vous donne une idée de base du fonctionnement du système d’événements dans le service Azure Web PubSub.

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

Explorer d’autres exemples Azure Web PubSub

Partager via

Tutoriel : Création d’une application de conversation avec le service Azure Web PubSub

Prérequis

Création d’une instance Azure Web PubSub

Créer un groupe de ressources

Créer une instance Web PubSub

Récupération de la chaîne de connexion pour une utilisation ultérieure

Configuration du projet

Prérequis

Création de l'application

Ajouter un point de terminaison de négociation

Gérez les événements

Mettez à jour la page web

Configuration du gestionnaire d’événements

Configurer les paramètres d’un hub

Exécutez awps-tunnel localement

Téléchargez et installez awps-tunnel

Utilisez la chaîne de connexion du service et exécutez

Exécutez le serveur web

Authentification différée avec le gestionnaire d’événements `connect`

Mettre à jour les paramètres du hub

Mettre à jour la logique en amont pour gérer l’événement de connexion

Mettre à jour index.html pour vous connecter directement

Réexécuter le serveur

Étapes suivantes

Commentaires

Ressources supplémentaires

Partager via

Tutoriel : Création d’une application de conversation avec le service Azure Web PubSub

Prérequis

Création d’une instance Azure Web PubSub

Créer un groupe de ressources

Créer une instance Web PubSub

Récupération de la chaîne de connexion pour une utilisation ultérieure

Configuration du projet

Prérequis

Création de l'application

Ajouter un point de terminaison de négociation

Gérez les événements

Mettez à jour la page web

Configuration du gestionnaire d’événements

Configurer les paramètres d’un hub

Exécutez awps-tunnel localement

Téléchargez et installez awps-tunnel

Utilisez la chaîne de connexion du service et exécutez

Exécutez le serveur web

Authentification différée avec le gestionnaire d’événements connect

Mettre à jour les paramètres du hub

Mettre à jour la logique en amont pour gérer l’événement de connexion

Mettre à jour index.html pour vous connecter directement

Réexécuter le serveur

Étapes suivantes

Commentaires

Ressources supplémentaires

Authentification différée avec le gestionnaire d’événements `connect`