Referencia de la API REST del plano de datos del servicio Azure Web PubSub

Como se muestra en el gráfico de flujo de trabajo anterior, así como en el flujo de trabajo detallado que se describe en Elementos internos, el servidor de aplicaciones puede enviar mensajes a los clientes o administrar los clientes conectados mediante las API REST que expone el servicio Web PubSub. En este artículo se describen detalladamente las API REST.

Uso de la API de REST

Nombres de grupos e IDs de usuario en las rutas de solicitud

Las operaciones REST que incluyen un nombre de grupo o un ID de usuario en la ruta de solicitud tienen una limitación con barras hacia adelante (/) en estos valores. La codificación URL de la barra puede %2F no resolver la limitación: la operación puede fallar en dirigirse al grupo o usuario previsto. Por ejemplo, un cliente conectado con el ID tenant/alice de usuario podría no ser encontrado por una solicitud REST cuyo camino contiene /users/tenant%2Falice.

Esta limitación se aplica a operaciones que utilizan estos parámetros de ruta, como enviar mensajes, comprobar si existe un grupo o usuario, cerrar conexiones y gestionar la pertenencia a un grupo. Los métodos del SDK del servidor que llaman a estos extremos REST están sujetos a la misma limitación. Esto es una limitación de la ruta de solicitud REST, no una prohibición general sobre / nombres de grupos o IDs de usuario en Web PubSub.

Para evitar la limitación, usa nombres de grupo e IDs de usuario sin / cuándo tu aplicación necesite estas operaciones REST. Si los identificadores de tu aplicación contienen /, mapealos a identificadores únicos y libres de barras y utiliza los valores asignados de forma consistente en tokens de acceso al cliente, pertenencia a grupos y llamadas REST. Cambiar solo el valor en la petición REST no cambia el ID de usuario ni el nombre del grupo asociado a una conexión existente.

Autenticación mediante la instancia de AccessKey del servicio Azure Web PubSub

En cada solicitud HTTP, se requiere un encabezado de autorización con un JSON Web Token (JWT) para autenticarse con el servicio Azure Web PubSub.

Firma y algoritmo de firma

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

Deberías usar la AccessKey instancia de cadena de conexión del servicio Azure Web PubSub para firmar el JWT generado.

Notificaciones

Las siguientes reclamaciones deben incluirse en el JWT.

Pseudocódigo en JS:

Las cadenas de conexión sin procesar solo aparecen en este artículo con fines de demostración. En entornos de producción, proteja siempre las claves de acceso. Use Azure Key Vault para administrar y rotar las claves de forma segura y proteja la conexión con WebPubSubServiceClient.

const bearerToken = jwt.sign({}, connectionString.accessKey, {
  audience: request.url,
  expiresIn: "1h",
  algorithm: "HS256",
});

Autenticación mediante el token de Microsoft Entra

Al igual que cuando se usa AccessKey, también se requiere un JSON Web Token (JWT) para autenticar la solicitud HTTP.

La diferencia es que, en este escenario, JWT se genera mediante Microsoft Entra ID.

Obtenga información sobre cómo generar tokens de Microsoft Entra

El ámbito de credencial usado debe ser https://webpubsub.azure.com/.default.

También puede usar el control de acceso basado en rol (RBAC) para autorizar la solicitud del servidor al servicio Azure Web PubSub.

Aprende cómo añadir asignaciones de roles

API existentes