Kit de développement logiciel (SDK) côté client Web PubSub pour JavaScript
Remarque
Des détails sur les termes utilisés ici sont décrits dans l’article sur les concepts clés.
Le Kit de développement logiciel (SDK) côté client vise à accélérer le flux de travail du développeur ; plus précisément,
- 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
Comme illustré dans le diagramme, vos clients établissent des connexions WebSocket avec votre ressource Web PubSub.
Bien démarrer
Prérequis
- Versions LTS de Node.js
- Un abonnement Azure
- Ressource Web PubSub
1. Installez le package @azure/web-pubsub-client
npm install @azure/web-pubsub-client
2. Connecter avec votre ressource Web PubSub
Un client utilise Client Access URL
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 Client Access URL
. Pour ce guide rapide, vous pouvez copier et coller un à partir de Portail Azure affiché. (Pour la production, vos clients sont Client Access URL
généralement générés sur votre serveur d’applications. Voir les détails )
Comme indiqué dans le diagramme, le client dispose des autorisations nécessaires pour envoyer et joindre 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
Un client ne peut recevoir que des messages provenant de groupes qu’il a joints. Vous pouvez ajouter un rappel pour spécifier la logique de ce qu’il faut faire lors de la réception de messages.
// ...continues the code snippet from above
// Specifies the group to join
let 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
Gérer connected
, disconnected
et stopped
les événements
Azure Web PubSub déclenche des événements système tels que connected
, disconnected
et stopped
. Vous pouvez inscrire des gestionnaires d’événements pour déterminer ce que le programme doit faire lorsque les événements sont déclenchés.
- Lorsqu’un client est correctement connecté à votre ressource Web PubSub, l’événement
connected
est déclenché. Cet extrait de code imprime simplement l’ID de connexion
client.on("connected", (e) => {
console.log(`Connection ${e.connectionId} is connected.`);
});
- Lorsqu’un client est déconnecté et ne parvient pas à récupérer la connexion, l’événement
disconnected
est déclenché. Cet extrait de code imprime simplement le message.
client.on("disconnected", (e) => {
console.log(`Connection disconnected: ${e.message}`);
});
- L’événement
stopped
est déclenché lorsque le client est déconnecté et que le client cesse de tenter de se reconnecter. Cela se produit généralement après l’appelclient.stop()
, ouautoReconnect
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 appelerclient.start()
l’événement arrêté.
// Registers an event handler for the "stopped" event
client.on("stopped", () => {
console.log(`Client has stopped`);
});
Utiliser un serveur d’applications pour générer Client Access URL
programmatiquement
En production, les clients récupèrent Client Access URL
généralement à partir d’un serveur d’applications. Le serveur contient la connection string
ressource Web PubSub et génère l’aide Client Access URL
de la bibliothèque @azure/web-pubsub
côté serveur.
1. Serveur d’applications
L’extrait de code est un exemple de serveur d’applications expose un /negotiate
point de terminaison et retourne Client Access URL
.
// 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) => {
let 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
const { WebPubSubClient } = require("@azure/web-pubsub-client")
const client = new WebPubSubClient({
getClientAccessUrl: async () => {
let value = await (await fetch(`/negotiate`)).json();
return value.url;
}
});
await client.start();
Remarque
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 d’un serveur d’applications ou de groupes.
// Registers a listener for the "server-message". The callback is 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 is 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}`);
});
Remarque
Pour group-message
l’événement, le client peut uniquement recevoir des messages des groupes qu’il a joints.
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 propre dans votre ressource Web PubSub. Cela signifie que lorsque le client se reconnecte, il doit rejoindre des groupes. Par défaut, le client a l’option autoRejoinGroup
activée.
Toutefois, vous devez connaître autoRejoinGroup
les limitations de l’application.
- Le client peut uniquement rejoindre des groupes qu’il a rejoints par le code client et non par le code côté serveur.
- Les opérations « Rejoindre un 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}`);
})
Réessayer
Par défaut, l’opération telle que client.joinGroup()
, client.leaveGroup()
, client.sendToGroup()
a client.sendEvent()
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
tentatives 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});
}
JavaScript Bundle
Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez utiliser un bundler. Pour plus d’informations sur la création d’un bundle, reportez-vous à notre documentation de regroupement.
Résolution des problèmes
Activer les journaux d’activité
Vous pouvez définir la variable d’environnement suivante pour afficher les journaux de débogage quand vous utilisez cette bibliothèque.
export AZURE_LOG_LEVEL=verbose
Pour obtenir des instructions plus détaillées sur l’activation des journaux, consultez les documents relatifs au package @azure/logger.
Trace dynamique
Utilisez l’outil Live Trace à partir de Portail Azure pour inspecter le trafic des messages en direct via votre ressource Web PubSub.