Partager via

Sous-protocole JSON WebSocket pris en charge par Azure Web PubSub

  • Article

Le sous-protocole JSON WebSocket, json.webpubsub.azure.v1permet l’échange de messages de publication/abonnement entre les clients via le service sans aller-retour vers le serveur en amont. Une connexion WebSocket à l’aide du json.webpubsub.azure.v1 sous-protocole est appelée client PubSub WebSocket.

Vue d’ensemble

Une connexion WebSocket simple déclenche un message événement lorsqu’il envoie des messages et s’appuie sur le côté serveur pour traiter les messages et effectuer d’autres opérations.

Avec le json.webpubsub.azure.v1 sous-protocole, vous pouvez créer des clients WebSocket PubSub qui peuvent :

Par exemple, vous pouvez créer un client PubSub WebSocket avec le code JavaScript suivant :

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

Ce document décrit les demandes et réponses de sous-protocole json.webpubsub.azure.v1 . Les trames de données entrantes et sortantes doivent contenir des charges utiles JSON.

Autorisations

Un client PubSub WebSocket peut publier sur d’autres clients seulement s’il est autorisé. Les roles attribués au client déterminent les autorisations accordées au client :

Rôle Autorisation
Non spécifié(e) Le client peut envoyer des requêtes d’é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 sur le groupe <group>.

Le serveur peut accorder ou révoquer les autorisations d’un client de manière dynamique en utilisant des API REST ou des SDK de serveur.

Demandes

Rejoindre des groupes

Format :

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId est l’identité de chaque demande et doit être unique. Le service envoie un message de réponse Ack pour notifier le résultat du processus de la demande. Pour plus d’informations, consultez AckId et Ack Response

Quitter des groupes

Format :

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId est l’identité de chaque demande et doit être unique. Le service envoie un message de réponse Ack pour notifier le résultat du processus de la demande. Pour plus d’informations, consultez AckId et Ack Response

Publier des messages

Format :

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "ackId" : 1,
    "noEcho": true|false,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId est l’identité de chaque demande et doit être unique. Le service envoie un message de réponse Ack pour notifier le résultat du processus de la demande. Pour plus d’informations, consultez AckId et Ack Response
  • noEcho est facultatif. Si la valeur est true, ce message n’est pas renvoyé à la même connexion. Si elle n’est pas définie, la valeur par défaut est false.
  • dataType peut être défini sur json, text ou binary :
    • json : les data peuvent être de n’importe quel type pris en charge par JSON et seront publiées telles quelles. Si dataType n’est pas spécifié, ce sera json par défaut.
    • text : les data doivent être au format chaîne et les données de chaîne seront publiées ;
    • binary : les data doivent être au format base64, et les données binaires seront publiées ;

Cas 1 : publier des données texte :

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • Les clients du sous-protocole dans <group_name> reçoivent :
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • Les clients WebSocket simples dans <group_name> reçoivent la chaîne text data.

Cas 2 : publier des données JSON :

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • Les clients du sous-protocole dans <group_name> reçoivent :
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • Les clients WebSocket simples dans <group_name> reçoivent la chaîne sérialisée {"hello": "world"}.

Cas 3 : publier des données binaires :

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • Les clients du sous-protocole dans <group_name> reçoivent :
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • Les clients WebSocket simples dans <group_name> reçoivent les données binaires dans la trame binaire.

Envoyer des événements personnalisés

Format :

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId est l’identité de chaque demande et doit être unique. Le service envoie un message de réponse Ack pour notifier le résultat du processus de la demande. Pour plus d’informations, consultez AckId et Ack Response

dataType peut être text, binary ou json :

  • json : les données peuvent être de n’importe quel type pris en charge par JSON et seront publiées telles quelles. Le type par défaut est json.
  • text : les données sont au format chaîne et les données de chaîne seront publiées ;
  • binary : les données sont au format base64, et les données binaires seront publiées ;

Cas 1 : envoyer un événement avec des données texte :

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "text",
    "data": "text data", 
}

Le gestionnaire d’événements en amont reçoit des données semblables à :

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: text/plain
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

text data

Le Content-Type de la requête HTTP CloudEvents est text/plain lorsque dataType est text.

Cas 2 : envoyer un événement avec des données JSON :

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json",
    "data": {
        "hello": "world"
    }, 
}

Le gestionnaire d’événements en amont reçoit des données semblables à :

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

{
    "hello": "world"
}

