Manipulador de eventos no serviço Azure Web PubSub

Artigo
10/26/2023

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 usando o protocolo HTTP CloudEvents.

Para cada evento, o serviço formula uma solicitação HTTP POST para o ponto de extremidade upstream registrado e espera uma resposta HTTP.

O envio de dados do serviço para o servidor está sempre no formato CloudEvents binary .

Screenshot of Web PubSub service event trigger.

Upstream e Validação

Quando você configura o ponto de extremidade webhook, a URL pode incluir o {event} parâmetro para definir um modelo de URL. O serviço calcula o valor da URL do webhook dinamicamente quando a solicitação do cliente chega. Por exemplo, quando uma solicitação /client/hubs/chat chega, com um padrão http://host.com/api/{event} de URL do manipulador de eventos configurado para hub chat, quando o cliente se conecta, ele primeiro POST para esta URL: http://host.com/api/connect. O {event} parâmetro pode ser útil quando um cliente PubSub WebSocket envia eventos personalizados, que o manipulador de eventos ajuda a despachar eventos diferentes para diferentes pontos de extremidade upstream. O {event} parâmetro não é permitido no nome de domínio da URL.

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. Cada URL de webhook upstream registado será validado por este mecanismo. O WebHook-Request-Origin cabeçalho da solicitação é definido como o nome de domínio do serviço e espera que a resposta tenha um cabeçalho WebHook-Allowed-Origin que contenha esse nome xxx.webpubsub.azure.comde 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 tentará 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.

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.

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	Descrição
`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"