Protocoles clients WebSocket pour Azure Web PubSub

Article
03/05/2024

Les clients se connectent à Azure Web PubSub à l’aide du protocole WebSocket standard.

Points de terminaison de service

Le service Web PubSub fournit deux types de points de terminaison auxquels les clients peuvent se connecter :

/client/hubs/{hub}
/client/?hub={hub}

{hub} est un paramètre obligatoire qui agit comme isolement pour différentes applications. Vous pouvez le définir soit dans le chemin d’accès, soit dans la requête.

Autorisation

Les clients se connectent au service avec un JSON Web Token (JWT). Le jeton peut être dans la chaîne de requête, sous la forme /client/?hub={hub}&access_token={token}, ou dans l’en-tête Authorization, sous la forme Authorization: Bearer {token}.

Voici un flux de travail d’autorisation générale :

Le client négocie avec votre serveur d’applications. Le serveur d’applications contient l’intergiciel d’autorisation, qui traite la demande du client et signe un JWT pour que le client puisse se connecter au service.
Le serveur d’applications renvoie le JWT et l’URL du service au client.
Le client tente de se connecter au service Web PubSub en utilisant l’URL et le jeton JWT renvoyés par le serveur d’applications.

Revendications prises en charge

Vous pouvez également configurer des propriétés pour la connexion cliente lors de la génération du jeton d’accès en spécifiant des revendications spéciales à l’intérieur du jeton JWT :

Description	Type de revendication	Valeur de la revendication	Notes
Le `userId` pour la connexion cliente	`sub`	le userId	Une seule contrainte `sub` est autorisée.
La durée de vie du jeton	`exp`	L’heure d'expiration	La revendication `exp` (délai d’expiration) indique le délai d’expiration à partir duquel le jeton JWT ne doit pas être accepté pour être traité.
Les autorisations que la connexion cliente a initialement	`role`	la valeur de rôle définie dans autorisations	Spécifier plusieurs revendications `role` si le client dispose de plusieurs autorisations.
Les groupes initiaux contactés par le client une fois qu’il se connecte à Azure Web PubSub	`group`	le groupe à joindre	Spécifier plusieurs revendications `group` si le client rejoint plusieurs groupes.

Vous pouvez également ajouter des revendications personnalisées dans le jeton d’accès et ces valeurs sont conservées en tant que propriété claims dans connecter le corps de la requête en amont.

Kits de développement logiciel (SDK) server fournit des API pour générer le jeton d’accès pour les clients.

Client WebSocket simple

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

Par exemple, dans JavaScript, vous pouvez créer un client WebSocket simple en utilisant le 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')

Le client WebSocket PubSub

Un client WebSocket PubSub est le client WebSocket qui utilise des sous-protocoles définis par le service Azure Web PubSub :

json.webpubsub.azure.v1
protobuf.webpubsub.azure.v1

Avec le sous-protocole pris en charge par le service, les clients WebSocket PubSub peuvent publier directement des messages dans des groupes lorsqu’ils disposent des autorisations.

Le sous-protocole `json.webpubsub.azure.v1`

Consultez ceci pour découvrir le sous-protocole JSON en détail.

Créer un client WebSocket PubSub

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

Rejoindre directement un groupe à partir du client

let ackId = 0;
pubsubClient.send(    
    JSON.stringify({
        type: 'joinGroup',
        group: 'group1',
        ackId: ++ackId
    }));

Envoyer des messages à un groupe directement à partir du client

let ackId = 0;
pubsubClient.send(    
    JSON.stringify({
        type: 'sendToGroup',
        group: 'group1',
        ackId: ++ackId,
        dataType: "json",
        data: {
            "hello": "world"
        }
    }));

Le sous-protocole `protobuf.webpubsub.azure.v1`

Les mémoires tampons de protocole (protobuf) désignent un protocole binaire indépendant du langage et de la plateforme qui simplifie l’envoi de données binaires. Protobuf fournit des outils permettant de générer des clients pour de nombreux langages, tels que Java, Python, Objective-C, C# et C++. En savoir plus sur protobuf.

Par exemple, dans JavaScript, vous pouvez créer un client WebSocket PubSub avec un sous-protocole protobuf à l’aide du code suivant :

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

