Freigeben über

Azure Web PubSub-Dienstclientbibliothek für JavaScript – Version 1.1.3

  • Artikel

Azure Web PubSub-Dienst ist ein von Azure verwalteter Dienst, der Entwicklern hilft, Webanwendungen mit Echtzeitfeatures und Veröffentlichungsabonnentmustern auf einfache Weise zu erstellen. Jedes Szenario, für das echtzeitbasierte Veröffentlichungsnachrichten zwischen Server und Clients oder zwischen Clients erforderlich sind, können den Azure Web PubSub-Dienst verwenden. Herkömmliche Echtzeitfeatures, die häufig eine Abfrage vom Server oder das Senden von HTTP-Anforderungen erfordern, können auch den Azure Web PubSub-Dienst verwenden.

Sie können diese Bibliothek auf Der App-Serverseite verwenden, um die WebSocket-Clientverbindungen zu verwalten, wie im folgenden Diagramm dargestellt:

Überlauf .

  • Nachrichten an Hubs und Gruppen senden.
  • Nachrichten an bestimmte Benutzer und Verbindungen senden.
  • Organisieren Sie Benutzer und Verbindungen in Gruppen.
  • Schließen von Verbindungen
  • Erteilen, Widerrufen und Überprüfen von Berechtigungen für eine vorhandene Verbindung

Details zu den hier verwendeten Begriffen werden im Abschnitt Schlüsselkonzepte beschrieben.

Quellcode | Package (NPM) | API-Referenzdokumentation | Produktdokumentation | Beispiele

Erste Schritte

Derzeit unterstützte Umgebungen

Voraussetzungen

1. Installieren des @azure/web-pubsub-Pakets

npm install @azure/web-pubsub

2. Erstellen und Authentifizieren eines WebPubSubServiceClient

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

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

Sie können die WebPubSubServiceClient auch mithilfe eines Endpunkts und einer AzureKeyCredentialauthentifizieren:

const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");

const key = new AzureKeyCredential("<Key>");
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");

Oder authentifizieren Sie die WebPubSubServiceClient mit Azure Active Directory-

  1. Installieren der @azure/identity Abhängigkeit
npm install @azure/identity
  1. Aktualisieren Sie den Quellcode, um DefaultAzureCredentialzu verwenden:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const { DefaultAzureCredential } = require("@azure/identity");

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

Schlüsselkonzepte

Verbindung

Eine Verbindung, die auch als Client oder Clientverbindung bezeichnet wird, stellt eine einzelne WebSocket-Verbindung dar, die mit dem Web PubSub-Dienst verbunden ist. Wenn die Verbindung erfolgreich hergestellt wurde, wird dieser Verbindung eine eindeutige Verbindungs-ID vom Web PubSub-Dienst zugewiesen.

Nabe

Ein Hub ist ein logisches Konzept für eine Reihe von Clientverbindungen. In der Regel verwenden Sie einen Hub für einen Zweck, z. B. einen Chat-Hub oder einen Benachrichtigungshub. Wenn eine Clientverbindung erstellt wird, wird eine Verbindung mit einem Hub hergestellt, und während der Lebensdauer gehört sie zu diesem Hub. Verschiedene Anwendungen können einen Azure Web PubSub-Dienst mit unterschiedlichen Hubnamen teilen.

Gruppe

Eine Gruppe ist eine Teilmenge von Verbindungen mit dem Hub. Sie können einer Gruppe eine Clientverbindung hinzufügen oder die Clientverbindung jederzeit aus der Gruppe entfernen. Wenn beispielsweise ein Client einem Chatroom beitritt oder ein Client den Chatroom verlässt, kann dieser Chatroom als Gruppe betrachtet werden. Ein Client kann mehreren Gruppen beitreten, und eine Gruppe kann mehrere Clients enthalten.

Benutzer

Verbindungen mit Web PubSub können einem Benutzer angehören. Ein Benutzer kann mehrere Verbindungen haben, z. B. wenn ein einzelner Benutzer über mehrere Geräte oder mehrere Browserregisterkarten verbunden ist.

Nachricht

Wenn der Client verbunden ist, kann er Nachrichten über die WebSocket-Verbindung an die upstream-Anwendung senden oder Nachrichten von der upstream-Anwendung empfangen.

Beispiele

Abrufen des Zugriffstokens für einen Client zum Starten der WebSocket-Verbindung

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

Übertragen von Nachrichten an alle Verbindungen in einem 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);

Senden von Nachrichten an alle Verbindungen in einem Hub mit OData-Filtersyntax

Details zur filter Syntax finden Sie unter OData-Filtersyntax für 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)` 
  });

Senden von Nachrichten an alle Verbindungen in einer Gruppe

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);

Senden von Nachrichten an alle Verbindungen für einen Benutzer

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);

Überprüfen, ob die Gruppe über eine Verbindung verfügt

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>");

Zugreifen auf die unformatierte HTTP-Antwort für einen Vorgang

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 });

Fehlerbehebung

Aktivieren von Protokollen

Sie können die folgende Umgebungsvariable festlegen, um die Debugprotokolle abzurufen, wenn Sie diese Bibliothek verwenden.

  • Abrufen von Debugprotokollen aus der SignalR-Clientbibliothek
export AZURE_LOG_LEVEL=verbose

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Live-Ablaufverfolgung

Verwenden Sie Live Trace- aus dem Web PubSub-Dienstportal, um den Livedatenverkehr anzuzeigen.

Nächste Schritte

Ausführliche Beispiele zur Verwendung dieser Bibliothek finden Sie in den Beispielen Verzeichnis.

Beitragend

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.