Configurar manipulador de eventos no serviço Azure Web PubSub

Artigo
09/19/2024

O manipulador de eventos manipula os eventos de cliente de entrada. Os manipuladores de eventos são registrados e configurados no serviço por meio do portal do Azure ou da CLI do Azure. Quando um evento de cliente é acionado, o serviço pode enviar o evento para o manipulador de eventos apropriado. O serviço Web PubSub agora oferece suporte ao manipulador de eventos como o lado do servidor, que expõe o ponto de extremidade acessível publicamente para o serviço invocar quando o evento é acionado. Por outras palavras, funciona como um webhook.

O serviço Web PubSub fornece eventos de cliente para o webhook upstream configurado usando o protocolo HTTP CloudEvents, com extensão CloudEvents para manipulador de eventos Web PubSub do Azure.

Captura de tela do gatilho de evento do serviço Web PubSub.

Configurações do manipulador de eventos

Um cliente sempre se conecta a um hub, e você pode definir várias configurações de manipulador de eventos para o hub. A ordem das configurações do manipulador de eventos é importante e a primeira tem a prioridade mais alta. Quando um cliente se conecta e um evento é acionado, o Web PubSub passa pelos manipuladores de eventos configurados na ordem de prioridade e o primeiro correspondente vence. Defina as seguintes propriedades ao configurar o manipulador de eventos:

Property name	Description
Modelo de url	Define o modelo que o Web PubSub usa para avaliar sua URL de webhook upstream.
Eventos do utilizador	Define os eventos de usuário com os quais a configuração atual do manipulador de eventos se preocupa.
Eventos do sistema	Define os eventos do sistema com os quais a configuração atual do manipulador de eventos se preocupa.
Autenticação	Define o método de autenticação entre o serviço Web PubSub e o servidor upstream.

evento

Os eventos incluem eventos de usuário e eventos do sistema. Os eventos do sistema são eventos predefinidos que são acionados durante o tempo de vida de um cliente. Os eventos do usuário são acionados quando o cliente envia dados, o nome do evento do usuário pode ser personalizado usando protocolos do cliente, aqui contém a explicação detalhada.

Tipo de evento	Valores suportados
Eventos do sistema	`connect`, `connected`, e `disconnected`
Eventos do utilizador	`message`ou nome de evento personalizado seguindo protocolos de cliente

Modelo de URL

O modelo de URL suporta vários parâmetros que podem ser avaliados durante o tempo de execução. Com esse recurso, é fácil rotear diferentes hubs ou eventos em diferentes servidores upstream com uma única configuração. A sintaxe de referência do KeyVault também é suportada para que os dados possam ser armazenados no Cofre de Chaves do Azure de forma segura.

Observação O nome de domínio de URL não deve conter sintaxe de parâmetro, por exemplo, http://{hub}.com não é um modelo de URL válido.

Parâmetros suportados	Sintaxe	Description	Exemplos
Parâmetro Hub	`{hub}`	O valor é o hub ao qual o cliente se conecta.	Quando um cliente se conecta ao `client/hubs/chat`, um modelo `http://host.com/api/{hub}` de URL é avaliado porque `http://host.com/api/chat` , para esse cliente, hub é `chat`.
Parâmetro do evento	`{event}`	O valor do evento acionado. `event` Os valores estão listados aqui. O valor do evento para solicitações de proteção contra abuso é `validate` conforme explicado aqui.	Se houver um modelo `http://host.com/api/{hub}/{event}` de URL configurado para o evento `connect`, Quando um cliente se conecta ao `client/hubs/chat`, o Web PubSub inicia uma solicitação POST para a URL `http://host.com/api/chat/connect` avaliada quando o cliente está se conectando, já que para esse evento do cliente, hub é `chat` e o evento que aciona essa configuração do manipulador de eventos é `connect`.
Parâmetro de referência KeyVault	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	O SecretUri deve ser o URI de plano de dados completo de um segredo no cofre, opcionalmente incluindo uma versão, por exemplo, `https://myvault.vault.azure.net/secrets/mysecret/` ou `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`. Ao usar a referência do KeyVault, você também precisa configurar a autenticação entre o serviço Web PubSub e o serviço KeyVault, verifique aqui as etapas detalhadas.	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)`

Autenticação entre serviço e webhook

Você pode usar qualquer um desses métodos para autenticar entre o serviço e o webhook.

Modo anónimo
A autenticação simples com ?code=<code> é fornecida através da URL Webhook configurada como parâmetro de consulta.
Autorização do Microsoft Entra. Para obter mais informações, consulte Usar uma identidade gerenciada em eventos de cliente.

Upstream e Validação

Ao configurar o webhook do manipulador de eventos por meio do portal do Azure ou da CLI, o serviço segue a Proteção contra Abuso do CloudEvents para validar o webhook upstream. Esse mecanismo valida cada URL de webhook upstream registrada. O WebHook-Request-Origin cabeçalho da solicitação é definido como o nome xxx.webpubsub.azure.comde domínio do serviço e espera que a resposta tenha um cabeçalho WebHook-Allowed-Origin que contenha esse nome de domínio ou *.

Ao fazer a validação, o {event} parâmetro é resolvido para validate. Por exemplo, ao tentar definir a URL como http://host.com/api/{event}, o serviço tenta OPTIONS uma solicitação para http://host.com/api/validate. E somente quando a resposta é válida, a configuração pode ser definida com êxito.

Por enquanto, não suportamos WebHook-Request-Rate e WebHook-Request-Callback.

Configurar manipulador de eventos

Configurar através do portal do Azure

Você pode adicionar um manipulador de eventos a um novo hub ou editar um hub existente.

Para configurar um manipulador de eventos em um novo hub:

Vá para a página do serviço Azure Web PubSub no portal do Azure.
Selecione Settings (Definições) no menu.
Selecione Adicionar para criar um hub e configurar a URL do webhook do lado do servidor. Nota: Para adicionar um manipulador de eventos a um hub existente, selecione o hub e selecione Editar.
Insira o nome do hub.
Selecione Adicionar em Configurar manipuladores pares.
Na página do manipulador de eventos, configure os seguintes campos: 1. Insira a URL do webhook do servidor no campo Modelo de URL. 1. Selecione os eventos do sistema que você deseja assinar. 1. Selecione os eventos de usuário que você deseja assinar. 1. Selecione Método de autenticação para autenticar solicitações upstream. 1. Selecione Confirmar.
Selecione Salvar na parte superior da página Configurar configurações do Hub.

Configurar através da CLI do Azure

Use os comandos do grupo de hub do Azure CLI az webpubsub para definir as configurações do manipulador de eventos.

Comandos	Description
`create`	Crie configurações de hub para o Serviço WebPubSub.
`delete`	Exclua as configurações de hub para o Serviço WebPubSub.
`list`	Liste todas as configurações de hub para o Serviço WebPubSub.
`show`	Mostrar configurações de hub para o Serviço WebPubSub.
`update`	Atualize as configurações do hub para o Serviço WebPubSub.

Aqui está um exemplo de criação de duas URLs de webhook para hub MyHub de MyWebPubSub recurso:

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"