Clientseitiges Web PubSub SDK für JavaScript

Hinweis

Details zu den hier verwendeten Begriffen finden Sie im Artikel zu den wichtigsten Konzepten .

Das clientseitige SDK zielt darauf ab, den Workflow des Entwicklers zu beschleunigen; genauer gesagt:

• 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

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

Erste Schritte

Voraussetzungen

• LTS-Versionen von Node.js
• Ein Azure-Abonnement
• Eine Web PubSub-Ressource

1. Installieren Sie das @azure/web-pubsub-client-Paket

npm install @azure/web-pubsub-client

2. Verbinden mit Ihrer Web PubSub-Ressource

Ein Client verwendet Client Access 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 Client Access URLhaben. In diesem Schnellleitfaden können Sie eines aus Azure-Portal kopieren und einfügen. (Für die Produktion werden Client Access URL Ihre Clients in der Regel auf Ihrem Anwendungsserver generiert. Siehe Details )

Wie im Diagramm gezeigt, verfügt der Client über die Berechtigungen zum Senden von Nachrichten an eine bestimmte Gruppe mit dem Namen group1und dem Beitritt zu einer bestimmten Gruppe.

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

Ein Client kann nur Nachrichten von Gruppen empfangen, denen er beigetreten ist. Sie können einen Rückruf hinzufügen, um die Logik anzugeben, was beim Empfangen von Nachrichten zu tun ist.

// ...continues the code snippet from above

// Specifies the group to join
let 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

disconnected Behandeln connectedvon Ereignissen und stopped Ereignissen

Azure Web PubSub löst Systemereignisse wie connected, disconnected und stopped. Sie können Ereignishandler registrieren, um zu entscheiden, was das Programm tun soll, wenn die Ereignisse ausgelöst werden.

1. Wenn ein Client erfolgreich mit Ihrer Web PubSub-Ressource verbunden ist, wird das connected Ereignis ausgelöst. Dieser Codeausschnitt druckt einfach die Verbindungs-ID aus.

client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});

2. Wenn ein Client getrennt wird und die Verbindung nicht wiederhergestellt werden kann, wird das disconnected Ereignis ausgelöst. Dieser Codeausschnitt druckt einfach die Nachricht aus.

client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});

3. Das stopped Ereignis wird ausgelöst, wenn der Client getrennt wird und der Client nicht mehr versucht, die Verbindung wiederherzustellen. Dies geschieht in der Regel nach dem client.stop() Aufruf oder deaktiviert oder autoReconnect ein angegebenes Limit, um die Verbindung wiederherzustellen, erreicht wurde. Wenn Sie den Client neu starten möchten, können Sie das angehaltene Ereignis aufrufen client.start() .

// Registers an event handler for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Verwenden eines Anwendungsservers zum programmgesteuerten Generieren Client Access URL

In der Produktion rufen Clients in der Regel von einem Anwendungsserver ab Client Access URL . Der Server enthält die connection string Web PubSub-Ressource und generiert die Client Access URL Hilfe aus der serverseitigen Bibliothek @azure/web-pubsub.

1. Anwendungsserver

Der Codeausschnitt ist ein Beispiel für einen Anwendungsserver, der einen /negotiate Endpunkt verfügbar macht und zurückgibt Client Access URL.

// 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) => {
  let 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

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

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

await client.start();

Hinweis

Den vollständigen Code dieses Beispiels finden Sie im Beispielbrowser.

---

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

Ein Client kann Rückrufe hinzufügen, um Nachrichten von einem Anwendungsserver oder gruppen zu nutzen.

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

Hinweis

Für group-message ein Ereignis kann der Client nur Nachrichten von den Gruppen empfangen, denen er beigetreten ist.

Behandeln eines Erneutverknüpfungsfehlers

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

Beachten Sie autoRejoinGroupjedoch die Einschränkungen.

• Der Client kann nur Gruppen erneut beitreten, denen er vom Clientcode hinzugefügt wurde, nicht vom serverseitigen Code.
• Vorgänge "Erneut beitreten" können aus verschiedenen Gründen fehlschlagen, z. B. verfügt der Client nicht über die Berechtigung zum Beitreten zu den Gruppen. 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}`);
})

Wiederholen

Standardmäßig weist der Vorgang wie client.joinGroup(), client.leaveGroup(), client.sendToGroup(), client.sendEvent() drei Wiederholungen auf. Sie können über die messageRetryOptions. Wenn alle Wiederholungen fehlgeschlagen sind, wird ein Fehler ausgelöst. Sie können den Vorgang weiterhin wiederholen, indem Sie dieselben Wiederholungen 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});
}

JavaScript-Bündel

Um diese Clientbibliothek im Browser zu verwenden, müssen Sie einen Bundler verwenden. Ausführliche Informationen zum Erstellen eines Bündels finden Sie in unserer Dokumentation zur Bündelung.

Problembehandlung

Aktivieren von Protokollen

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

export AZURE_LOG_LEVEL=verbose

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in der Paketdokumentation zu @azure/logger.

Live-Ablaufverfolgung

Verwenden Sie das Live Trace-Tool aus Azure-Portal, um den Datenverkehr von Livenachrichten über Ihre Web PubSub-Ressource zu prüfen.