Gebeurtenis-handler configureren in de Azure Web PubSub-service

Artikel
09/19/2024

De gebeurtenis-handler verwerkt de binnenkomende client gebeurtenissen. Gebeurtenis-handlers worden geregistreerd en geconfigureerd in de service via Azure Portal of Azure CLI. Wanneer een clientgebeurtenis wordt geactiveerd, kan de service de gebeurtenis verzenden naar de juiste gebeurtenis-handler. De Web PubSub-service ondersteunt nu de gebeurtenis-handler als de serverzijde, waarmee het openbaar toegankelijke eindpunt voor de service kan worden aangeroepen wanneer de gebeurtenis wordt geactiveerd. Met andere woorden, het fungeert als een webhook.

De Web PubSub-service levert clientgebeurtenissen aan de geconfigureerde upstream-webhook met behulp van het HTTP-protocol van CloudEvents, met de CloudEvents-extensie voor azure Web PubSub-gebeurtenishandler.

Schermopname van de gebeurtenistrigger Web PubSub-service.

Instellingen voor gebeurtenis-handler

Een client maakt altijd verbinding met een hub en u kunt meerdere instellingen voor de gebeurtenis-handler configureren voor de hub. De volgorde van de instellingen van de gebeurtenis-handler is van belang en de vorige heeft de hogere prioriteit. Wanneer een client verbinding maakt en een gebeurtenis wordt geactiveerd, doorloopt Web PubSub de geconfigureerde gebeurtenis-handlers in de prioriteitsvolgorde en de eerste overeenkomende gebeurtenis wint. Stel de volgende eigenschappen in wanneer u de gebeurtenis-handler configureert:

Eigenschapsnaam	Beschrijving
URL-sjabloon	Hiermee definieert u de sjabloon die Web PubSub gebruikt om uw upstream webhook-URL te evalueren.
Gebruikersevenementen	Hiermee definieert u de gebruikers gebeurtenissen waar de huidige gebeurtenis-handler-instelling om geeft.
Systeemevenementen	Hiermee definieert u de systeem gebeurtenissen waar de huidige gebeurtenis-handler-instelling om geeft.
Verificatie	Hiermee definieert u de verificatiemethode tussen de Web PubSub-service en uw upstream-server.

gebeurtenis

De gebeurtenissen omvatten gebruikers- en systeemevenementen. Systeemgebeurtenissen zijn vooraf gedefinieerde gebeurtenissen die worden geactiveerd tijdens de levensduur van een client. Gebruikersgebeurtenissen worden geactiveerd wanneer de client gegevens verzendt, de naam van de gebruikersgebeurtenis kan worden aangepast met behulp van clientprotocollen. Hier vindt u de gedetailleerde uitleg.

Gebeurtenistype	Ondersteunde waarden
Systeemevenementen	`connect`, `connected` en `disconnected`
Gebruikersevenementen	`message`of aangepaste gebeurtenisnaam volgens clientprotocollen

URL-sjabloon

URL-sjabloon ondersteunt verschillende parameters die tijdens runtime kunnen worden geëvalueerd. Met deze functie kunt u eenvoudig verschillende hubs of gebeurtenissen routeren naar verschillende upstream-servers met één instelling. KeyVault-referentiesyntaxis wordt ook ondersteund, zodat gegevens veilig kunnen worden opgeslagen in Azure Key Vault.

Opmerking: de domeinnaam van de URL mag geen parametersyntaxis bevatten, http://{hub}.com bijvoorbeeld geen geldige URL-sjabloon.

