Configurare il gestore eventi nel servizio Web PubSub di Azure

Articolo
09/19/2024

Il gestore eventi gestisce gli eventi client in ingresso. I gestori eventi sono registrati e configurati nel servizio tramite il portale di Azure o l'interfaccia della riga di comando di Azure. Quando viene attivato un evento client, il servizio può inviare l'evento al gestore eventi appropriato. Il servizio Web PubSub supporta ora il gestore eventi come lato server, che espone l'endpoint accessibile pubblicamente per il servizio da richiamare quando viene attivato l'evento. In altre parole, funge da webhook.

Il servizio Web PubSub recapita gli eventi client al webhook upstream configurato usando il protocollo HTTP CloudEvents, con l'estensione CloudEvents per il gestore eventi Azure Web PubSub.

Screenshot del trigger di evento del servizio Web PubSub.

Impostazioni del gestore eventi

Un client si connette sempre a un hub ed è possibile configurare più impostazioni del gestore eventi per l'hub. L'ordine delle impostazioni del gestore eventi è importante e quello precedente ha la priorità più alta. Quando un client si connette e viene attivato un evento, Web PubSub passa attraverso i gestori eventi configurati nell'ordine di priorità e il primo corrispondente vince. Impostare le proprietà seguenti quando si configura il gestore eventi:

Nome proprietà	Descrizione
Modello di URL	Definisce l'uso del modello Web PubSub per valutare l'URL del webhook upstream.
Eventi degli utenti	Definisce gli eventi utente a cui interessa l'impostazione corrente del gestore eventi.
Eventi di sistema	Definisce gli eventi di sistema su cui si occupa l'impostazione corrente del gestore eventi.
Autenticazione	Definisce il metodo di autenticazione tra il servizio Web PubSub e il server upstream.

Eventi

Gli eventi includono eventi utente ed eventi di sistema. Gli eventi di sistema sono eventi predefiniti che vengono attivati durante la durata di un client. Gli eventi utente vengono attivati quando il client invia dati, il nome dell'evento utente può essere personalizzato usando i protocolli client. Di seguito è illustrata la spiegazione dettagliata.

Tipo di evento	Valori supportati
Eventi di sistema	`connect`, `connected` e `disconnected`
Eventi degli utenti	`message` o il nome dell'evento personalizzato che segue i protocolli client

Modello di URL

Il modello di URL supporta diversi parametri che possono essere valutati durante il runtime. Con questa funzionalità, è facile instradare hub o eventi differenti in server upstream diversi con una singola impostazione. La sintassi di riferimento di KeyVault è supportata anche per consentire l'archiviazione sicura dei dati in Azure Key Vault.

Nota Il nome di dominio URL non deve contenere la sintassi dei parametri, ad esempio http://{hub}.com non è un modello URL valido.

Parametri supportati	Sintassi	Descrizione	Esempi
Parametro hub	`{hub}`	Il valore è l'hub a cui si connette il client.	Quando un client si connette a `client/hubs/chat`, un modello di URL`http://host.com/api/{hub}` valuta a `http://host.com/api/chat` perché per questo client, l'hub è `chat`.
Parametro event	`{event}`	Valore dell'evento attivato. I valori `event` sono elencati qui. Il valore dell'evento per le richieste di protezione da abusi è `validate`, come illustrato qui.	Se è presente un modello di URL `http://host.com/api/{hub}/{event}` configurato per l'evento `connect`, Quando un client si connette a `client/hubs/chat`, Web PubSub avvia una richiesta POST all'URL `http://host.com/api/chat/connect` valutato quando il client si connette, poiché per questo evento client, l'hub è `chat` e l'evento che attiva questa impostazione del gestore eventi è `connect`.
Parametro di riferimento di KeyVault	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	SecretUri deve essere l'URI del piano dati completo di un segreto nell'insieme di credenziali, inclusa facoltativamente una versione, ad esempio, `https://myvault.vault.azure.net/secrets/mysecret/` o `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`. Quando si usa il riferimento a KeyVault, è anche necessario configurare l'autenticazione tra il servizio Web PubSub e il servizio KeyVault, vedere qui per i passaggi dettagliati.	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)`

Autenticazione tra il servizio e il webhook

È possibile usare uno di questi metodi per eseguire l'autenticazione tra il servizio e il webhook.

Modalità anonima
L'autenticazione semplice con ?code=<code> viene fornita tramite l'URL del webhook configurato come parametro di query.
Autorizzazione Microsoft Entra. Per altre informazioni, vedere Usare un'identità gestita negli eventi client.

Upstream e convalida

Quando si configura il webhook del gestore eventi tramite il portale o l'interfaccia della riga di comando di Azure, il servizio segue la Protezione dagli abusi di CloudEvents per convalidare il webhook upstream. Questo meccanismo convalida ogni URL di webhook upstream registrato. L'intestazione della richiesta WebHook-Request-Origin è impostata sul nome di dominio del servizio xxx.webpubsub.azure.com e prevede che la risposta abbia intestazione WebHook-Allowed-Origin per contenere questo nome di dominio o *.

Quando si esegue la convalida, il parametro {event} viene risolto in validate. Ad esempio, quando si tenta di impostare l'URL su http://host.com/api/{event}, il servizio tenta di impostare OPZIONI di una richiesta su http://host.com/api/validate. E solo quando la risposta è valida, la configurazione può essere impostata correttamente.

Per il momento WebHook-Request-Rate e WebHook-Request-Callback non sono supportati.

Configurare il gestore eventi

Configurare tramite il portale di Azure

È possibile aggiungere un gestore eventi a un nuovo hub o modificare un hub esistente.

Per configurare un gestore eventi in un nuovo hub:

Andare alla pagina del servizio Web PubSub di Azure nel portale di Azure.
Selezionare Impostazioni dal menu.
Selezionare Aggiungi per creare un hub e configurare l'URL del webhook sul lato server. Nota: per aggiungere un gestore eventi a un hub esistente, selezionare l'hub e selezionare Modifica.
Immettere il nome dell'hub.
Selezionare Aggiungi in Configura gestori pari.
Nella pagina del gestore eventi configurare i campi seguenti: 1. Immettere l'URL del webhook del server nel campo Modello URL. 1. Selezionare gli eventi di sistema a cui si desidera eseguire la sottoscrizione. 1. Selezionare gli eventi utente a cui si desidera sottoscrivere. 1. Selezionare il metodo di autenticazione per autenticare le richieste upstream. 1. Seleziona Conferma.
Selezionare Salva nella parte superiore della pagina Configura impostazioni hub.

Configurare tramite l'interfaccia della riga di comando di Azure

Usare i comandi di gruppo az webpubsub hub group dell'interfaccia della riga di comando di Azure per configurare le impostazioni del gestore eventi.

Comandi	Descrizione
`create`	Creare le impostazioni dell'hub per il servizio WebPubSub.
`delete`	Eliminare le impostazioni dell'hub per il servizio WebPubSub.
`list`	Elencare tutte le impostazioni dell'hub per il servizio WebPubSub.
`show`	Mostra le impostazioni dell'hub per il servizio WebPubSub.
`update`	Aggiornare le impostazioni dell'hub per il servizio WebPubSub.

Di seguito è riportato un esempio di creazione di due URL webhook per l'hub MyHub della risorsa 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"