Éléments internes du service Azure Web PubSub

Article
06/01/2023

Azure Web PubSub Service offre un moyen simple de publier des messages ou de s’abonner à des messages à l’aide de simples connexions WebSocket.

Les clients peuvent être écrits dans n’importe quel langage prenant en charge Websocket.
Les messages texte et binaires sont pris en charge dans une même connexion.
Il existe un protocole simple permettant aux clients de publier en direct des messages client-client.
Le service gère les connexions WebSocket pour vous.

Conditions

Service : Azure Web PubSub Service.

Connexion : une connexion, également appelée client ou connexion cliente, représente une connexion WebSocket individuelle connectée au service Web PubSub. Une fois la connexion réussie, un ID de connexion unique est affecté à cette connexion par le service Web PubSub.
Hub : un hub est un concept logique pour un ensemble de connexions clientes. En règle générale, vous utilisez un hub pour un scénario, par exemple, un hub de conversation ou un hub de notification . Lorsqu’une connexion cliente est établie, le client se connecte à un hub et, pendant toute sa durée de vie, il appartient à ce hub. Une fois qu’une connexion cliente se connecte au hub, le hub existe. Différentes applications peuvent partager un service Azure Web PubSub en utilisant différents noms de hubs. Bien qu’il n’existe aucune limite stricte sur le nombre de hubs, un hub consomme davantage de charge de service par rapport à un groupe. Il est recommandé d’avoir un ensemble prédéterminé de hubs plutôt que de les générer dynamiquement.
Groupe : un groupe est un sous-ensemble de connexions au hub. Vous pouvez ajouter une connexion cliente à un groupe, ou la supprimer du groupe, quand vous le souhaitez. Par exemple, quand un client rejoint une salle de conversation ou quand il la quitte, cette salle de conversation peut être considérée comme un groupe. Un client peut rejoindre plusieurs groupes, et un groupe peut contenir plusieurs clients. Le groupe est semblable à une « session » de groupe, la session de groupe est créée une fois qu’une personne rejoint le groupe et la session est terminée quand personne n’est dans le groupe. Les messages envoyés au groupe sont remis à tous les clients connectés au groupe.
Utilisateur : les connexions à Web PubSub ne peuvent appartenir qu’à un seul utilisateur. Un utilisateur peut avoir plusieurs connexions. C’est le cas, par exemple, quand un seul utilisateur est connecté sur plusieurs appareils ou plusieurs onglets de navigateur.
Message : quand le client est connecté, il peut envoyer des messages à l’application en amont, ou recevoir des messages de l’application en amont, par le biais de la connexion WebSocket. Les messages peuvent être au format texte brut, binaire ou JSON et avoir une taille maximale de 1 Mo.
Connexion cliente et ID de connexion : un client se connecte au point de terminaison /client. Lorsqu’il est connecté, un connectionId unique est généré par le service en tant qu’identité unique de la connexion cliente. Les utilisateurs peuvent ensuite gérer la connexion cliente à l’aide de ce connectionId. Des informations détaillées sont disponibles dans la section Protocole client.
Événements clients : les événements sont créés pendant le cycle de vie d’une connexion cliente. Par exemple, une connexion cliente WebSocket simple crée un événement connect lorsqu’il tente de se connecter au service, un événement connected quand il s’est correctement connecté au service, un événement message lorsqu’il envoie des messages au service et un événement disconnected lorsqu’il se déconnecte du service. Des informations détaillées sur les événements clients sont présentées dans la section Protocole client.
Gestionnaire d’événements : le gestionnaire d’événements contient la logique permettant de gérer les événements du client. Inscrivez et configurez les gestionnaires d’événements dans le service via le portail ou Azure CLI au préalable. Des informations détaillées sont disponibles dans la section Gestionnaire d’événements.
Écouteur d’événements(préversion) : l’écouteur d’événements écoute simplement les événements du client, mais ne peut pas interférer dans la durée de vie de vos clients via leur réponse. Des informations détaillées sont disponibles dans la section Écouteur d’événements.
Serveur : le serveur peut gérer les événements du client, les connexions du client et publier des messages pour des groupes. Le gestionnaire d’événements et l’écouteur d’événements sont considérés comme étant côté serveur. Des informations détaillées sur le serveur sont présentées dans la section Protocole serveur.