Consultez ceci pour découvrir le sous-protocole protobuf en détail.

AckId et réponse ACK

Le client WebSocket PubSub prend en charge la propriété ackId pour les messages joinGroup, leaveGroup, sendToGroup et event. Lorsque vous utilisez ackId, vous pouvez recevoir un message de réponse ACK quand votre demande est traitée. Vous pouvez choisir d’omettre ackId dans les scénarios « fire and forget ». Dans l’article, nous décrivons les différences de comportement entre la spécification de ackId ou pas.

Comportement quand `ackId` n’est pas spécifié

Si ackId n’est pas spécifié, il est de type « fire and forget ». Même s’il y a des erreurs lors de la répartition des messages, vous n’avez aucun moyen d’être notifié.

Comportement quand `ackId` est spécifié

Publication idempotente

ackId est un numéro uint64 et doit être unique au sein d’un client avec le même ID de connexion. Le service Web PubSub enregistre les ackId et les messages avec le même ackId sont traités comme le même message. Le service refuse de répartir le même message plusieurs fois, ce qui est utile dans les nouvelles tentatives pour éviter les messages en double. Par exemple, si un client envoie un message avec ackId=5 et ne reçoit pas de réponse ACK avec ackId=5, le client effectue une nouvelle tentative et renvoie le même message. Dans certains cas, le message est déjà réparti et la réponse acquitter (ack) est perdue pour une raison quelconque. Le service rejette la nouvelle tentative et la réponse d’une réponse acquitter (ack) avec Duplicate raison.

Réponse ACK

Le service Web PubSub envoie une réponse ACK pour chaque demande avec ackId.

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

ackId associe la demande.
success est une valeur booléenne et indique si la demande est correctement traitée par le service. Si c’est false, les clients doivent vérifier error.
error existe uniquement lorsque success est false et les clients doivent avoir une logique différente pour des éléments name différents. Vous devez supposer qu’il peut y avoir plus de types name à l’avenir.
- Forbidden : le client n’a pas l’autorisation d’accès à la demande. Le client doit être ajouté aux rôles pertinents.
- InternalServerError : une erreur interne s’est produite dans le service. Une nouvelle tentative est nécessaire.
- Duplicate : le message avec le même ackId a déjà été traité par le service.

Autorisations

Comme vous l’avez probablement remarqué dans la description précédente du client WebSocket PubSub, un client ne peut publier vers d’autres clients que lorsqu’il est autorisé à le faire. Les autorisations d’un client peuvent être accordées au moment de la connexion ou pendant la durée de vie de la connexion.

Rôle	Autorisation
Non spécifié(e)	Le client peut envoyer des requêtes d’événements.
`webpubsub.joinLeaveGroup`	Le client peut rejoindre ou 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 ou quitter le groupe `<group>`.
`webpubsub.sendToGroup.<group>`	Le client peut publier des messages dans le groupe `<group>`.

L’autorisation d’un client peut être accordée de plusieurs façons :

1. Attribuer le rôle au client lors de la génération du jeton d’accès

Le client peut se connecter au service à l’aide d’un jeton JWT. La charge utile du jeton peut contenir des informations telles que la role du client. Lors de la signature du jeton JWT au client, vous pouvez accorder des autorisations au client en lui attribuant des rôles spécifiques.

Par exemple, signons un jeton JWT qui a l’autorisation d’envoyer des messages à group1 et à group2 :

let token = await serviceClient.getClientAccessToken({
    roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
});

2. Attribuer le rôle au client avec le gestionnaire d’événements `connect`

Les rôles des clients peuvent également être définis lors de l’inscription du gestionnaire d’événements connect et le gestionnaire d’événements en amont peut retourner le roles du client au service Web PubSub lors de la gestion des événements connect.

Par exemple, dans JavaScript, vous pouvez configurer l’événement handleConnect pour effectuer cette opération :

let handler = new WebPubSubEventHandler("hub1", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
    });
  },
});

3. Attribuer le rôle au client via des API REST ou des SDK serveur pendant l’exécution

let service = new WebPubSubServiceClient("<your_connection_string>", "test-hub");
await service.grantPermission("<connection_id>", "joinLeaveGroup", { targetName: "group1" });