Ereignisbenachrichtigungen von Clients

In den ersten drei Artikeln mit Schnellstarts haben Sie zwei nützliche Kommunikationsmuster kennengelernt, die Web PubSub für Echtzeitnachrichten im großen Stil (mehrere Millionen) verwenden.

• Pub/Sub zwischen Clients, die Ihren Anwendungsserver von der Komplexität der Verwaltung persistenter Verbindungen befreien
• Pushnachrichten von Ihrem Anwendungsserver an Clients, sobald neue Daten verfügbar sind

In diesem Schnellstart erfahren Sie mehr über das Ereignissystem von Web PubSub, mit dem Ihr Anwendungsserver auf Ereignisse reagieren kann, z. B. in folgenden Situationen:

• Ein Client ist connected.
• Ein Client sendet eine message, die eine weitere Verarbeitung erfordert.

Voraussetzungen

• Eine Web PubSub-Ressource. Wenn Sie noch keine Ressource erstellt haben, können Sie dieser Anleitung folgen: Erstellen einer Web PubSub-Ressource
• Ein Code-Editor wie Visual Studio Code
• Installieren der Abhängigkeiten für die Sprache, die Sie verwenden möchten

JavaScript

Node.js 12.x oder höher

Erstellen der Anwendung

Web PubSub ist ein eigenständiger Dienst für Ihren Anwendungsserver. Während Ihre Anwendung ihre Rolle als herkömmlicher HTTP-Server behält, übernimmt Web PubSub die Weitergabe in Echtzeit von Nachrichten zwischen Ihrem Anwendungsserver und den Clients. Zuerst erstellen Sie das Clientprogramm und dann das Serverprogramm.

Erstellen des Clients

JavaScript

1. Erstellen eines Verzeichnisses für die Client-App

mkdir eventHandlerDemo
cd eventHandlerDemo

# The SDK is available as an NPM module.
npm install @azure/web-pubsub-client

2. Herstellen einer Verbindung mit Web PubSub

Ein Client, sei es ein Browser, eine mobile App oder ein IoT-Gerät, verwendet eine Clientzugriffs-URL, um eine Verbindung mit Ihrer Ressource herzustellen und sich zu authentifizieren. Diese URL folgt dem Muster wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Ein Client kann die Clientzugriffs-URL mit verschiedenen Methoden abrufen. Für diese Schnellstartanleitung können Sie die im folgenden Diagramm gezeigte Datei aus dem Azure-Portal kopieren und einfügen. Es empfiehlt sich, die Clientzugriffs-URL in Ihrem Code nicht hart zu codieren. In der Produktionswelt richten wir normalerweise einen App-Server ein, um diese URL bei Bedarf zurückzugeben. Unter Generate Client Access URL (Generieren der URL für den Clientzugriff) wird die Vorgehensweise ausführlich beschrieben.

Erstellen einer Datei mit dem Namen client.js und Hinzufügen des folgenden Codes

const { WebPubSubClient } = require("@azure/web-pubsub-client");
// Instantiates the client object 
// <client-access-url> is copied from Azure portal mentioned above.
const client = new WebPubSubClient("<client-access-url>");

// Registers a handler to the "connected" event
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});

// You must invoke start() on the client object 
// to establish connection with your Web PubSub resource
client.start();

Erstellen des Anwendungsservers

JavaScript

1. Installieren von „express.js“ und des Web PubSub-Server SDK

npm init -y
npm install --save express

# Installs the middleware from Web PubSub. This middleware will set up an endpoint for you.
npm install --save @azure/web-pubsub-express 

2. Erstellen einer neuen Datei mit dem Namen „server.js“, die eine leere Express-App einrichtet

const express = require("express");

const app = express();

app.listen(8080, () => console.log('Server started, listening on port 8080'));

3. Behandeln von Ereignissen

Mit Web PubSub kann Ihr Anwendungsserver Handler für die Reaktion auf Ereignisse einrichten, wenn bestimmte Aktivitäten auf Clientseite ausgeführt werden (z. B. wenn ein Client connected oder disconnected mit Ihrer Web PubSub-Ressource ist).

Im Folgenden finden Sie zwei wichtige Anwendungsfälle:

• Wenn ein Client verbunden ist, können Sie diesen Status an alle verbundenen Clients übertragen.
• Wenn ein Client eine Nachricht an Ihre Web PubSub-Ressource sendet, können Sie die Nachricht in einer Datenbank Ihrer Wahl speichern.

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

const app = express();

const HUB_NAME = "myHub1";

let handler = new WebPubSubEventHandler(HUB_NAME, {
  path: '/eventhandler', // Exposes an endpoint 
  onConnected: async (req) => {
    console.log(`${req.context.userId} connected`);
  }, 
});

// Registers the middleware with the express app
app.use(handler.getMiddleware());

app.listen(8080, () => console.log('Server started, listening on port 8080'));

