Konfigurera händelsehanterare i Azure Web PubSub-tjänsten

Artikel
10/17/2024

Händelsehanteraren hanterar inkommande klienthändelser. Händelsehanterare registreras och konfigureras i tjänsten via Azure Portal eller Azure CLI. När en klienthändelse utlöses kan tjänsten skicka händelsen till lämplig händelsehanterare. Tjänsten Web PubSub har nu stöd för händelsehanteraren som serversidan, vilket gör den offentligt tillgängliga slutpunkten tillgänglig för tjänsten att anropa när händelsen utlöses. Med andra ord fungerar den som en webhook.

Tjänsten Web PubSub levererar klienthändelser till den konfigurerade överordnade webhooken med hjälp av HTTP-protokollet CloudEvents med CloudEvents-tillägget för Azure Web PubSub-händelsehanteraren.

Skärmbild av händelseutlösaren för Web PubSub-tjänsten.

Inställningar för händelsehanterare

En klient ansluter alltid till en hubb och du kan konfigurera flera händelsehanterarinställningar för hubben. Ordningen på händelsehanterarinställningarna är viktiga och den tidigare har högre prioritet. När en klient ansluter och en händelse utlöses går Web PubSub igenom de konfigurerade händelsehantrarna i prioritetsordningen och den första matchande vinner. Ange följande egenskaper när du konfigurerar händelsehanteraren:

Egenskapsnamn	beskrivning
Url-mall	Definierar mallen Web PubSub använder för att utvärdera din överordnade webhook-URL.
Användarhändelser	Definierar de användarhändelser som den aktuella händelsehanterarinställningen bryr sig om.
Systemhändelser	Definierar de systemhändelser som den aktuella händelsehanterarinställningen bryr sig om.
Autentisering	Definierar autentiseringsmetoden mellan Web PubSub-tjänsten och den överordnade servern.

Händelser

Händelserna omfattar användarhändelser och systemhändelser. Systemhändelser är fördefinierade händelser som utlöses under en klients livslängd. Användarhändelser utlöses när klienten skickar data, användarnamnet kan anpassas med hjälp av klientprotokoll, här innehåller den detaljerade förklaringen.

Händelsetyp	Värden som stöds
Systemhändelser	`connect`, `connected` och `disconnected`
Användarhändelser	`message`, eller anpassat händelsenamn efter klientprotokoll

URL-mall

URL-mallen stöder flera parametrar som kan utvärderas under körningen. Med den här funktionen är det enkelt att dirigera olika hubbar eller händelser till olika överordnade servrar med en enda inställning. KeyVault-referenssyntaxen har också stöd för att data ska kunna lagras i Azure Key Vault på ett säkert sätt.

Observera att URL-domännamnet inte får innehålla parametersyntax, till exempel http://{hub}.com inte är en giltig URL-mall.

Parametrar som stöds	Syntax	beskrivning	Exempel
Hubbparameter	`{hub}`	Värdet är den hubb som klienten ansluter till.	När en klient ansluter till `client/hubs/chat`utvärderas en URL-mall `http://host.com/api/{hub}` till `http://host.com/api/chat` eftersom hubben för den här klienten är `chat`.
Händelseparameter	`{event}`	Värdet för den utlösta händelsen. `event` värden visas här. Händelsevärdet för begäranden om missbruksskydd beskrivs `validate` här.	Om det finns en URL-mall `http://host.com/api/{hub}/{event}` som konfigurerats för händelsen `connect`initierar `client/hubs/chat`Web PubSub en POST-begäran till den utvärderade URL: `http://host.com/api/chat/connect` en när klienten ansluter, eftersom hubben och `chat` händelsen som utlöser den här händelsehanterarinställningen är `connect`för den här klienthändelsen .
KeyVault-referensparameter	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	SecretUri ska vara den fullständiga dataplans-URI:n för en hemlighet i valvet, eventuellt inklusive en version, `https://myvault.vault.azure.net/secrets/mysecret/` till exempel eller `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`. När du använder KeyVault-referensen måste du också konfigurera autentiseringen mellan din Web PubSub-tjänst och Din KeyVault-tjänst. Mer information finns här .	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)`

Autentisering mellan tjänst och webhook

Du kan använda någon av dessa metoder för att autentisera mellan tjänsten och webhooken.

Anonymt läge
Enkel autentisering med ?code=<code> tillhandahålls via den konfigurerade Webhook-URL:en som frågeparameter.
Microsoft Entra-auktorisering. Mer information finns i Använda en hanterad identitet i klienthändelser.

Uppströms och validering

När du konfigurerar händelsehanterarens webhook via Azure Portal eller CLI följer tjänsten CloudEvents Abuse Protection för att verifiera den överordnade webhooken. Den här mekanismen validerar varje registrerad överordnad webhook-URL. Begärandehuvudet WebHook-Request-Origin är inställt på tjänstdomännamnet xxx.webpubsub.azure.comoch förväntar sig att svaret har ett huvud WebHook-Allowed-Origin som ska innehålla det här domännamnet eller *.

När du utför verifieringen matchas parametern {event} till validate. När du till exempel försöker ange URL:en till http://host.com/api/{event}försöker tjänsten ange ALTERNATIV för en begäran till http://host.com/api/validate. Och bara när svaret är giltigt kan konfigurationen ställas in.

För tillfället stöder vi inte WebHook-Request-Rate och WebHook-Request-Callback.

Konfigurera händelsehanterare

Konfigurera via Azure Portal

Du kan lägga till en händelsehanterare i en ny hubb eller redigera en befintlig hubb.

Så här konfigurerar du en händelsehanterare i en ny hubb:

Gå till tjänstsidan för Azure Web PubSub i Azure Portal.
Välj Inställningar på menyn.
Välj Lägg till för att skapa en hubb och konfigurera webhookens URL på serversidan. Obs! Om du vill lägga till en händelsehanterare i en befintlig hubb väljer du hubben och väljer Redigera.
Ange hubbens namn.
Välj Lägg till under Konfigurera jämna hanterare.
På händelsehanterarsidan konfigurerar du följande fält: 1. Ange serverns webhook-URL i fältet URL-mall . 1. Välj de systemhändelser som du vill prenumerera på. 1. Välj de användarhändelser som du vill prenumerera på. 1. Välj Autentiseringsmetod för att autentisera överordnade begäranden. 1. Välj Bekräfta.
Välj Spara överst på sidan Konfigurera hubbinställningar .

Konfigurera via Azure CLI

Använd azure CLI az webpubsub hub group-kommandon för att konfigurera inställningarna för händelsehanteraren.

Kommandon	beskrivning
`create`	Skapa hubbinställningar för WebPubSub Service.
`delete`	Ta bort hubbinställningar för WebPubSub Service.
`list`	Visa en lista över alla hubbinställningar för WebPubSub Service.
`show`	Visa hubbinställningar för WebPubSub Service.
`update`	Uppdatera hubbinställningarna för WebPubSub Service.

Här är ett exempel på hur du skapar två webhook-URL:er för resurshubben MyHub MyWebPubSub :

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"