Le Content-Type de la requête HTTP CloudEvents est application/json lorsque dataType est json

Cas 3 : envoyer un événement avec des données binaires :

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "binary",
    "data": "base64_binary", 
}

Le gestionnaire d’événements en amont reçoit des données semblables à :

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

binary

Le Content-Type de la requête HTTP CloudEvents est application/octet-stream lorsque dataType est binary. La trame WebSocket peut être au format text pour les trames de message texte ou de binaires codés en UTF8 pour les trames de message binary.

Le service Web PubSub refuse le client si le message ne correspond pas au format décrit.

Ping

Format :

{
    "type": "ping",
}

Le client peut envoyer un ping message au service pour permettre au service Web PubSub de détecter la durée de vie du client.

Réponses

Les types de messages reçus par le client peuvent être les suivants :

  • ack - Réponse à une requête contenant un ackId.
  • message : messages du groupe ou du serveur.
  • système : messages du service Web PubSub.
  • pong - Réponse à un ping message.

Réponse ACK

Lorsque la demande cliente contient ackId, le service retourne une réponseck pour la demande. Le client doit gérer le mécanisme ack en attendant la réponse ack avec une async await opération et en utilisant une opération de délai d’expiration lorsque la réponse ack n’est pas reçue pendant une certaine période.

Format :

{
    "type": "ack",
    "ackId": 1, // The ack id for the request to ack
    "success": false, // true or false
    "error": {
        "name": "Forbidden|InternalServerError|Duplicate",
        "message": "<error_detail>"
    }
}

L’implémentation du client DOIT toujours vérifier si la success valeur est true ou false la première, puis uniquement lire l’erreur quand success est false.

Réponse de message

Les clients peuvent recevoir des messages publiés par un groupe que le client a rejoint, ou par le serveur, qui opère en tant que rôle de gestionnaire du serveur, envoie des messages au client ou à l’utilisateur spécifique.

  1. Lorsque le message provient d’un groupe

    {
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
    "fromUserId": "abc"
}

  2. Lorsque le message provient du serveur.

    {
    "type": "message",
    "from": "server",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
}

Cas 1 : envoi de données Hello World à la connexion via l’API REST avec Content-Type=text/plain

  • Un client WebSocket simple reçoit une trame WebSocket de texte avec des données : Hello World ;

  • Un client PubSub WebSocket reçoit :

    {
    "type": "message",
    "from": "server",
    "dataType" : "text",
    "data": "Hello World", 
}

Cas 2 : envoi de données { "Hello" : "World"} à la connexion via l’API REST avec Content-Type=application/json

  • Un client WebSocket simple reçoit un cadre WebSocket de texte avec des données stringified : { "Hello" : "World"}.

  • Un client PubSub WebSocket reçoit :

    {
    "type": "message",
    "from": "server",
    "dataType" : "json",
    "data": {
        "Hello": "World"
    }
}

Si l’API REST envoie une chaîne Hello World à l’aide application/json du type de contenu, le client WebSocket simple reçoit une chaîne JSON, qui est "Hello World" encapsulée avec des guillemets doubles (").

Cas 3 : envoi de données binaires à la connexion via l’API REST avec Content-Type=application/octet-stream

  • Un client WebSocket simple reçoit une trame WebSocket binaire avec les données binaires.

  • Un client PubSub WebSocket reçoit :

    {
    "type": "message",
    "from": "server",
    "dataType" : "binary",
    "data": "<base64_binary>"
}

Réponse du système

Le service Web PubSub envoie des messages liés au système aux clients.

Réponse Pong

Le service Web PubSub envoie un pong message au client lorsqu’il reçoit un ping message du client.

Format :

{
    "type": "pong",
}

Connecté

Message envoyé au client lorsque le client se connecte correctement :

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
}

Déconnecté

Message envoyé au client lorsque le serveur ferme la connexion ou lorsque le service refuse le client.

{
    "type": "system",
    "event": "disconnected",
    "message": "reason"
}

Étapes suivantes

Utilisez ces ressources pour commencer à créer votre propre application :

Tutoriel : Publier et s’abonner à des messages dans Azure Web PubSub

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

Tutoriel : Utiliser un sous-protocole pris en charge par le service pour le streaming client

Tutoriel : Créer une conversation serverless avec Azure Functions et Web PubSub

Tutoriel : Configurer un détecteur d’événements

Expérimenter des démonstrations en direct

Explorer d’autres exemples Azure Web PubSub