Wie im obigen Code konfiguriert, ruft Web PubSub, wenn ein Client eine Verbindung mit Ihrer Web PubSub-Ressource herstellt, den von Ihrem Anwendungsserver bereitgestellten Webhook unter dem Pfad /eventhandler auf. Hier geben Sie einfach die userId an der Konsole aus, wenn Benutzer*innen verbunden sind.

Verfügbarmachen des Localhost

Führen Sie das Programm aus. Es sollte auf localhost am Port 8080 ausgeführt werden. Für unsere Zwecke bedeutet dies, dass Ihre lokale Express-App nicht über das Internet erreichbar ist. Web PubSub kann also nicht den Webhook aufrufen, der unter dem Pfad /eventhandler bereitgestellt wird.

Es gibt zwei Möglichkeiten, den Datenverkehr an Ihren Localhost weiterzuleiten, einer besteht darin, localhost verfügbar zu machen, um über Tools wie ngrok und TunnelRelay auf das Internet zugreifen zu können. Eine weitere Möglichkeit und auch die empfohlene Möglichkeit besteht darin, AWP-Tunnel zum Tunneln des Datenverkehrs vom Web PubSub-Dienst über das Tool zu Ihrem lokalen Server zu verwenden.

AWPS-Tunnel

1. Herunterladen und Installieren des AWP-Tunnels

Das Tool wird auf Node.js , Version 16 oder höher, ausgeführt.

npm install -g @azure/web-pubsub-tunnel-tool

2. Verwenden des Diensts Verbindungszeichenfolge und Ausführen

export WebPubSubConnectionString="<your connection string>"
awps-tunnel run --hub myHub1 --upstream http://localhost:8080

Festlegen des Ereignishandlers für Ihre Web PubSub-Ressource

Nun müssen Sie Ihre Web PubSub-Ressource über diese Webhook-URL informieren. Sie können die Ereignishandler entweder über Azure-Portal oder über die Azure-Befehlszeilenschnittstelle festlegen.

Azure portal

1. Wählen Sie im Menü die Option Einstellungen und dann Hinzufügen aus.

2. Geben Sie einen Hubnamen ein. Geben Sie für in diesem Fall myHub1 ein, und wählen Sie Hinzufügen aus.

3. Konfigurieren Sie auf der Ereignishandlerseite bei Verwendung awps-tunnel des Tools die folgenden Felder, wobei die URL-Vorlage das Schema gefolgt vom Pfad verwendet tunnel : tunnel:///eventhandler

4. Speichern Sie Ihre Konfiguration.

Azure-Befehlszeilenschnittstelle

Wichtig

Ersetzen Sie <your-resource-group-name> durch den Namen der tatsächlichen Ressourcengruppe, die Ihre Web PubSub-Ressource enthält. Ersetzen Sie <your-unique-resource-name> durch den tatsächlichen Namen Ihrer Web PubSub-Ressource. Ersetzen Sie <domain-name> durch den von ngrok ausgegebenen Namen.

az webpubsub hub update --group "<your-resource-group-name>" --name "<your-unique-resource-name>" --hub-name "myHub1" --event-handler url-template="https://<domain-name>.ngrok.io/eventHandler" user-event-pattern="*" system-event="connected"

Ausführen der Programme

JavaScript

Starten des Anwendungsservers

node server.js

Starten des Clientprogramms

node client.js

Untersuchen des Ergebnisses

An der Konsole sollte userId ausgegeben werden.

Verarbeiten Sie das Nachrichtenereignis.

Neben Systemereignissen wie connect, connected und disconnected kann ein Client auch benutzerdefinierte Ereignisse senden.

Anpassen des Clientprogramms

Beenden Sie Ihr Clientprogramm, und fügen Sie den folgenden Code hinzu: client.js.

// ...code from before

client.start();

// The name of the event is message and the content is in text format.
client.sendEvent("message", "sending custom event!", "text");

Anpassen des Serverprogramms

Beenden Sie Ihr Clientprogramm, und fügen Sie den folgenden Code hinzu: server.js.

// ... code from before

let handler = new WebPubSubEventHandler(HUB_NAME, {
  path: "/eventhandler",
  onConnected: async (req) => {
    console.log(`"${req.context.userId}" is connected.`);
  },
  // This handler function will handle user system
  handleUserEvent: async (req, res) => {
    if (req.context.eventName === "message") {
      console.log(`Received message: ${req.data}`);
      // Additional logic to process the data,
      // e.g save message content to database 
      // or broadcast the message to selected clients.
    }
  },
});

//... code from before

Erneutes Starten von Clientprogramm und Serverprogramm

An der Konsole sollten die userId und Received message: sending custom event! ausgegeben werden.

Zusammenfassung

In diesem Tutorial haben Sie eine grundlegende Vorstellung davon erhalten, wie das Ereignissystem in Web PubSub funktioniert. In realen Anwendungen kann das Ereignissystem Ihnen helfen, zusätzliche Logik zum Verarbeiten von system- und benutzergenerierten Ereignissen zu implementieren.

Nächste Schritte

Erkunden Sie Codebeispiele nach Sprache.

Probieren Sie spielbare Demos aus.