Partager via

Bibliothèque de client du service Azure Web PubSub pour JavaScript - version 1.1.3

  • Article

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 :

dépassement de capacité .

  • 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

  • Un abonnement Azure .
  • Instance de service Azure Web PubSub existante.

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

  1. Installer la dépendance @azure/identity
npm install @azure/identity
  1. 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 @azure/enregistreur d’événements.

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.