Controlador de eventos en el servicio Azure Web PubSub

Artículo
10/26/2023

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 mediante el protocolo HTTP CloudEvents.

Para cada evento, el servicio formula una solicitud HTTP POST al punto de conexión ascendente registrado y espera una respuesta HTTP.

Los datos que se envían del servicio al servidor siempre están en formato binary de CloudEvents.

Screenshot of Web PubSub service event trigger.

Servidor ascendente y validación

Al configurar el punto de conexión de webhook, la dirección URL puede incluir el {event} parámetro para definir una plantilla de dirección URL. El servicio calcula el valor de la dirección URL del webhook dinámicamente cuando entra la solicitud del cliente. Por ejemplo, cuando llega una solicitud /client/hubs/chat, con un patrón http://host.com/api/{event} de dirección URL de controlador de eventos configurado para el centro chat, cuando el cliente se conecta, primero se aplica POST a esta dirección URL: http://host.com/api/connect. El {event} parámetro puede ser útil cuando un cliente webSocket de PubSub envía eventos personalizados, que el controlador de eventos ayuda a enviar diferentes eventos a distintos puntos de conexión ascendentes. El parámetro {event} no se permite en el nombre de dominio de la dirección URL.

Al configurar el webhook del controlador de eventos a través de Azure Portal o la CLI, el servicio sigue cloudEvents Abuse Protection para validar el webhook ascendente. Este mecanismo validará todas las direcciones URL de webhook ascendentes 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 intentará ejecutar OPTIONS en una solicitud a 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.

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.

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 centro de conectividad Configuración.

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.

Este es un ejemplo de creación de dos direcciones URL de webhook para el centro MyHub de MyWebPubSub recursos:

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"