Bibliothèque de client du service Azure Web PubSub pour JavaScript - version 1.1.3
service Azure Web PubSub est un service géré par Azure qui permet aux développeurs de créer facilement des applications web avec des fonctionnalités en temps réel et un modèle de publication-abonnement. Tout scénario nécessitant une messagerie de publication-abonnement en temps réel entre le serveur et les clients ou parmi les clients peut utiliser le service Azure Web PubSub. Les fonctionnalités en temps réel traditionnelles qui nécessitent souvent l’interrogation à partir du serveur ou l’envoi de requêtes HTTP peuvent également utiliser le service Azure Web PubSub.
Vous pouvez utiliser cette bibliothèque côté serveur d’applications pour gérer les connexions clientes WebSocket, comme illustré dans le diagramme ci-dessous :
.
- Envoyez des messages à des hubs et des groupes.
- Envoyez des messages à des utilisateurs et des connexions particuliers.
- Organisez les utilisateurs et les connexions en groupes.
- Fermer les connexions
- Accorder, révoquer et vérifier les autorisations pour une connexion existante
Vous trouverez plus d’informations sur les termes utilisés ici dans section Concepts clés.
documentation de référence sur le code source | Package (NPM) | | Documentation produit | Exemples
Commencer
Environnements actuellement pris en charge
Conditions préalables
1. Installer le package @azure/web-pubsub
npm install @azure/web-pubsub
2. Créer et authentifier un WebPubSubServiceClient
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
Vous pouvez également authentifier le WebPubSubServiceClient
à l’aide d’un point de terminaison et d’un AzureKeyCredential
:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const key = new AzureKeyCredential("<Key>");
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");
Ou authentifiez le WebPubSubServiceClient
à l’aide de Azure Active Directory
- Installer la dépendance
@azure/identity
npm install @azure/identity
- Mettez à jour le code source pour utiliser
DefaultAzureCredential
:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const { DefaultAzureCredential } = require("@azure/identity");
const key = new DefaultAzureCredential();
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");
Concepts clés
Connexion
Une connexion, également appelée client ou connexion cliente, représente une connexion WebSocket individuelle connectée au service Web PubSub. Une fois connecté, un ID de connexion unique est affecté à cette connexion par le service Web PubSub.
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 service Azure 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.
Message
Lorsque le client est connecté, il peut envoyer des messages à l’application en amont ou recevoir des messages de l’application en amont via la connexion WebSocket.
Exemples
Obtenir le jeton d’accès d’un client pour démarrer la connexion WebSocket
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
// Get the access token for the WebSocket client connection to use
let token = await serviceClient.getClientAccessToken();
// Or get the access token and assign the client a userId
token = await serviceClient.getClientAccessToken({ userId: "user1" });
// Or get the access token that the client will join group GroupA when it connects using the access token
token = await serviceClient.getClientAccessToken({ userId: "user1", groups: [ "GroupA" ] });
// return the token to the WebSocket client
Diffuser des messages vers toutes les connexions dans un hub
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
// Send a JSON message
await serviceClient.sendToAll({ message: "Hello world!" });
// Send a plain text message
await serviceClient.sendToAll("Hi there!", { contentType: "text/plain" });
// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToAll(payload.buffer);
Envoyer des messages à toutes les connexions dans un hub avec la syntaxe de filtre OData
Pour plus d’informations sur filter
syntaxe, consultez syntaxe de filtre OData pour Azure Web PubSub.
const { WebPubSubServiceClient, odata } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
// Send a JSON message to anonymous connections
await serviceClient.sendToAll(
{ message: "Hello world!" },
{ filter: "userId eq null" }
);
// Send a text message to connections in groupA but not in groupB
const groupA = 'groupA';
const groupB = 'groupB';
await serviceClient.sendToAll(
"Hello world!",
{
contentType: "text/plain",
// use plain text "'groupA' in groups and not('groupB' in groups)"
// or use the odata helper method
filter: odata`${groupA} in groups and not(${groupB} in groups)`
});
Envoyer des messages à toutes les connexions d’un groupe
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
const groupClient = serviceClient.group("<groupName>");
// Add user to the group
await groupClient.addUser("user1");
// Send a JSON message
await groupClient.sendToAll({ message: "Hello world!" });
// Send a plain text message
await groupClient.sendToAll("Hi there!", { contentType: "text/plain" });
// Send a binary message
const payload = new Uint8Array(10);
await groupClient.sendToAll(payload.buffer);
Envoyer des messages à toutes les connexions d’un utilisateur
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
// Send a JSON message
await serviceClient.sendToUser("user1", { message: "Hello world!" });
// Send a plain text message
await serviceClient.sendToUser("user1", "Hi there!", { contentType: "text/plain" });
// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToUser("user1", payload.buffer);
Vérifier si le groupe a une connexion
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const WebSocket = require("ws");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
const groupClient = serviceClient.group("<groupName>");
// close all the connections in the group
await groupClient.closeAllConnections({ reason: "<closeReason>" });
// check if the group has any connections
const hasConnections = await serviceClient.groupExists("<groupName>");
Accéder à la réponse HTTP brute pour une opération
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
function onResponse(rawResponse) {
console.log(rawResponse);
}
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });
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.
- Obtention des journaux de débogage à partir de la bibliothèque cliente SignalR
export AZURE_LOG_LEVEL=verbose
Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentationdu package
Trace dynamique
Utilisez de trace dynamique à partir du portail du service Web PubSub pour afficher le trafic en direct.
Étapes suivantes
Consultez les exemples répertoire pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque.
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.
Projets connexes
Azure SDK for JavaScript