Partager via

Bibliothèque cliente Web PubSub pour JavaScript

Azure Web PubSub est un service cloud qui permet aux développeurs de créer facilement des fonctionnalités en temps réel dans des applications web avec des modèles de publication-abonnement à grande échelle.

Tout scénario nécessitant une messagerie en temps réel entre le serveur et les clients ou parmi les clients qui suivent des modèles d’abonnement de publication peut tirer parti de l’utilisation de Web PubSub. Les développeurs n’ont plus besoin d’interroger le serveur en envoyant des requêtes HTTP répétées à intervalles, ce qui est inutile et difficile à mettre à l’échelle.

Comme illustré dans le diagramme ci-dessous, vos clients établissent des connexions WebSocket avec votre ressource Web PubSub. Cette bibliothèque cliente :

  • simplifie la gestion des connexions clientes
  • simplifie l’envoi de messages entre les clients
  • réessayer automatiquement après des suppressions involontaires de la connexion cliente
  • remet de manière fiable les messages en nombre et dans l’ordre après la récupération à partir des suppressions de connexion

de dépassement de capacité

Vous trouverez plus d’informations sur les termes utilisés ici dans section concepts clés.

Cette bibliothèque est hébergée sur NPM.

Commencer

Environnements actuellement pris en charge

Conditions préalables

  • Un abonnement Azure
  • Une ressource Web PubSub

1. Installer le package @azure/web-pubsub-client

npm install @azure/web-pubsub-client

2. Connectez-vous à votre ressource Web PubSub

Un client utilise une URL d’accès client pour se connecter et s’authentifier auprès du service, qui suit un modèle de wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Un client peut avoir plusieurs façons d’obtenir l’URL d’accès client. Pour ce démarrage rapide, vous pouvez copier et coller un à partir du portail Azure ci-dessous. (Pour la production, vos clients obtiennent généralement l’URL d’accès client générée sur votre serveur d’applications. Voir les détails ci-dessous )

get_client_url

Comme indiqué dans le diagramme ci-dessus, le client dispose des autorisations nécessaires pour envoyer des messages et rejoindre un groupe spécifique nommé «group1».

// Imports the client libray
const { WebPubSubClient } = require("@azure/web-pubsub-client");

// Instantiates the client object
const client = new WebPubSubClient("<client-access-url>");

// Starts the client connection with your Web PubSub resource
await client.start();

// ...
// The client can join/leave groups, send/receive messages to and from those groups all in real-time

3. Joindre des groupes

Notez qu’un client peut uniquement recevoir des messages des groupes qu’il a joints et que vous devez ajouter un rappel pour spécifier la logique lors de la réception de messages.

// ...continues the code snippet from above

// Specifies the group to join
const groupName = "group1";

// Registers a listener for the event 'group-message' early before joining a group to not miss messages
client.on("group-message", (e) => {
  console.log(`Received message: ${e.message.data}`);
});

// A client needs to join the group it wishes to receive messages from
await client.joinGroup(groupName);

4. Envoyer des messages à un groupe

// ...continues the code snippet from above

// Send a message to a joined group
await client.sendToGroup(groupName, "hello world", "text");

// In the Console tab of your developer tools found in your browser, you should see the message printed there.

Exemples

Ajouter des rappels pour les événements connectés, déconnectés et arrêtés

  1. Lorsqu’un client est correctement connecté à votre ressource Web PubSub, l’événement connected est déclenché.
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
  1. Lorsqu’un client est déconnecté et ne parvient pas à récupérer la connexion, l’événement disconnected est déclenché.
client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});
  1. L’événement stopped est déclenché lorsque le client est déconnecté et le client cesse de tenter de se reconnecter. Cela se produit généralement après l’appel du client.stop(), ou autoReconnect est désactivé ou une limite spécifiée pour essayer de se reconnecter a atteint. Si vous souhaitez redémarrer le client, vous pouvez appeler client.start() dans l’événement arrêté.
