Freigeben über

Web PubSub-Clientbibliothek für JavaScript

Azure Web PubSub ist ein Clouddienst, mit dem Entwickler problemlos Echtzeitfeatures in Webanwendungen mit Veröffentlichungsabonnentmustern erstellen können.

Jedes Szenario, das Echtzeitnachrichten zwischen Server und Clients oder zwischen Clients nach Veröffentlichungsabonnentmustern erfordert, kann von der Verwendung von Web PubSub profitieren. Entwickler müssen den Server nicht mehr abrufen, indem wiederholte HTTP-Anforderungen in Intervallen gesendet werden, was verschwendet und schwer zu skalieren ist.

Wie im folgenden Diagramm dargestellt, richten Ihre Clients WebSocket-Verbindungen mit Ihrer Web PubSub-Ressource ein. Diese Clientbibliothek:

  • vereinfacht die Verwaltung von Clientverbindungen
  • vereinfacht das Senden von Nachrichten zwischen Clients
  • automatische Wiederholungen nach unbeabsichtigten Abbrüchen der Clientverbindung
  • zuverlässige Lieferungen von Nachrichten in Nummer und Reihenfolge nach der Wiederherstellung von Verbindungsabbrüchen

Überlauf

Details zu den hier verwendeten Begriffen werden in Wichtigsten Konzepten Abschnitt beschrieben.

Diese Bibliothek wird auf NPM-gehostet.

Erste Schritte

Derzeit unterstützte Umgebungen

Voraussetzungen

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

npm install @azure/web-pubsub-client

2. Herstellen einer Verbindung mit Ihrer Web PubSub-Ressource

Ein Client verwendet eine Clientzugriffs-URL, um eine Verbindung mit dem Dienst herzustellen und zu authentifizieren, die einem Muster von wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>folgt. Ein Client kann einige Möglichkeiten zum Abrufen der Clientzugriffs-URL haben. Für diesen Schnellstart können Sie eins aus dem unten gezeigten Azure-Portal kopieren und einfügen. (Für die Produktion erhalten Ihre Clients in der Regel die Clientzugriffs-URL auf Ihrem Anwendungsserver. Siehe Details unten )

get_client_url

Wie im obigen Diagramm gezeigt, verfügt der Client über die Berechtigungen zum Senden von Nachrichten an eine bestimmte Gruppe mit dem Namen "Gruppe1".

// 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. Gruppen beitreten

Beachten Sie, dass ein Client nur Nachrichten von Gruppen empfangen kann, denen er beigetreten ist, und Sie müssen einen Rückruf hinzufügen, um die Logik beim Empfangen von Nachrichten anzugeben.

// ...continues the code snippet from above

// Specifies the group to join
const 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. Senden von Nachrichten an eine Gruppe

// ...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.

Beispiele

Hinzufügen von Rückrufen für verbundene, getrennte und beendete Ereignisse

  1. Wenn ein Client erfolgreich mit Ihrer Web PubSub-Ressource verbunden ist, wird das connected-Ereignis ausgelöst.
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
  1. Wenn ein Client getrennt wird und die Verbindung nicht wiederhergestellt werden kann, wird das disconnected-Ereignis ausgelöst.
client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});
  1. Das stopped-Ereignis wird ausgelöst, wenn der Client getrennt wird und der Client nicht mehr versucht, eine erneute Verbindung herzustellen. Dies geschieht in der Regel, nachdem die client.stop() aufgerufen wurde, oder autoReconnect deaktiviert ist oder ein festgelegter Grenzwert für den Versuch, die Verbindung wiederherzustellen, erreicht wurde. Wenn Sie den Client neu starten möchten, können Sie client.start() im angehaltenen Ereignis aufrufen.
// Registers a listener for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Verwenden eines Aushandlungsservers zum programmgesteuerten Generieren der Clientzugriffs-URL

In der Produktion rufen Clients in der Regel die Clientzugriffs-URL von einem Anwendungsserver ab. Der Server enthält die Verbindungszeichenfolge mit Ihrer Web PubSub-Ressource und generiert die Clientzugriffs-URL mithilfe der Serverbibliothek @azure/web-pubsub.

1. Anwendungsserver

Der folgende Codeausschnitt ist ein Beispiel für einen Anwendungsserver, der einen /negotiate Pfad verfügbar macht und die Clientzugriffs-URL zurückgibt.

// 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) => {
  const 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. Clientseite

Der folgende Codeausschnitt ist ein Beispiel für die Clientseite.

const { WebPubSubClient } = require("@azure/web-pubsub-client")

const client = new WebPubSubClient({
  getClientAccessUrl: async () => {
    const value = await (await fetch(`/negotiate`)).json();
    return value.url;
  }
});

await client.start();

Den vollständigen Code dieses Beispiels finden Sie unter Beispielbrowser-.

