Configurar o manipulador de eventos no serviço Azure Web PubSub

Artigo
08/07/2024

O manipulador de eventos lida com os eventos de entrada do cliente. 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 cliente é disparado, o serviço pode enviar o evento para o manipulador de eventos apropriado. O serviço Web PubSub agora dá 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 é disparado. Em outras palavras, ele atua como um webhook.

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

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 é disparado, o Web PubSub passa pelos manipuladores de eventos configurados na ordem de prioridade e o primeiro correspondente vence. Ao configurar o manipulador de eventos, as propriedades abaixo devem ser definidas.

Nome da propriedade	Descrição
Modelo de URL	Define o modelo que o Web PubSub usa para avaliar a URL do webhook upstream.
Eventos de usuário	Define os eventos do usuário aos quais a configuração atual do manipulador de eventos se preocupa.
Eventos do sistema	Define os eventos do sistema aos 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.

Eventos

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

Tipo de evento	Valores com suporte
Eventos do sistema	`connect`, `connected` e `disconnected`
Eventos de usuário	`message`ou nome de evento personalizado seguindo protocolos de cliente

Modelo do URL

O modelo de URL dá suporte a vários parâmetros que podem ser avaliados durante o runtime. Com esse recurso, é fácil rotear diferentes hubs ou eventos para diferentes servidores upstream com uma única configuração. A sintaxe de referência do KeyVault também é compatível para que os dados possam ser armazenados no Azure Key Vault com segurança.

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

Parâmetros com suporte	Sintaxe	Descrição	Exemplos
Parâmetro do hub	`{hub}`	O valor é o hub ao qual o cliente se conecta.	Quando um cliente se conecta a `client/hubs/chat`, um modelo de URL `http://host.com/api/{hub}` é avaliado como `http://host.com/api/chat` porque, para esse cliente, o hub é `chat`.
Parâmetro de evento	`{event}`	O valor do evento disparado. `event` 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 de URL `http://host.com/api/{hub}/{event}` configurado para `connect`de eventos, quando um cliente se conecta ao `client/hubs/chat`, o Web PubSub inicia uma solicitação POST para a URL avaliada `http://host.com/api/chat/connect` quando o cliente está se conectando, pois para esse evento cliente, o hub é `chat` e o evento que dispara essa configuração de manipulador de eventos é `connect`.
Parâmetro de referência KeyVault	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	O SecretUri deve ser o URI completo do plano de dados de um segredo no cofre, incluindo opcionalmente 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 KeyVault, você também precisa configurar a autenticação entre o serviço Web PubSub e o serviço KeyVault, verifique aqui para obter etapas detalhadas.	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)`

Autenticação entre o serviço e o 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 por meio da URL do Webhook configurada como parâmetro de consulta.
Autorização do Microsoft Entra. Para obter mais informações, confira Usar uma identidade gerenciada no AKS.

Upstream e validação

Ao configurar o webhook do manipulador de eventos por meio do portal do Microsoft Azure ou da CLI, o serviço segue o CloudEvents Abuse Protection para validar o webhook upstream. Cada URL do webhook upstream registrada será validada por esse mecanismo. O cabeçalho de solicitação WebHook-Request-Origin é definido como o nome de domínio de serviço xxx.webpubsub.azure.com e espera que a resposta com o cabeçalho WebHook-Allowed-Origin contenha esse nome de domínio ou *.

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

Por enquanto, não damos suporte para WebHook-Request-Rate e WebHook-Request-Callback.

Configurar o manipulador de eventos

Configurar por meio 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:

Acesse sua página de serviço do Azure Web PubSub no Portal do Microsoft Azure.
Selecione o menu Configurações.
Selecione Adicionar para criar um hub e configurar a URL do webhook do lado do servidor. Observação: 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 aos quais você deseja assinar. 1. Selecione os Eventos do usuário aos quais 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 Definir Configurações do Hub.

Configurar por meio da CLI do Azure

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

Comandos	Descrição
`create`	Criar configurações de hub do Serviço WebPubSub.
`delete`	Excluir configurações de hub do Serviço WebPubSub.
`list`	Listar todas as configurações de hub do Serviço WebPubSub.
`show`	Mostrar as configurações de hub do Serviço WebPubSub.
`update`	Atualize as configurações de hub do Serviço WebPubSub.

Aqui está um exemplo de criação de duas URLs de webhook para o 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"