// Registers a listener for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Utiliser un serveur de négociation pour générer programmatiquement l’URL d’accès client

En production, les clients récupèrent généralement l’URL d’accès client à partir d’un serveur d’applications. Le serveur contient la chaîne de connexion à votre ressource Web PubSub et génère l’URL d’accès client avec l’aide de la bibliothèque de serveurs @azure/web-pubsub.

1. Serveur d’applications

L’extrait de code ci-dessous est un exemple de serveur d’applications qui expose un chemin d’accès /negotiate et retourne l’URL d’accès client.

// This code snippet uses the popular Express framework
const express = require('express');
const app = express();
const port = 8080;

// Imports the server library, which is different from the client library
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
const hubName = 'sample_chat';

const serviceClient = new WebPubSubServiceClient("<web-pubsub-connectionstring>", hubName);

// Note that the token allows the client to join and send messages to any groups. It is specified with the "roles" option.
app.get('/negotiate', async (req, res) => {
  const token = await serviceClient.getClientAccessToken({roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
  res.json({
    url: token.url
  });
});

app.listen(port, () => console.log(`Application server listening at http://localhost:${port}/negotiate`));

2. Côté client

L’extrait de code ci-dessous est un exemple du côté client.

const { WebPubSubClient } = require("@azure/web-pubsub-client")

const client = new WebPubSubClient({
  getClientAccessUrl: async () => {
    const value = await (await fetch(`/negotiate`)).json();
    return value.url;
  }
});

await client.start();

Pour afficher le code complet de cet exemple, reportez-vous à samples-browser .

Un client consomme des messages à partir du serveur d’applications ou des groupes joints

Un client peut ajouter des rappels pour consommer des messages à partir de votre serveur d’applications ou groupes. Notez que, pour group-message événement, le client peut uniquement recevoir des messages de groupe qu’il a joints.

// Registers a listener for the "server-message". The callback will be invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.on("server-message", (e) => {
  console.log(`Received message ${e.message.data}`);
});

// Registers a listener for the "group-message". The callback will be invoked when the client receives a message from the groups it has joined.
client.on("group-message", (e) => {
    console.log(`Received message from ${e.message.group}: ${e.message.data}`);
});

Gérer l’échec de jointeur

Lorsqu’un client est déconnecté et ne parvient pas à récupérer, tous les contextes de groupe sont nettoyés dans votre ressource Web PubSub. Cela signifie que lorsque le client se reconnecte, il doit rejoindre des groupes. Par défaut, le client a autoRejoinGroup option activée.

Toutefois, vous devez connaître les limitations de autoRejoinGroup.

  • Le client peut uniquement rejoindre des groupes qu’il est joint à l’origine par le code client pas par le code côté serveur.
  • Les opérations de « jonction de groupe » peuvent échouer en raison de diverses raisons, par exemple, le client n’a pas l’autorisation de rejoindre les groupes. Dans ce cas, vous devez ajouter un rappel pour gérer cette défaillance.
// By default autoRejoinGroups=true. You can disable it by setting to false.
const client = new WebPubSubClient("<client-access-url>", { autoRejoinGroups: true });

// Registers a listener to handle "rejoin-group-failed" event
client.on("rejoin-group-failed", e => {
  console.log(`Rejoin group ${e.group} failed: ${e.error}`);
})

Opération et nouvelle tentative

Par défaut, l’opération telle que client.joinGroup(), client.leaveGroup(), client.sendToGroup(), client.sendEvent() a trois nouvelles tentatives. Vous pouvez configurer via le messageRetryOptions. Si toutes les nouvelles tentatives ont échoué, une erreur est levée. Vous pouvez continuer à réessayer en transmettant les mêmes ackId que les nouvelles tentatives précédentes afin que le service Web PubSub puisse dédupliquer l’opération.

try {
  await client.joinGroup(groupName);
} catch (err) {
  let id = null;
  if (err instanceof SendMessageError) {
    id = err.ackId;
  }
  await client.joinGroup(groupName, {ackId: id});
}

