Konfigurace obslužné rutiny událostí ve službě Azure Web PubSub

Článek
09/19/2024

Obslužná rutina události zpracovává příchozí události klienta. Obslužné rutiny událostí se ve službě registrují a konfigurují prostřednictvím webu Azure Portal nebo Azure CLI. Při aktivaci události klienta může služba odeslat událost příslušné obslužné rutině události. Služba Web PubSub teď podporuje obslužnou rutinu události jako serverovou stranu, která zveřejňuje veřejně přístupný koncový bod pro službu, která se má vyvolat při aktivaci události. Jinými slovy, funguje jako webhook.

Služba Web PubSub doručuje události klienta do nakonfigurovaného upstreamového webhooku pomocí protokolu HTTP CloudEvents s rozšířením CloudEvents pro obslužnou rutinu události Azure Web PubSub.

Snímek obrazovky s triggerem události služby Web PubSub

Nastavení obslužné rutiny události

Klient se vždy připojuje k centru a pro centrum můžete nakonfigurovat několik nastavení obslužné rutiny událostí. Pořadí nastavení obslužné rutiny události záleží a první nastavení má vyšší prioritu. Když se klient připojí a aktivuje se událost, web pubSub projde nakonfigurovanými obslužnými rutinami událostí v pořadí priority a první odpovídající událost vyhrává. Při konfiguraci obslužné rutiny události nastavte následující vlastnosti:

Název vlastnosti	Popis
Šablona adresy URL	Definuje šablonu Web PubSub, která používá k vyhodnocení adresy URL upstreamového webhooku.
Události uživatelů	Definuje události uživatele, o které se aktuální nastavení obslužné rutiny události stará.
Systémové události	Definuje systémové události, o které se aktuální nastavení obslužné rutiny události stará.
Ověřování	Definuje metodu ověřování mezi službou Web PubSub a vaším upstream serverem.

Události

Události zahrnují události uživatelů a systémové události. Systémové události jsou předdefinované události, které se aktivují během životnosti klienta. Uživatelské události se aktivují, když klient odesílá data, uživatelské jméno události lze přizpůsobit pomocí klientských protokolů, zde obsahuje podrobné vysvětlení.

Typ události	Podporované hodnoty
Systémové události	`connect`, `connected`a `disconnected`
Události uživatelů	`message`nebo vlastní název události následující po klientských protokolech

Šablona adresy URL

Šablona adresy URL podporuje několik parametrů, které je možné vyhodnotit během běhu. Díky této funkci je snadné směrovat různá centra nebo události do různých nadřazených serverů pomocí jediného nastavení. Referenční syntaxe služby KeyVault je také podporována, aby se data mohla bezpečně ukládat ve službě Azure Key Vault.

Poznámka: Název domény ADRESY URL by neměl obsahovat syntaxi parametrů, http://{hub}.com například není platnou šablonou adresy URL.

Podporované parametry	Syntaxe	Popis	Ukázky
Parametr centra	`{hub}`	Hodnota je centrum, ke kterému se klient připojuje.	Když se klient připojí k `client/hubs/chat`, šablona `http://host.com/api/{hub}` adresy URL se vyhodnotí `http://host.com/api/chat` proto, že pro tohoto klienta je `chat`centrum .
Parametr události	`{event}`	Hodnota aktivované události. `event`tady jsou uvedeny hodnoty. Hodnota události pro žádosti o ochranu před zneužitím je `validate` vysvětlená zde.	Pokud existuje šablona `http://host.com/api/{hub}/{event}` adresy URL nakonfigurovaná pro událost `connect`, Když se klient připojí k `client/hubs/chat`, Web PubSub zahájí požadavek POST na vyhodnocenou adresu URL `http://host.com/api/chat/connect` při připojování klienta, protože pro tuto událost klienta je `chat` centrum a událost aktivující toto nastavení obslužné rutiny události je `connect`.
Referenční parametr keyVault	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	SecretUri by měl být úplný identifikátor URI roviny dat tajného klíče v trezoru, volitelně včetně verze, `https://myvault.vault.azure.net/secrets/mysecret/` například nebo `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`. Pokud používáte referenční informace ke službě KeyVault, musíte také nakonfigurovat ověřování mezi službou Web PubSub a službou KeyVault. Tady najdete podrobné pokyny.	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)`

Ověřování mezi službou a webhookem

K ověření mezi službou a webhookem můžete použít některou z těchto metod.

Anonymní režim
Jednoduché ověřování se ?code=<code> poskytuje prostřednictvím nakonfigurované adresy URL webhooku jako parametru dotazu.
Autorizace Microsoft Entra. Další informace najdete v tématu Použití spravované identity v událostech klienta.

Upstream a validation

Při nastavování webhooku obslužné rutiny událostí prostřednictvím webu Azure Portal nebo rozhraní příkazového řádku se služba řídí ochranou před zneužitím CloudEvents a ověří upstreamový webhook. Tento mechanismus ověří každou zaregistrovanou adresu URL webhooku. Hlavička WebHook-Request-Origin požadavku je nastavená na název xxx.webpubsub.azure.comdomény služby a očekává, že odpověď bude obsahovat tento WebHook-Allowed-Origin název domény nebo *.

Při ověřování {event} se parametr přeloží na validate. Například při pokusu o nastavení adresy URL http://host.com/api/{event}na , služba se pokusí MOŽNOSTI požadavku na http://host.com/api/validate. A pouze v případě, že je odpověď platná, je možné úspěšně nastavit konfiguraci.

Prozatím nepodporujeme funkci WebHook-Request-Rate a WebHook-Request-Callback.

Konfigurace obslužné rutiny události

Konfigurace prostřednictvím webu Azure Portal

Obslužnou rutinu události můžete přidat do nového centra nebo upravit existující centrum.

Konfigurace obslužné rutiny události v novém centru:

Na webu Azure Portal přejděte na stránku služby Azure Web PubSub.
Z nabídky vyberte Nastavení.
Výběrem možnosti Přidat vytvořte centrum a nakonfigurujte adresu URL webhooku na straně serveru. Poznámka: Pokud chcete přidat obslužnou rutinu události do existujícího centra, vyberte centrum a vyberte Upravit.
Zadejte název centra.
Vyberte Přidat v části Konfigurovat sudé obslužné rutiny.
Na stránce obslužné rutiny události nakonfigurujte následující pole: 1. Do pole Šablona adresy URL zadejte adresu URL webhooku serveru. 1. Vyberte systémové události, ke kterým se chcete přihlásit. 1. Vyberte události uživatele, které chcete přihlásit k odběru. 1. Vyberte metodu ověřování pro ověřování upstreamových požadavků. 1. Vyberte Potvrdit.
V horní části stránky Konfigurovat nastavení centra vyberte Uložit.

Konfigurace prostřednictvím Azure CLI

Ke konfiguraci nastavení obslužné rutiny události použijte příkazy skupiny Azure CLI az webpubsub hub.

Příkazy	Popis
`create`	Vytvořte nastavení centra pro službu WebPubSub.
`delete`	Odstraňte nastavení centra pro službu WebPubSub.
`list`	Zobrazí seznam všech nastavení centra pro službu WebPubSub.
`show`	Zobrazit nastavení centra pro službu WebPubSub.
`update`	Aktualizujte nastavení centra pro službu WebPubSub.

Tady je příklad vytvoření dvou adres URL webhooku pro centrum MyHub MyWebPubSub prostředků:

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"