Konfigurieren des Ereignishandlers im Azure Web PubSub-Dienst

Artikel
09/19/2024

Der Ereignishandler verarbeitet die eingehenden Clientereignisse. Der Ereignishandler werden im Dienst über das Azure-Portal oder die Azure CLI 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 serverseitig, der einen öffentlichen zugänglichen Endpunkt für den Dienst verfügbar macht, der aufgerufen werden soll, wenn das Ereignis ausgelöst wird. Mit anderen Worten: Er fungiert als Webhook.

Der Web PubSub-Dienst liefert Client-Ereignisse an den konfigurierten Upstreamwebhook unter Verwendung des CloudEvents-HTTP-Protokolls, mit CloudEvents-Erweiterung für Azure Web PubSub Ereignishandler.

Screenshot des Web PubSub-Dienstereignistriggers

Ereignishandlereinstellungen

Ein Client stellt immer eine Verbindung mit einem Hub bereit, und Sie können mehrere Ereignishandlereinstellungen für den Hub konfigurieren. Die Reihenfolge der Ereignishandlereinstellungen ist wichtig, und die erste hat die höhere Priorität. Wenn ein Client eine Verbindung herstellt und ein Ereignis ausgelöst wird, durchläuft Web PubSub die konfigurierten Ereignishandler in der Prioritätsreihenfolge, und der erste übereinstimmende gewinnt. Legen Sie beim Konfigurieren des Ereignishandlers die folgenden Eigenschaften fest:

Eigenschaftenname	Beschreibung
URL-Vorlage	Definiert die Vorlage, die Web PubSub verwendet, um Ihre Upstreamwebhook-URL auszuwerten.
Benutzerereignisse	Definiert die Benutzerereignisse, für die sich die aktuelle Ereignisbehandlungseinstellung interessiert.
Systemereignisse	Definiert die Systemereignisse, für die sich die aktuelle Ereignisbehandlungseinstellung interessiert.
Authentifizierung	Definiert die Authentifizierungsmethode zwischen dem Web PubSub-Dienst und dem Upstreamserver.

Ereignisse

Zu den Ereignissen gehören Benutzerereignisse und Systemereignisse. Systemereignisse sind vordefinierte Ereignisse, die während der Lebensdauer eines Clients ausgelöst werden. Benutzerereignisse werden ausgelöst, wenn der Client Daten sendet. Der Benutzername kann mithilfe von Clientprotokollen angepasst werden, hier finden Sie die ausführliche Erläuterung.

Ereignistyp	Unterstützte Werte
Systemereignisse	`connect`, `connected` und `disconnected`
Benutzerereignisse	`message`, oder benutzerdefinierter Ereignisname nach Clientprotokollen

URL-Vorlage

Die URL-Vorlage unterstützt mehrere Parameter, die während der Laufzeit ausgewertet werden können. Mit diesem Feature ist es einfach, verschiedene Hubs oder Ereignisse mit einer einzigen Einstellung an verschiedene Upstreamserver weiterzuleiten. Die KeyVault-Referenzsyntax wird ebenfalls unterstützt, so dass die Daten sicher in Azure Key Vault gespeichert werden können.

Beachten Sie, dass der Domänenname der URL keine Parametersyntax enthalten sollte, http://{hub}.com ist beispielsweise keine gültige URL-Vorlage.

Unterstützte Parameter	Syntax	Beschreibung	Beispiele
Hubparameter	`{hub}`	Der Wert ist der Hub, mit dem der Client eine Verbindung herstellt.	Wenn ein Client eine Verbindung zu `client/hubs/chat` herstellt, wird eine URL-Vorlage `http://host.com/api/{hub}` zu `http://host.com/api/chat` ausgewertet, da der Hub für diesen Client `chat` ist.
Ereignisparameter	`{event}`	Der Wert des ausgelösten Ereignisses. `event`-Werte finden Sie hier. Der Ereigniswert für Missbrauchsschutzanforderungen ist `validate`, wie hier erläutert.	Wenn für das Ereignis `connect` eine URL-Vorlage `http://host.com/api/{hub}/{event}` konfiguriert ist, initiiert Web PubSub bei der Verbindung eines Clients mit `client/hubs/chat` eine POST-Anforderung an die bewertete URL `http://host.com/api/chat/connect`, da für dieses Client-Ereignis Hub `chat` und das Ereignis, das diese Event-Handler-Einstellung auslöst, `connect` ist.
KeyVault-Referenzparameter	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	Der SecretUri sollte der vollständige URI der Datenebene eines Geheimnisses im Tresor sein und optional eine Version enthalten, z. B. `https://myvault.vault.azure.net/secrets/mysecret/` oder `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`. Wenn Sie die KeyVault-Referenz verwenden, müssen Sie auch die Authentifizierung zwischen Ihrem Web PubSub-Dienst und Ihrem KeyVault-Dienst konfigurieren. Hier finden Sie detaillierte Schritte.	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)`

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 mit ?code=<code> wird über die konfigurierte Webhook-URL als Abfrageparameter bereitgestellt.
Microsoft Entra ID-Autorisierung. Weitere Informationen finden Sie unter Verwenden einer verwalteten Identität in Clientereignissen.

Upstream und Überprüfung

Beim Einrichten des Ereignishandlerwebhooks über das Azure-Portal oder die Azure CLI überprüft der Dienst den Upstreamwebhook mithilfe des CloudEvents-Schutzes gegen Missbrauch. Dieser Mechanismus überprüft jede registrierte Upstream-Webhook-URL. 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.

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 Ereignishändler 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. Klicken Sie auf Bestätigen.
Wählen Sie oben auf der Seite Hubeinstellungen 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.

Im Folgenden finden Sie 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"