Freigeben über

Azure Web PubSub CloudEvents-Handler für Express

  • Artikel

Der Azure Web PubSub-Dienst ist ein verwalteter Azure-Dienst, der Entwicklern die einfache Erstellung von Webanwendungen mit Echtzeitfunktionen und einem Veröffentlichen-Abonnieren-Muster ermöglicht. Der Azure Web PubSub-Dienst kann in allen Szenarien verwendet werden, für die Veröffentlichen-Abonnieren-Messaging in Echtzeit zwischen Server und Clients oder zwischen Clients erforderlich ist. Herkömmliche Echtzeitfeatures, die häufig das Abrufen vom Server oder das Übermitteln von HTTP-Anforderungen erfordern, können ebenfalls den Azure Web PubSub-Dienst verwenden.

Wenn eine WebSocket-Verbindung hergestellt wird, transformiert der Web PubSub-Dienst den Verbindungslebenszyklus und Nachrichten in Ereignisse im CloudEvents-Format. Diese Bibliothek stellt eine Express-Middleware zum Verarbeiten von Ereignissen zur Verfügung, die den Lebenszyklus und die Nachrichten der WebSocket-Verbindung darstellen, wie in der folgenden Abbildung gezeigt:

cloudevents

Details zu den hier verwendeten Begriffen werden im Abschnitt Wichtige Begriffe beschrieben.

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

Erste Schritte

Die derzeitig unterstützten Umgebungen

Voraussetzungen

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

npm install @azure/web-pubsub-express

2. Erstellen eines WebPubSubEventHandler

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat");

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Wichtige Begriffe

Verbindung

Eine Verbindung (auch Client oder Clientverbindung genannt) stellt eine einzelne WebSocket-Verbindung mit dem Web PubSub-Dienst dar. Wenn die Verbindung erfolgreich hergestellt wurde, wird ihr vom Web PubSub-Dienst eine eindeutige Verbindungs-ID zugewiesen.

Hub

Ein Hub ist ein logisches Konzept für eine Gruppe von Clientverbindungen. In der Regel wird jeweils ein einzelner Hub für einen einzelnen Zweck verwendet – beispielsweise ein Chathub oder ein Benachrichtigungshub. Eine Clientverbindung wird mit einem Hub hergestellt und gehört während ihrer Lebensdauer zu diesem Hub. Von verschiedenen Anwendungen können unterschiedliche Hubnamen verwendet werden, um gemeinsam einen einzelnen Azure Web PubSub-Dienst zu nutzen.

Group

Eine Gruppe ist eine Teilmenge der Verbindungen mit dem Hub. Sie können einer Gruppe eine Clientverbindung hinzufügen und sie jederzeit wieder aus der Gruppe entfernen. Beispiel: Wenn ein Client einem Chatroom beitritt oder wenn 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 zu einem einzelnen Benutzer gehören. Ein Benutzer kann über mehrere Verbindungen verfügen, etwa, wenn ein einzelner Benutzer über mehrere Geräte oder mehrere Browsertabs verbunden ist.

Clientereignisse

Ereignisse werden während des Lebenszyklus einer Clientverbindung erstellt. Eine einfache WebSocket-Clientverbindung erstellt z. B. ein connect-Ereignis, wenn versucht wird, eine Verbindung mit dem Dienst herzustellen, ein connected-Ereignis, wenn erfolgreich eine Verbindung mit dem Dienst hergestellt wurde, ein message-Ereignis, wenn Nachrichten an den Dienst gesendet werden und ein disconnected-Ereignis, wenn die Verbindung mit dem Dienst getrennt wird.

Ereignishandler

Der Event-Handler enthält die Logik zum Behandeln der Clientereignisse. Der Ereignishandler muss im Dienst über das Portal oder die Azure CLI im Voraus registriert und konfiguriert werden. Der Ort zum Hosten der Ereignishandlerlogik wird im Allgemeinen als serverseitig betrachtet.

Beispiele

Verarbeiten der connect-Anforderung und Zuweisen von <userId>

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      userId: "<userId>"
    });
  },
  allowedEndpoints: ["https://<yourAllowedService>.webpubsub.azure.com"]
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Nur angegebene Endpunkte zulassen

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  allowedEndpoints: [
    "https://<yourAllowedService1>.webpubsub.azure.com",
    "https://<yourAllowedService2>.webpubsub.azure.com"
  ]
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Festlegen des benutzerdefinierten Ereignishandlerpfads

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  path: "customPath1"
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  // Azure WebPubSub Upstream ready at http://localhost:3000/customPath1
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Festlegen und Lesen des Verbindungsstatus

const express = require("express");

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

const handler = new WebPubSubEventHandler("chat", {
  handleConnect(req, res) {
    // You can set the state for the connection, it lasts throughout the lifetime of the connection
    res.setState("calledTime", 1);
    res.success();
  },
  handleUserEvent(req, res) {
    var calledTime = req.context.states.calledTime++;
    console.log(calledTime);
    // You can also set the state here
    res.setState("calledTime", calledTime);
    res.success();
  }
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Problembehandlung

Aktivieren von Protokollen

Sie können die folgende Umgebungsvariable festlegen, um Debugprotokolle anzuzeigen, 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 der Paketdokumentation zu @azure/logger.

Live-Ablaufverfolgung

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

Nächste Schritte

Ausführliche Beispiele zur Verwendung dieser Bibliothek finden Sie im Beispielverzeichnis .

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.