Partage via

Informations de référence sur l’API REST du plan de données Azure SignalR Service

  • Article

En plus du modèle client/serveur classique, Azure SignalR Service fournit un ensemble d’API REST pour vous aider à intégrer des fonctionnalités en temps réel dans votre architecture serverless.

Remarque

Azure SignalR Service prend en charge l’utilisation d’API REST uniquement pour gérer les clients connectés via ASP.NET Core SignalR. Les clients connectés via ASP.NET SignalR utilisent un autre protocole de données qui n’est actuellement pas pris en charge.

Architecture serverless classique avec Azure Functions

Le diagramme suivant illustre une architecture serverless classique qui utilise Azure SignalR Service avec Azure Functions.

Diagramme d’une architecture serverless classique pour Azure SignalR Service.

  • La negotiate fonction retourne une réponse de négociation et redirige tous les clients vers Azure SignalR Service.
  • La broadcast fonction appelle l’API REST pour Azure SignalR Service. Azure SignalR Service diffuse le message à tous les clients connectés.

Dans une architecture serverless, les clients ont des connexions persistantes à Azure SignalR Service. Étant donné qu’il n’existe aucun serveur d’applications pour gérer le trafic, les clients sont en LISTEN mode. Dans ce mode, les clients peuvent recevoir des messages, mais ne peuvent pas envoyer de messages. Azure SignalR Service déconnecte tout client qui envoie des messages, car il s’agit d’une opération non valide.

Vous trouverez un exemple complet d’utilisation d’Azure SignalR Service avec Azure Functions dans ce dépôt GitHub.

Implémenter le point de terminaison de négociation

Vous devez implémenter une negotiate fonction qui retourne une réponse de négociation de redirection afin que les clients puissent se connecter au service.

Une réponse de négociation classique a ce format :

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

La accessToken valeur est générée via le même algorithme décrit dans la section d’authentification. La seule différence est que la aud revendication doit être identique à url.

Vous devez héberger votre API https://<hub_url>/negotiate de négociation afin que vous puissiez toujours utiliser un client SignalR pour vous connecter à l’URL du hub. En savoir plus sur la redirection de clients vers Azure SignalR Service dans les connexions clientes.

Versions de l’API REST

Le tableau suivant présente toutes les versions d’API REST prises en charge. Il fournit également le fichier Swagger pour chaque version de l’API.

Version d’API État Port Documentation Spécification
20220601 Latest Standard Article Fichier Swagger
1.0 Stable Standard Article Fichier Swagger
1.0-preview Obsolète Standard Article Fichier Swagger

Le tableau suivant répertorie les API disponibles.

API Chemin d’accès
Diffuser un message à tous les clients connectés au hub cible POST /api/v1/hubs/{hub}
Diffuser un message à tous les clients appartient à l’utilisateur cible POST /api/v1/hubs/{hub}/users/{id}
Envoyer un message à la connexion spécifique POST /api/v1/hubs/{hub}/connections/{connectionId}
Vérifier si la connexion avec le connectionId donné existe GET /api/v1/hubs/{hub}/connections/{connectionId}
Fermer la connexion cliente DELETE /api/v1/hubs/{hub}/connections/{connectionId}
Diffuser un message à tous les clients au sein du groupe cible POST /api/v1/hubs/{hub}/groups/{group}
Vérifier s’il existe des connexions clientes dans le groupe donné GET /api/v1/hubs/{hub}/groups/{group}
Vérifier s’il existe des connexions clientes connectées pour l’utilisateur donné GET /api/v1/hubs/{hub}/users/{user}
Ajouter une connexion au groupe cible PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Supprimer une connexion du groupe cible DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Vérifier si un utilisateur existe dans le groupe cible GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
Ajouter un utilisateur au groupe cible PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
Supprimer un utilisateur du groupe cible DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
Supprimer un utilisateur de tous les groupes DELETE /api/v1/hubs/{hub}/users/{user}/groups

Utilisation de l’API REST

Authentification via AccessKey dans Azure SignalR Service

Dans chaque requête HTTP, un en-tête d’autorisation avec un jeton web JSON (JWT) est requis pour s’authentifier auprès d’Azure SignalR Service.

Algorithme de signature et signature

HS256, à savoir HMAC-SHA256, est utilisé comme algorithme de signature.

Utilisez la AccessKey valeur de l’instance Azure SignalR Service chaîne de connexion pour signer le JWT généré.

Revendications

Les revendications suivantes doivent être incluses dans le JWT.

type de revendication Obligatoire Description
aud true Doit être identique à l’URL de votre requête HTTP, sans inclure la barre oblique de fin et les paramètres de requête. Par exemple, le public d’une requête de diffusion devrait ressembler à : https://example.service.signalr.net/api/v1/hubs/myhub.
exp true Heure Epoch d’expiration de ce jeton.

Authentification via le jeton Microsoft Entra

Comme pour l’authentification via AccessKey, un JWT est requis pour authentifier une requête HTTP à l’aide d’un jeton Microsoft Entra.

La différence est que dans ce scénario, Microsoft Entra ID génère le JWT. Pour plus d’informations, consultez Découvrez comment générer des jetons Microsoft Entra.

L’étendue des informations d’identification utilisée doit être https://signalr.azure.com/.default.

Vous pouvez également utiliser le contrôle d’accès en fonction du rôle (RBAC) pour autoriser la demande de votre client ou serveur à Azure SignalR Service. Pour plus d’informations, consultez Autoriser l’accès avec l’ID Microsoft Entra pour Azure SignalR Service.

Pour appeler l’API REST associée à l’utilisateur, chacun de vos clients doit s’identifier auprès d’Azure SignalR Service. Sinon, Azure SignalR Service ne peut pas trouver de connexions cibles à partir de l’ID utilisateur.

Vous pouvez obtenir l’identification du client en incluant une nameid revendication dans le JWT de chaque client lorsqu’il se connecte à Azure SignalR Service. Azure SignalR Service utilise ensuite la valeur de la nameid revendication comme ID utilisateur pour chaque connexion cliente.

Exemple

Dans ce référentiel GitHub, vous trouverez une application console complète pour montrer comment générer manuellement une requête HTTP d’API REST dans Azure SignalR Service.

Vous pouvez également utiliser Microsoft.Azure.SignalR.Management pour publier des messages sur Azure SignalR Service à l’aide des interfaces similaires de IHubContext. Vous trouverez des exemples dans ce référentiel GitHub. Pour plus d’informations, consultez le Kit de développement logiciel (SDK) Azure SignalR Service Management.

Limites

Actuellement, les demandes d’API REST présentent les limitations suivantes :

  • La taille maximale de l’en-tête est de 16 Ko.
  • La taille maximale du corps est de 1 Mo.

Si vous souhaitez envoyer des messages de plus de 1 Mo, utilisez le Kit de développement logiciel (SDK) Service Management avec persistent le mode.