Workflow

Diagram showing the Web PubSub service workflow.

Workflow comme indiqué dans le graphique ci-dessus :

Un client se connecte au point de terminaison /client du service à l’aide du transport WebSocket. Le service transfère chaque trame WebSocket vers le serveur en amont configuré. La connexion WebSocket peut se connecter à n’importe quel sous-protocole personnalisé à gérer par le serveur ou se connecter au sous-protocole pris en charge par le service, ce qui permet aux clients json.webpubsub.azure.v1 d’effectuer des actions Pub/Sub directement. Des informations détaillées sont disponibles dans la section Protocole client.
Le service appelle le serveur à l'aide du protocole CloudEvents sur différents événements clients. CloudEvents est une définition standardisée et indépendante du protocole de la description de la structure et des métadonnées des événements hébergés par la Cloud Native Computing Foundation (CNCF). L’implémentation détaillée du protocole CloudEvents s’appuie sur le rôle serveur, décrit dans Protocole de serveur.
Le serveur Web PubSub peut appeler le service à l’aide de l’API REST pour envoyer des messages aux clients ou pour gérer les clients connectés. Des informations détaillées sont disponibles dans la section Protocole serveur.

Protocole client

Une connexion cliente se connecte au point de terminaison /client du service à l'aide du protocole WebSocket. Le protocole WebSocket fournit des canaux de communication duplex intégral sur une connexion TCP unique et a été normalisé par l’IETF sous la dénomination RFC 6455 en 2011. La plupart des langages ont une prise en charge native pour démarrer les connexions WebSocket.

Notre service prend en charge deux types de clients :

Client WebSocket simple
Client WebSocket PubSub

Client WebSocket simple

Un client WebSocket simple, comme son nom l’indique, est une connexion WebSocket simple. Il peut également avoir son sous-protocole personnalisé.

Par exemple, dans JS, un client WebSocket simple peut être créé à l’aide du code suivant.

// simple WebSocket client1
var client1 = new WebSocket("wss://test.webpubsub.azure.com/client/hubs/hub1");

// simple WebSocket client2 with some custom subprotocol
var client2 = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "custom.subprotocol"
);

Un client WebSocket simple suit une architecture client-serveur<>, comme le montre le diagramme de séquence ci-dessous : Diagram showing the sequence for a client connection.

Lorsque le client démarre un établissement de liaison WebSocket, le service tente d’appeler le gestionnaire d’événements connect pour l’établissement d'une liaison WebSocket. Les développeurs peuvent utiliser ce gestionnaire pour gérer le protocole d’établissement de liaison WebSocket, déterminer le sous-protocole à utiliser, authentifier le client et joindre le client à des groupes.
Lorsque le client est correctement connecté, le service appelle un gestionnaire d’événements connected. Il fonctionne comme une notification et ne bloque pas l’envoi de messages par le client. Les développeurs peuvent utiliser ce gestionnaire pour effectuer un stockage de données et peuvent répondre avec des messages au client. Le service envoie également un événement connected à tous les écouteurs d’événements concernés, le cas échéant.
Lorsque le client envoie des messages, le service déclenche un événement message au gestionnaire d’événements pour gérer les messages envoyés. Cet événement est un événement général qui contient les messages envoyés dans une trame WebSocket. Votre code doit distribuer les messages à l’intérieur de ce gestionnaire d’événements. Si le gestionnaire d’événements retourne un code de réponse non réussi, le service annulé la connexion cliente. Le service envoie également un événement message à tous les écouteurs d’événements concernés, le cas échéant. Si le service ne trouve aucun serveur inscrit pour recevoir les messages, il annule également la connexion.
Lorsque le client se déconnecte, le service tente de déclencher l’événement disconnected vers le gestionnaire d’événements, une fois qu’il a détecté la déconnexion. Le service envoie également un événement disconnected à tous les écouteurs d’événements concernés, le cas échéant.

Scénarios

Ces connexions peuvent être utilisées dans une architecture client-serveur classique, où le client envoie des messages au serveur et où le serveur gère les messages entrants à l’aide de gestionnaires d’événements. Elle peut également être utilisée lorsque les clients appliquent des sous-protocoles existants dans leur logique d’application.

