Configuración del controlador de eventos en el servicio Azure Web PubSub

Artículo
09/19/2024

El controlador de eventos controla los eventos de cliente entrantes. Los controladores de eventos se registran y configuran en el servicio a través de Azure Portal o la CLI de Azure. Cuando se desencadena un evento de cliente, el servicio puede enviar el evento al controlador de eventos adecuado. El servicio Web PubSub ahora admite el controlador de eventos como servidor, que expone el punto de conexión accesible públicamente para que el servicio invoque cuando se desencadene el evento. En otras palabras, actúa como un webhook.

El servicio Web PubSub entrega eventos de cliente al webhook ascendente configurado mediante el Protocolo HTTP CloudEvents, con la Extensión CloudEvents para el controlador de eventos de Azure Web PubSub.

Captura de pantalla del desencadenador de eventos del servicio Web PubSub.

Configuración del controlador de eventos

Un cliente siempre se conecta a un centro de conectividad y puede configurar varias opciones de controlador de eventos para el centro. El orden de la configuración del controlador de eventos es importante y el primero tiene la prioridad más alta. Cuando un cliente se conecta y se desencadena un evento, Web PubSub pasa por los controladores de eventos configurados en el orden de prioridad y el primer resultado coincidente. Establezca las siguientes propiedades al configurar el controlador de eventos:

Nombre de la propiedad	Descripción
Plantilla de dirección URL	Define la plantilla Que Web PubSub usa para evaluar la dirección URL del webhook ascendente.
Eventos de usuario	Define los eventos de usuario en los que se preocupa la configuración del controlador de eventos actual.
Eventos del sistema	Define los eventos del sistema en los que se preocupa la configuración del controlador de eventos actual.
Autenticación	Define el método de autenticación entre el servicio Web PubSub y el servidor ascendente.

Eventos

Los eventos incluyen eventos de usuario y eventos del sistema. Los eventos del sistema son eventos predefinidos que se desencadenan durante la vigencia de un cliente. Los eventos de usuario se desencadenan cuando el cliente envía datos, el nombre de evento de usuario se puede personalizar mediante protocolos de cliente, aquí contiene la explicación detallada.

Tipo de evento	Valores admitidos
Eventos del sistema	`connect`, `connected` y `disconnected`
Eventos de usuario	`message`, o nombre de evento personalizado siguiendo los protocolos de cliente

URL template

La plantilla de dirección URL admite varios parámetros que se pueden evaluar durante el tiempo de ejecución. Con esta característica, es fácil enrutar diferentes centros o eventos a diferentes servidores ascendentes con una única configuración. La sintaxis de referencia de KeyVault también es compatible para que los datos se puedan almacenar de forma segura en Azure Key Vault.

Nota El nombre de dominio de dirección URL no debe contener sintaxis de parámetros, por ejemplo, http://{hub}.com no es una plantilla de dirección URL válida.

Parámetros admitidos	Sintaxis	Descripción	Ejemplos
Parámetro del concentrador	`{hub}`	El valor es el centro al que se conecta el cliente.	Cuando un cliente se conecta a `client/hubs/chat`, una plantilla de dirección URL `http://host.com/api/{hub}` se evalúa como `http://host.com/api/chat` porque para este cliente, el centro es `chat`.
Parámetro de evento	`{event}`	Valor del evento desencadenado. Los valores `event` se enumeran aquí. El valor del evento para las solicitudes de protección contra abusos es `validate` como se explica aquí.	Si hay una plantilla de dirección URL `http://host.com/api/{hub}/{event}` configurada para el evento `connect`, cuando un cliente se conecta a `client/hubs/chat`, Web PubSub inicia una solicitud POST a la dirección URL evaluada `http://host.com/api/chat/connect` cuando el cliente se conecta, ya que para este evento de cliente, el centro es `chat` y el evento que desencadena esta configuración del controlador de eventos es `connect`.
Parámetro de referencia de KeyVault	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	El SecretUri debe ser el URI completo del plano de datos de un secreto en el almacén, incluida opcionalmente una versión, por ejemplo, `https://myvault.vault.azure.net/secrets/mysecret/` o `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`. Al usar la referencia de KeyVault, también debe configurar la autenticación entre el servicio Web PubSub y el servicio KeyVault, consulte aquí para ver los pasos detallados.	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)`

Autenticación entre el servicio y el webhook

Puede usar cualquiera de estos métodos para autenticarse entre el servicio y el webhook.

Modo anónimo
La autenticación simple con ?code=<code> se proporciona a través de la dirección URL de Webhook configurada como parámetro de consulta.
Autorización de Microsoft Entra. Para obtener más información, consulte Uso de una identidad administrada en eventos de cliente.

Servidor ascendente y validación

Al configurar el webhook del controlador de eventos a través de Azure Portal o la CLI, el servicio sigue la CloudEvents Abuse Protection para validar el webhook ascendente. Este mecanismo valida todas las direcciones URL de webhook ascendente registradas. El encabezado de la solicitud WebHook-Request-Origin se establece en el nombre de dominio del servicio xxx.webpubsub.azure.com, y espera que la respuesta que tiene el encabezado WebHook-Allowed-Origin contenga este nombre de dominio o *.

Al realizar la validación, el parámetro {event} se resuelve en validate. Por ejemplo, al intentar establecer la dirección URL en http://host.com/api/{event}, el servicio intenta OPTIONS una solicitud para http://host.com/api/validate. Y solo cuando la respuesta es válida, la configuración se puede establecer correctamente.

Por ahora, no se admiten WebHook-Request-Rate ni WebHook-Request-Callback.

Configuración del controlador de eventos

Configuración mediante Azure Portal

Puede agregar un controlador de eventos a un nuevo centro o editar un centro existente.

Para configurar un controlador de eventos en un nuevo centro:

Vaya a la página del servicio Azure Web PubSub en Azure Portal.
Seleccione Configuración en el menú.
Seleccione Agregar para crear un centro y configurar la dirección URL del webhook del lado servidor. Nota: Para agregar un controlador de eventos a un centro existente, seleccione el centro y seleccione Editar.
Escriba el nombre del centro.
Seleccione Agregar en Configurar controladores pares.
En la página del controlador de eventos, configure los siguientes campos: 1. Escriba la dirección URL del webhook del servidor en el campo Plantilla de dirección URL. 1. Seleccione los Eventos del sistema a los que desea suscribirse. 1. Seleccione los Eventos de usuario a los que desea suscribirse. 1. Seleccione Método de autenticación para autenticar las solicitudes ascendentes. 1. Seleccione Confirmar.
Seleccione Guardar en la parte superior de la página Configurar ajustes del centro de control.

Configuración mediante la CLI de Azure

Use los comandos del grupo de centro de conectividad az webpubsub de la CLI de Azure para configurar los ajustes del controlador de eventos.

Comandos:	Descripción
`create`	Cree la configuración del centro de conectividad para el servicio WebPubSub.
`delete`	Permite eliminar la configuración del centro de conectividad para el servicio WebPubSub.
`list`	Permite enumerar la configuración del centro de conectividad para el servicio WebPubSub.
`show`	Permite mostrar la configuración del centro de conectividad para el servicio WebPubSub.
`update`	Permite actualizar la configuración del centro de conectividad para el servicio WebPubSub.

A continuación se muestra un ejemplo de creación de dos direcciones URL de webhooks para el recurso centro MyHub de 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"