Ereignishandler im Azure Web PubSub-Dienst

Artikel
10/26/2023

Der Ereignishandler verarbeitet die eingehenden Clientereignisse. Ereignishandler werden über die Azure-Portal oder Azure CLI im Dienst registriert und konfiguriert. Wenn ein Clientereignis ausgelöst wird, kann der Dienst das Ereignis an den entsprechenden Ereignishandler senden. Der Web PubSub-Dienst unterstützt jetzt den Ereignishandler als serverseitiger Handler, der den öffentlich zugänglichen Endpunkt für den Dienst verfügbar macht, der beim Auslösen des Ereignisses aufgerufen wird. Mit anderen Worten: Er fungiert als Webhook.

Der Web PubSub-Dienst liefert Clientereignisse mithilfe des CloudEvents-HTTP-Protokolls an den upstream-Webhook.

Für jedes Ereignis formuliert der Dienst eine HTTP POST-Anforderung an den registrierten Upstream-Endpunkt und erwartet eine HTTP-Antwort.

Die Daten, die vom Dienst an den Server gesendet werden, weisen immer das CloudEvents-Format binary auf.

Screenshot of Web PubSub service event trigger.

Upstream und Überprüfung

Wenn Sie den Webhook-Endpunkt konfigurieren, kann die URL den {event} Parameter enthalten, um eine URL-Vorlage zu definieren. Der Dienst berechnet den Wert der Webhook-URL dynamisch, sobald er die Clientanforderung empfängt. Beispiel: Wenn die Anforderung /client/hubs/chat mit dem konfigurierten Ereignishandler-URL-Muster http://host.com/api/{event} für den Hub chat empfangen wird, wird beim Herstellen der Clientverbindung zunächst eine Nachricht für diese URL veröffentlicht: http://host.com/api/connect. Der {event} Parameter kann nützlich sein, wenn ein PubSub WebSocket-Client benutzerdefinierte Ereignisse sendet, die der Ereignishandler hilft, verschiedene Ereignisse an verschiedene upstream-Endpunkte zu verteilen. Der {event}-Parameter ist im URL-Domänennamen unzulässig.

Beim Einrichten des Ereignishandler-Webhooks über Azure-Portal oder CLI folgt der Dienst dem CloudEvents-Missbrauchsschutz, um den upstream-Webhook zu überprüfen. Jede registrierte Upstream-Webhook-URL wird mit diesem Mechanismus überprüft. Der Anforderungsheader WebHook-Request-Origin ist auf den Dienstdomänennamen xxx.webpubsub.azure.com festgelegt, und es wird erwartet, dass die Antwort einen Header vom Typ WebHook-Allowed-Origin besitzt, der diesen Domänennamen oder * enthält.

Bei der Überprüfung wird der Parameter {event} in validate aufgelöst. Beim Versuch, die URL auf http://host.com/api/{event} festzulegen, wird vom Dienst beispielsweise versucht, einen OPTIONS-Vorgang für eine Anforderung an http://host.com/api/validate auszuführen. Die Konfiguration kann nur erfolgreich festgelegt werden, wenn die Antwort gültig ist.

Aktuell werden WebHook-Request-Rate und WebHook-Request-Callback nicht unterstützt.

Authentifizierung zwischen Dienst und Webhook

Sie können eine dieser Methoden verwenden, um sich zwischen dem Dienst und dem Webhook zu authentifizieren.

Anonymer Modus
Die einfache Authentifizierung erfolgt ?code=<code> über die konfigurierte Webhook-URL als Abfrageparameter.
Microsoft Entra-Autorisierung. Weitere Informationen finden Sie unter Verwenden einer verwalteten Identität in Clientereignissen.

Konfigurieren eines Ereignishandlers

Konfigurieren über Azure-Portal

Sie können einem neuen Hub einen Ereignishandler hinzufügen oder einen vorhandenen Hub bearbeiten.

So konfigurieren Sie einen Ereignishandler in einem neuen Hub:

Wechseln Sie zur Azure Web PubSub-Dienstseite im Azure-Portal.
Klicken Sie im Menü auf Einstellungen.
Wählen Sie "Hinzufügen" aus, um einen Hub zu erstellen und ihre serverseitige Webhook-URL zu konfigurieren. Hinweis: Wenn Sie einem vorhandenen Hub einen Ereignishandler hinzufügen möchten, wählen Sie den Hub aus, und wählen Sie "Bearbeiten" aus.
Geben Sie Ihren Hubnamen ein.
Wählen Sie "Hinzufügen " unter "Gerade Handler konfigurieren" aus.
Konfigurieren Sie auf der Ereignishandlerseite die folgenden Felder: 1. Geben Sie die Serverwebhook-URL in das Feld "URL-Vorlage " ein. 1. Wählen Sie die Systemereignisse aus, die Sie abonnieren möchten. 1. Wählen Sie die Benutzerereignisse aus, die Sie abonnieren möchten. 1. Wählen Sie die Authentifizierungsmethode aus, um Upstreamanforderungen zu authentifizieren. 1. Wählen Sie Bestätigen aus.
Wählen Sie oben auf der Seite "Hub Einstellungen konfigurieren" die Option "Speichern" aus.

Konfigurieren über Azure CLI

Verwenden Sie die Befehle der Azure CLI-Gruppe az webpubsub hub, um die Ereignishandlereinstellungen zu aktualisieren.

Befehle	Beschreibung
`create`	Erstellen Sie Hubeinstellungen für den WebPubSub-Dienst.
`delete`	Löschen Sie Hubeinstellungen für den WebPubSub-Dienst.
`list`	Listen Sie Hubeinstellungen für den WebPubSub-Dienst auf.
`show`	Zeigen Sie Hubeinstellungen für den WebPubSub-Dienst an.
`update`	Aktualisieren Sie Hubeinstellungen für den WebPubSub-Dienst.

Hier ist ein Beispiel für das Erstellen von zwei Webhook-URLs für den Hub MyHub der MyWebPubSub Ressource:

az webpubsub hub create -n "MyWebPubSub" -g "MyResourceGroup" --hub-name "MyHub" --event-handler url-template="http://host.com" user-event-pattern="*" --event-handler url-template="http://host2.com" system-event="connected" system-event="disconnected" auth-type="ManagedIdentity" auth-resource="uri://myUri"