Le client WebSocket PubSub

Le service prend également en charge un sous-protocole spécifique appelé json.webpubsub.azure.v1, qui permet aux clients de publier/de s’abonner directement à la place d’un aller-retour au serveur en amont. Nous appelons la connexion WebSocket avec le sous-protocole json.webpubsub.azure.v1 un client WebSocket PubSub. Pour plus d’informations, consultez la spécification du client Web PubSub sur GitHub.

Par exemple, dans JS, un client WebSocket PubSub peut être créé à l’aide du code suivant.

// PubSub WebSocket client
var pubsub = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);

Le client WebSocket PubSub peut :

Rejoindre un groupe, par exemple :

{
  "type": "joinGroup",
  "group": "<group_name>"
}

Quitter un groupe, par exemple :

{
  "type": "leaveGroup",
  "group": "<group_name>"
}

Publier des messages dans un groupe, par exemple :

{
  "type": "sendToGroup",
  "group": "<group_name>",
  "data": { "hello": "world" }
}

Envoyer des événements personnalisés au serveur en amont, par exemple :

{
  "type": "event",
  "event": "<event_name>",
  "data": { "hello": "world" }
}

Le Sous-protocole WebSocket PubSub contient les détails du sous-protocole json.webpubsub.azure.v1.

Vous avez peut-être remarqué que pour un client WebSocket simple, le serveur est un rôle indispensable pour recevoir les événements message des clients. Une connexion WebSocket simple déclenche toujours un événement message lors de l’envoi de messages et s’appuie toujours sur le côté serveur pour traiter les messages et effectuer d’autres opérations. Avec l’aide du sous-protocole json.webpubsub.azure.v1, un client autorisé peut rejoindre un groupe et publier des messages directement dans un groupe. Il peut également acheminer des messages vers différents gestionnaires d'événements / écouteurs d’événements en personnalisant l’événement auquel appartient le message.

Scénarios

Ces clients peuvent être utilisés lorsque les clients souhaitent communiquer entre eux. Les messages sont envoyés à partir du service client2 et le service remet le message directement à client1 si les clients sont autorisés à le faire.

Client 1 :

