Partager via

Bibliothèque cliente du service Azure Web PubSub pour JavaScript - version 1.2.0

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

1. Installer le package @azure/web-pubsub

npm install @azure/web-pubsub

2. Créer et authentifier un WebPubSubServiceClient

import { WebPubSubServiceClient } from "@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:

import { AzureKeyCredential, WebPubSubServiceClient } from "@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:
import { DefaultAzureCredential } from "@azure/identity";
import { WebPubSubServiceClient } from "@azure/web-pubsub";

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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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"] });

Diffuser des messages vers toutes les connexions dans un hub

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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.

import { WebPubSubServiceClient, odata } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

function onResponse(rawResponse) {
  console.log(rawResponse);
}

await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

Dépannage

Activer les journaux

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info.

export AZURE_LOG_LEVEL=verbose

Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

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.

  • Last updated on