Ein Client nutzt Nachrichten vom Anwendungsserver oder verknüpften Gruppen.

Ein Client kann Rückrufe hinzufügen, um Nachrichten von Ihrem Anwendungsserver oder -gruppen zu nutzen. Bitte beachten Sie, dass der Client für group-message Ereignis nur gruppennachrichten empfangen kann, die er beigetreten ist,.

// Registers a listener for the "server-message". The callback will be 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 will be 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}`);
});

Behandeln eines Erneutverknüpfungsfehlers

Wenn ein Client getrennt wird und nicht wiederhergestellt werden kann, werden alle Gruppenkontexte in Ihrer Web PubSub-Ressource bereinigt. Dies bedeutet, dass der Client erneut eine Verbindung herstellen muss, um Gruppen erneut anzuordnen. Standardmäßig ist der Client autoRejoinGroup Option aktiviert.

Beachten Sie jedoch die Einschränkungen autoRejoinGroup.

  • Der Client kann nur Gruppen erneut beitreten, die ursprünglich vom Clientcode verknüpft sind, nicht vom serverseitigen Code.
  • Vorgänge "Erneut beitreten" können aufgrund verschiedener Gründe fehlschlagen, z. B. dass der Client nicht über die Berechtigung zum Beitreten zu den Gruppen verfügt. In solchen Fällen müssen Sie einen Rückruf hinzufügen, um diesen Fehler zu behandeln.
// 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}`);
})

Vorgang und Wiederholen

Standardmäßig weist der Vorgang wie client.joinGroup(), client.leaveGroup(), client.sendToGroup(), client.sendEvent() drei Wiederholungen auf. Sie können über die messageRetryOptionskonfigurieren. Wenn alle Wiederholungen fehlgeschlagen sind, wird ein Fehler ausgelöst. Sie können den Vorgang weiterhin wiederholen, indem Sie dieselbe ackId wie vorherige Wiederholungen übergeben, damit der Web PubSub-Dienst den Vorgang deduplizieren kann.

try {
  await client.joinGroup(groupName);
} catch (err) {
  let id = null;
  if (err instanceof SendMessageError) {
    id = err.ackId;
  }
  await client.joinGroup(groupName, {ackId: id});
}

Unterprotocol angeben

Sie können das Vom Client verwendete Unterprotocol ändern. Standardmäßig verwendet der Client json.reliable.webpubsub.azure.v1. Sie können json.reliable.webpubsub.azure.v1 oder json.webpubsub.azure.v1verwenden.

// Change to use json.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonProtocol() });

// Change to use json.reliable.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonReliableProtocol() });

Schlüsselkonzepte

Verbindung

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

Genesung

Wenn ein Client, der zuverlässige Protokolle verwendet, getrennt wird, versucht ein neues WebSocket, die Verbindungs-ID der verlorenen Verbindung zu verwenden. Wenn die neue WebSocket-Verbindung erfolgreich verbunden ist, wird die Verbindung wiederhergestellt. Während der Verbindung eines Clients behält der Dienst den Kontext des Clients sowie alle Nachrichten bei, die der Client abonniert hat, und wenn der Client wiederhergestellt wird, sendet der Dienst diese Nachrichten an den Client. Wenn der Dienst den WebSocket-Fehlercode 1008 zurückgibt oder der Wiederherstellungsversuch länger als 30 Sekunden dauert, schlägt die Wiederherstellung fehl.

Wiederverbinden

Eine erneute Verbindung erfolgt, wenn die Clientverbindung abbricht und nicht wiederhergestellt werden kann. Die erneute Verbindung startet eine neue Verbindung, und die neue Verbindung verfügt über eine neue Verbindungs-ID. Im Gegensatz zur Wiederherstellung behandelt der Dienst den erneut verbundenen Client als neue Clientverbindung. Die Clientverbindung muss erneut an Gruppen teilnehmen. Standardmäßig werden in der Clientbibliothek Gruppen nach der erneuten Verbindung erneut verknüpft.

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 ein Web PubSub 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.

Clientlebensdauer

Jeder der Web PubSub-Clients kann zwischengespeichert und als Singleton für die Lebensdauer der Anwendung verwendet werden. Die registrierten Ereignisrückrufe haben dieselbe Lebensdauer für den Client. Dies bedeutet, dass Sie Rückrufe jederzeit hinzufügen oder entfernen können, und der Registrierungsstatus ändert sich nicht, nachdem die Verbindung erneut verbunden wurde oder der Client beendet wurde.

JavaScript-Bündel

Um diese Clientbibliothek im Browser zu verwenden, müssen Sie zuerst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

Fehlerbehebung

  • Aktivieren von Protokollen

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

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-Tool aus dem Web PubSub-Portal, um den Livedatenverkehr anzuzeigen.

Weitere Ressourcen

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.

  • Last updated on