var client1 = new WebSocket(
  "wss://xxx.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);
client1.onmessage = (e) => {
  if (e.data) {
    var message = JSON.parse(e.data);
    if (message.type === "message" && message.group === "Group1") {
      // Only print messages from Group1
      console.log(message.data);
    }
  }
};

client1.onopen = (e) => {
  client1.send(
    JSON.stringify({
      type: "joinGroup",
      group: "Group1",
    })
  );
};

Client 2 :

var client2 = new WebSocket("wss://xxx.webpubsub.azure.com/client/hubs/hub1", "json.webpubsub.azure.v1");
client2.onopen = e => {
    client2.send(JSON.stringify({
        type: "sendToGroup",
        group: "Group1",
        data: "Hello Client1"
    });
};

Comme le montre l’exemple ci-dessus, client2 envoie des données directement à client1 en publiant des messages dans le Group1 dans lesquel se trouve client1.

Résumé des événements client

Les événements client sont répartis en deux catégories :

Les événements synchrones (bloquants) Des événements synchrones bloquent le workflow du client.
- connect : cet événement concerne uniquement le gestionnaire d’événements. Lorsque le client démarre l’établissement d'une liaison WebSocket, l’événement est déclenché et les développeurs peuvent utiliser le gestionnaire d’événements connect pour gérer l’établissement d'une liaison WebSocket, déterminer le sous-protocole à utiliser, authentifier le client et joindre le client à des groupes.
- message : cet événement est déclenché lorsqu’un client envoie un message.
Les événements asynchrones (non bloquants) Les événements asynchrones ne bloquent pas le workflow client, ils agissent en tant que notification au serveur. Lorsqu’un déclencheur d’événement de ce type échoue, le service journalise le détail de l’erreur.
- connected : cet événement est déclenché lorsqu’un client se connecte au service avec succès.
- disconnected : cet événement est déclenché lorsqu’un client s’est déconnecté du service.

Limite du message client

La taille de message maximale autorisée pour une trame WebSocket est de 1 Mo.

Authentification du client

Workflow d'authentification

Le client utilise un jeton JWT signé pour se connecter au service. Le serveur en amont peut également rejeter le client lorsqu’il s’agit d’un gestionnaire d’événements connect du client entrant. Le gestionnaire d’événements authentifie le client en spécifiant le userId et le ou les roles du client dans la réponse du webhook, ou décline le client avec l’erreur 401. La section Gestionnaire d’événements décrit cela en détails.

Le graphique suivant décrit le workflow.

Diagram showing the client authentication workflow.

Comme vous l’avez peut-être remarqué lorsque nous avons décrit les clients WebSocket PubSub, un client ne peut publier vers d’autres clients que s’il y est autorisé. Les roles du client déterminent les autorisations initiales dont dispose le client :

Rôle	Autorisation
Non spécifié(e)	Le client peut envoyer des événements.
`webpubsub.joinLeaveGroup`	Le client peut rejoindre/quitter n’importe quel groupe.
`webpubsub.sendToGroup`	Le client peut publier des messages dans n’importe quel groupe.
`webpubsub.joinLeaveGroup.<group>`	Le client peut rejoindre/quitter le groupe `<group>`.
`webpubsub.sendToGroup.<group>`	Le client peut publier des messages dans le groupe `<group>`.

Le côté serveur peut également accorder ou révoquer des autorisations de manière dynamique au client via le protocole serveur, comme illustré dans une section ultérieure.

Protocole serveur

Le protocole serveur fournit les fonctionnalités permettant au serveur de gérer les événements client, les connexions client et les groupes.

En général, le protocole serveur contient deux rôles :

Gestionnaire d’événements
Connection manager
Écouteur d’événements

Gestionnaire d’événements

Le gestionnaire d’événements gère les événements clients entrants. Les gestionnaires d’événements sont inscrits et configurés dans le service via le portail ou Azure CLI. Lorsqu’un événement client est déclenché, le service peut identifier si l’événement doit être géré ou non. Nous utilisons maintenant le mode PUSH pour appeler le gestionnaire d’événements. Le gestionnaire d’événements côté serveur expose un point de terminaison accessible au public pour que le service puisse l’appeler lorsque l’événement est déclenché. Il agit comme un webhook.

Le service Web PubSub fournit des événements client au webhook en amont à l’aide du protocole HTTP CloudEvents.

Pour chaque événement, le service formule une requête HTTP POST au service en amont inscrit et attend une réponse HTTP.

Les données envoyées du service au serveur sont toujours au format binary CloudEvents.

Diagram showing the Web PubSub service event push mode.

Serveur en amont et validation

Le gestionnaire d’événements doit être inscrit et configuré dans le service via le portail ou Azure CLI avant la première utilisation. Lorsqu’un événement client est déclenché, le service peut identifier si l’événement doit être géré ou non. Pour la préversion publique, nous utilisons le mode PUSH pour appeler le gestionnaire d’événements. Le gestionnaire d’événements côté serveur expose un point de terminaison accessible au public pour que le service puisse l’appeler lorsque l’événement est déclenché. Il agit comme un webhooken amont.

L’URL peut utiliser le paramètre {event} pour définir un modèle d’URL pour le gestionnaire de webhook. Le service calcule de manière dynamique la valeur de l’URL du webhook lorsque la demande du client arrive. Par exemple, lorsqu’une demande /client/hubs/chat arrive, avec un modèle d'URL de gestionnaire d’événements configuré http://host.com/api/{event} pour le hub chat, lorsque le client se connecte, il publie d’abord vers cette URL : http://host.com/api/connect. Ce comportement peut être utile lorsqu’un client WebSocket PubSub envoie des événements personnalisés, et le gestionnaire d’événements aide à distribuer différents événements vers différents serveurs en amont. Le paramètre {event} n’est pas autorisé dans le nom de domaine d’URL.

Quand vous configurez le gestionnaire d’événements en amont par le biais du portail Azure ou de l’interface CLI, le service suit la protection contre les abus CloudEvents pour valider le webhook en amont. L’en-tête de demande WebHook-Request-Origin est défini sur le nom de domaine de service xxx.webpubsub.azure.com et il s’attend à ce que la réponse ayant l’en-tête WebHook-Allowed-Origin contienne ce nom de domaine.

Lors de la validation, le paramètre {event} est résolu en validate. Par exemple, lorsqu’il essaie de définir l’URL sur http://host.com/api/{event}, le service essaie de poser des OPTIONS sur une requête vers http://host.com/api/validate et c’est seulement lorsque la réponse est valide que la configuration peut être définie avec succès.

À l’heure actuelle, WebHook-Request-Rate et WebHook-Request-Callback ne sont pas pris en charge.

Authentification/autorisation entre le service et le webhook

Mode anonyme
Authentification simple code qui est fournie par le biais de l’URL de webhook configurée.
Utilisez l’autorisation Microsoft Entra. Pour plus d’informations, consultez comment utiliser l’identité managée.
- Étape 1 : activer l’identité pour le service Web PubSub
- Étape 2 : Sélectionner à partir de l’application Microsoft Entra existante qui correspond à votre application web webhook

Gestionnaire de connexions

Le serveur est par nature un utilisateur autorisé. Avec l’aide du rôle de gestionnaire d’événements, le serveur connaît les métadonnées des clients, par exemple, connectionId et userId. Il peut donc :

Fermer une connexion cliente
Envoyer des messages à un client
Envoyer des messages aux clients qui appartiennent au même utilisateur
Ajouter un client à un groupe
Ajouter des clients authentifiés en tant qu’utilisateur à un groupe
Supprimer un client d’un groupe
Supprimer les clients authentifiés en tant qu’utilisateur d’un groupe
Publier des messages dans un groupe

Il peut également accorder ou révoquer des autorisations de publication/jointure pour un client PubSub :

Accorder des autorisations de publication/jointure à un groupe spécifique ou à tous les groupes
Révoquer des autorisations de publication/jointure pour un groupe spécifique ou pour tous les groupes
Vérifier si le client a l’autorisation de joindre ou de publier dans un groupe spécifique ou dans tous les groupes

Le service fournit des API REST pour le serveur afin de gérer les connexions.

Diagram showing the Web PubSub service connection manager workflow.

Le protocole détaillé en lien avec l’API REST est défini ici.

Écouteur d'événements

Remarque

La fonctionnalité d’écouteur d’événements est en préversion.

L’écouteur d’événements écoute les événements client entrant. Chaque écouteur d’événements contient un filtre pour spécifier les types d’événements qui le concerne, un point de terminaison indiquant où envoyer les événements.

Actuellement, nous prenons en charge Event Hubs en tant que point de terminaison d’écouteur d’événements.

Vous devez inscrire les écouteurs d’événements à l’avance, afin que, lorsqu’un événement client est déclenché, le service puisse envoyer l’événement aux écouteurs d’événements correspondants. Consultez ce document pour savoir comment configurer un écouteur d’événements avec un point de terminaison Event Hub.

Vous pouvez configurer plusieurs écouteurs d’événements. Peu importe l’ordre des écouteurs d’événements. Si un événement correspond à plusieurs écouteurs d’événements, il est envoyé à tous les écouteurs auxquels il correspond. Consultez le diagramme suivant pour obtenir un exemple. Supposons que vous configurez quatre écouteurs d’événements en même temps. Ensuite, un événement client qui correspond à trois de ces écouteurs est envoyé à trois écouteurs, laissant le reste intact.

Event listener data flow diagram sample

Vous pouvez combiner un gestionnaire d’événements et des écouteurs d’événements pour le même événement. Dans ce cas, le gestionnaire d’événements et les écouteurs d’événements recevront l’événement.

Le service Web PubSub fournit des événements client aux écouteurs d’événements à l’aide de l’extension CloudEvents AMQP pour Azure Web PubSub.

Résumé

Vous avez peut-être remarqué que le rôle de gestionnaire d’événements gère la communication du service au serveur tandis que le rôle de manager gère la communication du serveur au service. Après avoir combiné les deux rôles, le flux de données entre le service et le serveur ressemble au diagramme suivant à l’aide du protocole HTTP.

Diagram showing the Web PubSub service bi-directional workflow.