Spécifier le sous-protocole

Vous pouvez modifier le sous-protocole à utiliser par le client. Par défaut, le client utilise json.reliable.webpubsub.azure.v1. Vous pouvez choisir d’utiliser json.reliable.webpubsub.azure.v1 ou json.webpubsub.azure.v1.

// Change to use json.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonProtocol() });

// Change to use json.reliable.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonReliableProtocol() });

Concepts clés

Connexion

Une connexion, également appelée client ou connexion cliente, représente une connexion WebSocket individuelle connectée à Web PubSub. Une fois connecté, un ID de connexion unique est affecté à cette connexion par web PubSub. Chaque WebPubSubClient crée sa propre connexion exclusive.

Récupération

Si un client utilisant des protocoles fiables se déconnecte, un nouveau WebSocket tente d’établir à l’aide de l’ID de connexion de la connexion perdue. Si la nouvelle connexion WebSocket est correctement connectée, la connexion est récupérée. Pendant toute la déconnexion d’un client, le service conserve le contexte du client ainsi que tous les messages auxquels le client a été abonné et lorsque le client se rétablit, le service envoie ces messages au client. Si le service retourne le code d’erreur WebSocket 1008 ou si la tentative de récupération dure plus de 30 secondes, la récupération échoue.

Reconnecter

La reconnexion se produit lorsque la connexion cliente tombe et ne parvient pas à récupérer. La reconnexion démarre une nouvelle connexion et la nouvelle connexion a un nouvel ID de connexion. Contrairement à la récupération, le service traite le client reconnecté comme une nouvelle connexion cliente. La connexion cliente doit rejoindre des groupes. Par défaut, la bibliothèque cliente rejoint des groupes après la reconnexion.

Centre

Un hub est un concept logique pour un ensemble de connexions clientes. En règle générale, vous utilisez un hub à un seul usage, par exemple, un hub de conversation ou un hub de notification. Lorsqu’une connexion cliente est créée, elle se connecte à un hub et pendant sa durée de vie, elle appartient à ce hub. Différentes applications peuvent partager un web PubSub à l’aide de noms de hub différents.

Groupe

Un groupe est un sous-ensemble de connexions au hub. Vous pouvez ajouter une connexion cliente à un groupe ou supprimer la connexion cliente du groupe, chaque fois que vous le souhaitez. Par exemple, lorsqu’un client rejoint une salle de conversation ou lorsqu’un client quitte la salle de conversation, cette salle de conversation peut être considérée comme un groupe. Un client peut joindre plusieurs groupes et un groupe peut contenir plusieurs clients.

Utilisateur

Les connexions à Web PubSub peuvent appartenir à un utilisateur. Un utilisateur peut avoir plusieurs connexions, par exemple lorsqu’un seul utilisateur est connecté sur plusieurs appareils ou sur plusieurs onglets de navigateur.

Durée de vie du client

Chacun des clients Web PubSub est sûr de mettre en cache et d’être utilisé en tant que singleton pour la durée de vie de l’application. Les rappels d’événements inscrits partagent la même durée de vie avec le client. Cela signifie que vous pouvez ajouter ou supprimer des rappels à tout moment et que l’état d’inscription ne change pas après la reconnexion ou l’arrêt du client.

JavaScript Bundle

Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez d’abord utiliser un bundler. Pour plus d’informations sur la procédure à suivre, reportez-vous à notre documentation de regroupement .

Dépannage

  • Activer les journaux

    Vous pouvez définir la variable d’environnement suivante pour obtenir les journaux de débogage lors de l’utilisation de cette bibliothèque.

export AZURE_LOG_LEVEL=verbose

Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentation du package@azure/enregistreur d’événements.

  • Trace dynamique

    Utilisez 'outil Live Trace à partir du portail Web PubSub pour afficher le trafic en direct.

Ressources additionnelles

Contribuant

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

  • Last updated on