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

Article
10/26/2023

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 :

rejoignez un groupe à l’aide de demandes de jointure.
publiez des messages directement dans un groupe à l’aide de requêtes de publication.
acheminer les messages vers différents gestionnaires d’événements en amont à l’aide de demandes d’événements.

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 ne peut publier que sur d’autres clients lorsqu’il est autorisé. Le roles client affecté détermine 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 dans le groupe `<group>`.

Le serveur peut accorder ou révoquer dynamiquement des autorisations client par le biais d’API REST ou de kits 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 Réponse Ack

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 Réponse Ack

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 Réponse Ack
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, textou 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 de sous-protocole dans <group_name> la réception :

{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}

Les clients WebSocket simples dans <group_name> la réception de la chaîne text data.

Cas 2 : publier des données JSON :

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

Les clients de sous-protocole dans <group_name> la réception :

{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}

Les clients WebSocket simples dans <group_name> la réception de la chaîne {"hello": "world"}sérialisée .

Cas 3 : publier des données binaires :

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}

Les clients de sous-protocole dans <group_name> la réception :

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

Les clients WebSocket simples reçoivent <group_name> les données binaires dans le cadre 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 Réponse Ack

dataType peut être text, binary ou json :

json: les données peuvent être n’importe quel type pris en charge et seront publiées comme il s’agit ; La valeur 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 similaires à ce qui suit :

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

La Content-Type requête HTTP CloudEvents est text/plain quand dataType 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 similaires à ce qui suit :

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

La Content-Type requête HTTP CloudEvents est application/json la date à laquelle 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 similaires à ce qui suit :

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

La Content-Type requête HTTP CloudEvents est application/octet-stream quand dataType 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.

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.

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 à partir d’un groupe que le client a joint ou à partir du serveur, qui, fonctionnant dans un rôle d’administration de serveur, envoie des messages à des clients ou utilisateurs spécifiques.

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

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 un cadre 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.

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

Partager via

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

Vue d’ensemble

autorisations

Demandes

Rejoindre des groupes

Quitter des groupes

Publier des messages

Cas 1 : publier des données texte :

Cas 2 : publier des données JSON :

Cas 3 : publier des données binaires :

Envoyer des événements personnalisés

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

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

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

Réponses

Réponse ACK

Réponse de message

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

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

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

Réponse du système

Connecté

Déconnecté

Étapes suivantes

Commentaires

Ressources supplémentaires

Partager via

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

Vue d’ensemble

autorisations

Demandes

Rejoindre des groupes

Quitter des groupes

Publier des messages

Cas 1 : publier des données texte :

Cas 2 : publier des données JSON :

Cas 3 : publier des données binaires :

Envoyer des événements personnalisés

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

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

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

Réponses

Réponse ACK

Réponse de message

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

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

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

Réponse du système

Connecté

Déconnecté

Étapes suivantes

Commentaires

Ressources supplémentaires

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

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

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