Referencia de la API REST del plano de datos de Azure SignalR Service

  • Artículo

Además del patrón de cliente o servidor clásico, Azure SignalR Service proporciona un conjunto de API REST que le ayudarán a integrar la funcionalidad en tiempo real en la arquitectura sin servidor.

Nota:

Azure SignalR Service solo admite el uso de API REST para administrar clientes conectados a través de ASP.NET Core SignalR. Los clientes conectados a través de ASP.NET SignalR usan un protocolo de datos diferente que no se admite actualmente.

Arquitectura típica sin servidor con Azure Functions

En el diagrama siguiente se muestra una arquitectura típica sin servidor que usa Azure SignalR Service con Azure Functions.

Diagram of a typical serverless architecture for Azure SignalR Service.

  • La negotiate función devuelve una respuesta de negociación y redirige a todos los clientes a Azure SignalR Service.
  • La broadcast función llama a la API REST para Azure SignalR Service. Azure SignalR Service difunde el mensaje a todos los clientes conectados.

En una arquitectura sin servidor, los clientes tienen conexiones persistentes a Azure SignalR Service. Dado que no hay ningún servidor de aplicaciones para controlar el tráfico, los clientes están en LISTEN modo. En ese modo, los clientes pueden recibir mensajes, pero no pueden enviar mensajes. Azure SignalR Service desconecta cualquier cliente que envíe mensajes porque es una operación no válida.

Puede encontrar un ejemplo completo del uso de Azure SignalR Service con Azure Functions en este repositorio de GitHub.

Implementación del punto de conexión de negociación

Debe implementar una negotiate función que devuelva una respuesta de negociación de redirección para que los clientes puedan conectarse al servicio.

Una respuesta de negociación típica tiene este formato:

{
  "url": "https://<service_name>.service.signalr.net/client/?hub=<hub_name>",
  "accessToken": "<a typical JWT token>"
}

El accessToken valor se genera a través del mismo algoritmo descrito en la sección autenticación. La única diferencia es que la aud notificación debe ser la misma que url.

Debe hospedar la API de negociación en https://<hub_url>/negotiate para que pueda seguir usando un cliente de SignalR para conectarse a la dirección URL del centro. Obtenga más información sobre la redirección de clientes a Azure SignalR Service en conexiones de cliente.

Versiones de la API REST

En la tabla siguiente se muestran todas las versiones admitidas de la API REST. También proporciona el archivo swagger para cada versión de API.

Versión de API Estado Port Documentación Especificación
20220601 Más reciente Estándar Artículo Archivo de Swagger
1.0 Stable Estándar Artículo Archivo de Swagger
1.0-preview Obsoleto Estándar Artículo Archivo de Swagger

En la tabla siguiente se enumeran las API disponibles.

API Path
Difusión de un mensaje a todos los clientes conectados al centro de destino POST /api/v1/hubs/{hub}
Difundir un mensaje a todos los clientes pertenecen al usuario de destino POST /api/v1/hubs/{hub}/users/{id}
Enviar mensaje a la conexión específica POST /api/v1/hubs/{hub}/connections/{connectionId}
Comprobar si existe la conexión con el elemento connectionId especificado GET /api/v1/hubs/{hub}/connections/{connectionId}
Cerrar la conexión de cliente DELETE /api/v1/hubs/{hub}/connections/{connectionId}
Difundir un mensaje a todos los clientes del grupo de destino POST /api/v1/hubs/{hub}/groups/{group}
Comprobar si hay alguna conexión de cliente dentro del grupo especificado GET /api/v1/hubs/{hub}/groups/{group}
Comprobar si hay alguna conexión de cliente conectada para el usuario especificado GET /api/v1/hubs/{hub}/users/{user}
Adición de una conexión al grupo de destino PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Quitar una conexión del grupo de destino DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Comprobar si existe un usuario en el grupo de destino GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
Agregar un usuario al grupo de destino PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
Quitar un usuario del grupo de destino DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
Eliminación de un usuario de todos los grupos DELETE /api/v1/hubs/{hub}/users/{user}/groups

Mediante la API de REST

Autenticación mediante AccessKey en Azure SignalR Service

En cada solicitud HTTP, se requiere un encabezado de autorización con un token web JSON (JWT) para autenticarse con Azure SignalR Service.

Algoritmo de firma y firma

HS256 (concretamente HMAC-SHA256) se usa como algoritmo de firma.

Use el AccessKey valor de la cadena de conexión de la instancia de Azure SignalR Service para firmar el JWT generado.

Notificaciones

Las siguientes notificaciones deben incluirse en el JWT.

Tipo de notificación Es obligatorio Descripción
aud true Debe ser el mismo que la dirección URL de la solicitud HTTP, no incluida la barra diagonal final y los parámetros de consulta. Por ejemplo, la audiencia de una solicitud de difusión debe tener el aspecto siguiente: https://example.service.signalr.net/api/v1/hubs/myhub.
exp true Hora de época en la que expirará este token.

Autenticación a través del token de Microsoft Entra

De forma similar a la autenticación a través AccessKeyde , se requiere un JWT para autenticar una solicitud HTTP mediante un token de Microsoft Entra.

La diferencia es que, en este escenario, el id. de Microsoft Entra genera el JWT. Para obtener más información, consulte Más información sobre cómo generar tokens de Microsoft Entra.

También puede usar el control de acceso basado en rol (RBAC) para autorizar la solicitud desde el cliente o servidor a Azure SignalR Service. Para más información, consulte Autorización del acceso con el identificador de Entra de Microsoft para Azure SignalR Service.

Para llamar a la API REST relacionada con el usuario, cada uno de los clientes debe identificarse en Azure SignalR Service. De lo contrario, Azure SignalR Service no puede encontrar conexiones de destino desde el identificador de usuario.

Puede lograr la identificación del cliente mediante la inclusión de una nameid notificación en el JWT de cada cliente cuando se conecta a Azure SignalR Service. A continuación, Azure SignalR Service usa el valor de la nameid notificación como identificador de usuario para cada conexión de cliente.

Ejemplo

En este repositorio de GitHub, puede encontrar una aplicación de consola completa para demostrar cómo compilar manualmente una solicitud HTTP de API REST en Azure SignalR Service.

También puede usar Microsoft.Azure.SignalR.Management para publicar mensajes en Azure SignalR Service mediante las interfaces similares de IHubContext. Puede encontrar ejemplos en este repositorio de GitHub. Para más información, consulte SDK de administración de Azure SignalR Service.

Limitaciones

Actualmente, las solicitudes de API REST tienen las siguientes limitaciones:

  • El tamaño del encabezado tiene un máximo de 16 KB.
  • El tamaño del cuerpo tiene un máximo de 1 MB.

Si desea enviar mensajes de más de 1 MB, use el SDK de administración de servicios con persistent el modo .