Ondersteunde parameters	Syntaxis	Beschrijving	Voorbeelden
Hubparameter	`{hub}`	De waarde is de hub waarmee de client verbinding maakt.	Wanneer een client verbinding maakt `client/hubs/chat`, wordt een URL-sjabloon `http://host.com/api/{hub}` geëvalueerd `http://host.com/api/chat` omdat voor deze client de hub is `chat`.
Gebeurtenisparameter	`{event}`	De waarde van de geactiveerde gebeurtenis. `event`hier worden de waarden vermeld. De gebeurteniswaarde voor misbruikbeveiligingsaanvragen wordt `validate` hier uitgelegd.	Als er een URL-sjabloon `http://host.com/api/{hub}/{event}` is geconfigureerd voor een gebeurtenis `connect`, start Web PubSub een `client/hubs/chat`POST-aanvraag naar de geëvalueerde URL `http://host.com/api/chat/connect` wanneer de client verbinding maakt, omdat voor deze clientgebeurtenis de hub is `chat` en de gebeurtenis die deze gebeurtenis-handlerinstelling `connect`activeert.
KeyVault-referentieparameter	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	De SecretUri moet de volledige gegevensvlak-URI van een geheim in de kluis zijn, eventueel inclusief een versie, bijvoorbeeld `https://myvault.vault.azure.net/secrets/mysecret/` of `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`. Wanneer u keyVault-naslaginformatie gebruikt, moet u ook de verificatie tussen uw Web PubSub-service en uw KeyVault-service configureren. Kijk hier voor gedetailleerde stappen.	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)`

Verificatie tussen service en webhook

U kunt een van deze methoden gebruiken om te verifiëren tussen de service en de webhook.

Anonieme modus
Eenvoudige verificatie met ?code=<code> wordt geleverd via de geconfigureerde Webhook-URL als queryparameter.
Microsoft Entra-autorisatie. Zie Een beheerde identiteit gebruiken in clientevenementen voor meer informatie.

Upstream en validatie

Bij het instellen van de gebeurtenishandlerwebhook via Azure Portal of CLI volgt de service CloudEvents Abuse Protection om de upstream-webhook te valideren. Met dit mechanisme wordt elke geregistreerde upstream webhook-URL gevalideerd. De WebHook-Request-Origin aanvraagheader is ingesteld op de naam van het servicedomein xxx.webpubsub.azure.comen verwacht dat het antwoord een header WebHook-Allowed-Origin bevat die deze domeinnaam of *.

Bij het uitvoeren van de validatie wordt de {event} parameter omgezet in validate. Wanneer u bijvoorbeeld de URL http://host.com/api/{event}probeert in te stellen, probeert de service opties een aanvraag naar http://host.com/api/validate. En alleen wanneer het antwoord geldig is, kan de configuratie worden ingesteld.

Op dit moment bieden we geen ondersteuning voor WebHook-Request-Rate en WebHook-Request-Callback.

Gebeurtenis-handler configureren

Configureren via Azure Portal

U kunt een gebeurtenis-handler toevoegen aan een nieuwe hub of een bestaande hub bewerken.

Een gebeurtenis-handler configureren in een nieuwe hub:

Ga naar uw Azure Web PubSub-servicepagina in Azure Portal.
Selecteer Instellingen in het menu.
Selecteer Toevoegen om een hub te maken en de WEBhook-URL aan de serverzijde te configureren. Opmerking: Als u een gebeurtenis-handler wilt toevoegen aan een bestaande hub, selecteert u de hub en selecteert u Bewerken.
Voer de naam van uw hub in.
Selecteer Toevoegen onder Even handlers configureren.
Configureer op de pagina gebeurtenis-handler de volgende velden: 1. Voer de URL van de serverwebhook in het veld URL-sjabloon in. 1. Selecteer de systeemevenementen waarop u zich wilt abonneren. 1. Selecteer de gebruikersevenementen waarop u zich wilt abonneren. 1. Selecteer de verificatiemethode om upstream-aanvragen te verifiëren. 1. Selecteer Bevestigen.
Selecteer Opslaan boven aan de pagina Hub-instellingen configureren.

Configureren via Azure CLI

Gebruik de azure CLI az webpubsub hub group commands om de instellingen voor de gebeurtenis-handler te configureren.

Opdracht	Beschrijving
`create`	Hubinstellingen maken voor WebPubSub Service.
`delete`	Hubinstellingen voor WebPubSub Service verwijderen.
`list`	Geef alle hubinstellingen voor WebPubSub Service weer.
`show`	Hubinstellingen weergeven voor WebPubSub Service.
`update`	Hubinstellingen voor WebPubSub Service bijwerken.

Hier volgt een voorbeeld van het maken van twee webhook-URL's voor de hub MyHub van MyWebPubSub de resource:

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"