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

  • Artículo
  • Tiempo de lectura: 5 minutos

Nota:

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

Además del patrón de cliente-servidor clásico, Azure SignalR Service proporciona un conjunto de API REST para que pueda integrar fácilmente la funcionalidad en tiempo real en la arquitectura sin servidor.

Arquitectura típica sin servidor con Azure Functions

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

Diagrama de una arquitectura sin servidor típica para Azure SignalR Service

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

En una arquitectura sin servidor, los clientes siguen teniendo conexiones persistentes con SignalR Service. Puesto que no hay ningún servidor de aplicaciones para controlar el tráfico, los clientes están en modo LISTEN, lo que significa que solo pueden recibir mensajes, pero no pueden enviar mensajes. SignalR Service desconectará cualquier cliente que envíe mensajes porque es una operación no válida.

Puede encontrar un ejemplo completo del uso de SignalR Service con Azure Functions aquí.

API

En la tabla siguiente, se muestran todas las versiones de la API REST que tenemos por ahora. También puede encontrar el archivo swagger de cada versión de la API REST.

Versión de la API Estado Port Doc Especificación
20220601 Más reciente Estándar Documentación swagger
1.0 Stable Estándar Documentación swagger
1.0-preview Obsoletos Estándar Documentación swagger

Las API disponibles más recientes se enumeran a continuación.

API Ruta de acceso
Obtiene el estado de mantenimiento del servicio. HEAD /api/health
Cierre todas las conexiones del centro. POST /api/hubs/{hub}/:closeConnections
Retransmitir un mensaje a todos los clientes conectados al centro de destino. POST /api/hubs/{hub}/:send
Comprobar si existe la conexión con el elemento connectionId especificado HEAD /api/hubs/{hub}/connections/{connectionId}
Cerrar la conexión de cliente DELETE /api/hubs/{hub}/connections/{connectionId}
Enviar un mensaje a una conexión específica. POST /api/hubs/{hub}/connections/{connectionId}/:send
Comprobar si hay alguna conexión de cliente dentro del grupo especificado HEAD /api/hubs/{hub}/groups/{group}
Cierre las conexiones del grupo específico. POST /api/hubs/{hub}/groups/{group}/:closeConnections
Retransmitir un mensaje a todos los clientes del grupo de destino. POST /api/hubs/{hub}/groups/{group}/:send
Agregar una conexión al grupo de destino. PUT /api/hubs/{hub}/groups/{group}/connections/{connectionId}
Quitar una conexión del grupo de destino. DELETE /api/hubs/{hub}/groups/{group}/connections/{connectionId}
Eliminación de una conexión de todos los grupos DELETE /api/hubs/{hub}/connections/{connectionId}/groups
Comprobar si hay alguna conexión de cliente conectada para el usuario especificado HEAD /api/hubs/{hub}/users/{user}
Cierre las conexiones del usuario específico. POST /api/hubs/{hub}/users/{user}/:closeConnections
Retransmitir un mensaje a todos los clientes que pertenecen al usuario de destino. POST /api/hubs/{hub}/users/{user}/:send
Comprobar si existe un usuario en el grupo de destino. HEAD /api/hubs/{hub}/users/{user}/groups/{group}
Agregar un usuario al grupo de destino. PUT /api/hubs/{hub}/users/{user}/groups/{group}
Quitar un usuario del grupo de destino. DELETE /api/hubs/{hub}/users/{user}/groups/{group}
Quitar un usuario de todos los grupos. DELETE /api/hubs/{hub}/users/{user}/groups

Uso de la API de REST

Autenticación mediante el elemento AccessKey de Azure SignalR Service

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

Firma y algoritmo de firma

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

Utilice el elemento AccessKey en la cadena de conexión de la instancia de Azure SignalR Service para firmar el token JWT generado.

Notificaciones

Se deben incluir las siguientes notificaciones en el token JWT.

Tipo de notificación Es obligatorio Descripción
aud true Debe ser igual a la dirección URL de la solicitud HTTP (barra diagonal final y parámetros de consulta no incluidos). 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 mediante el token de Azure Active Directory (token de Azure AD)

De forma similar a la autenticación mediante AccessKey, al autenticarse mediante el token de Azure AD, también se requiere un JSON Web Token (JWT) para autenticar la solicitud HTTP.

La diferencia es que, en este escenario, Azure Active Directory genera el token JWT.

Obtenga información sobre cómo generar tokens de Azure AD.

También puede usar el control de acceso basado en rol (RBAC) para autorizar la solicitud del cliente o servidor en SignalR Service.

Obtenga información sobre cómo configurar roles del control de acceso basado en rol para el recurso.

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

Como se muestra en la sección de arquitectura, debe implementar una función negotiate que devuelva una respuesta de negociación de redirección para que el cliente pueda conectarse al servicio. Una respuesta de negociación típica tiene el siguiente aspecto:

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

El elemento accessToken se genera con el mismo algoritmo descrito en la sección de autenticación. La única diferencia es que la notificación aud debe ser la misma que url.

Debe hospedar la API de negociación en https://<hub_url>/negotiate para que pueda seguir usando el cliente de SignalR para conectarse a la dirección URL del centro.

Obtenga más información sobre cómo redirigir el cliente a Azure SignalR Service aquí.

Para llamar a las API REST relacionadas con el usuario, cada uno de los clientes debe identificarse en SignalR Service. De lo contrario, SignalR Service no pueden encontrar conexiones de destino a partir de un identificador de usuario determinado.

La identificación del cliente se puede lograr mediante la inclusión de una notificación nameid en el token JWT de cada cliente cuando se conecta a SignalR Service. A continuación, SignalR Service usará el valor de la notificación nameid como identificador de usuario de cada conexión de cliente.

Ejemplo

Puede encontrar una aplicación de consola completa para demostrar cómo crear manualmente una solicitud HTTP de la API REST en SignalR Service aquí.

También puede usar Microsoft.Azure.SignalR.Management para publicar mensajes en SignalR Service mediante las interfaces similares de IHubContext. Los ejemplos se pueden encontrar aquí. Para más información, consulte Uso del SDK de administración.

Limitación

Actualmente, tenemos la siguiente limitación para las solicitudes de la API REST:

  • 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 quiere enviar mensajes de más de 1 MB, use el SDK de administración con el modo persistent.