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

  • Article
  • 4 minutes de lecture

Notes

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

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

Architecture serverless typique avec Azure Functions

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

Diagramme de l’architecture serverless type pour le service Azure SignalR

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

Dans une architecture serverless, les clients ont toujours des connexions persistantes à SignalR Service. Étant donné qu’il n’existe aucun serveur d’application pour gérer le trafic, les clients sont en mode LISTEN, ce qui signifie qu’ils peuvent uniquement recevoir des messages, ils ne peuvent pas en envoyer. SignalR Service déconnecte tous les clients qui envoient des messages, car c’est une opération qui n’est pas valide.

Vous trouverez un exemple complet d’utilisation de SignalR Service avec Azure Functions ici.

API

Le tableau suivant montre toutes les versions de l’API REST que nous avons pour l’instant. Vous trouverez également le fichier swagger pour chaque version de l’API REST.

Version d'API Statut Port Doc Spec
20220601 Latest Standard Doc swagger
1.0 Stable Standard Doc swagger
1.0-preview Obsolète Standard Doc swagger

Les dernières API disponibles sont listées comme suit.

API Path
Obtenir l’état d’intégrité du service. HEAD /api/health
Fermez toutes les connexions dans le hub. POST /api/hubs/{hub}/:closeConnections
Diffuser un message à tous les clients connectés au hub cible. POST /api/hubs/{hub}/:send
Vérifier si la connexion avec le connectionId donné existe HEAD /api/hubs/{hub}/connections/{connectionId}
Fermer la connexion cliente DELETE /api/hubs/{hub}/connections/{connectionId}
Envoyer un message à la connexion spécifique. POST /api/hubs/{hub}/connections/{connectionId}/:send
Vérifier s’il existe des connexions clientes dans le groupe donné HEAD /api/hubs/{hub}/groups/{group}
Fermez les connexions dans le groupe spécifique. POST /api/hubs/{hub}/groups/{group}/:closeConnections
Diffuser un message à tous les clients au sein du groupe cible. POST /api/hubs/{hub}/groups/{group}/:send
Ajouter une connexion au groupe cible. PUT /api/hubs/{hub}/groups/{group}/connections/{connectionId}
Supprimer une connexion du groupe cible. DELETE /api/hubs/{hub}/groups/{group}/connections/{connectionId}
Supprimer une connexion de tous les groupes DELETE /api/hubs/{hub}/connections/{connectionId}/groups
Vérifier s’il existe des connexions clientes connectées pour l’utilisateur donné HEAD /api/hubs/{hub}/users/{user}
Fermez les connexions pour l’utilisateur spécifique. POST /api/hubs/{hub}/users/{user}/:closeConnections
Diffuser un message à tous les clients appartenant à l’utilisateur cible. POST /api/hubs/{hub}/users/{user}/:send
Vérifier si un utilisateur existe dans le groupe cible. HEAD /api/hubs/{hub}/users/{user}/groups/{group}
Ajouter un utilisateur au groupe cible. PUT /api/hubs/{hub}/users/{user}/groups/{group}
Supprimer un utilisateur du groupe cible. DELETE /api/hubs/{hub}/users/{user}/groups/{group}
Supprimer un utilisateur de tous les groupes. DELETE /api/hubs/{hub}/users/{user}/groups

Utilisation de l'API REST

S’authentifier via une clé d’accès 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 AccessKey dans la chaîne de connexion de l’instance Azure SignalR Service pour signer le jeton JWT généré.

Revendications

Les revendications suivantes doivent être incluses dans le jeton JWT.

Type de revendication Est obligatoire Description
aud true Doit être identique à votre URL de requête HTTP, barre oblique de fin et paramètres de requête non inclus. 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.

S’authentifier via un jeton Azure Active Directory (jeton Azure AD)

Comme pour l’authentification avec AccessKey, lors de l’authentification avec un jeton Azure AD, un jeton JWT (JSON Web Token) est également nécessaire pour authentifier la requête HTTP.

La différence est, dans ce scénario, que le jeton JWT est généré par Azure Active Directory.

Découvrez comment générer des jetons Azure AD

Vous pouvez également utiliser le contrôle d’accès en fonction du rôle (RBAC) pour autoriser la requête de votre serveur/client à SignalR Service.

Découvrez comment configurer des rôles de contrôle d’accès en fonction du rôle pour votre ressource

Implémenter le point de terminaison Negotiate

Comme indiqué dans la section architecture, vous devez implémenter une fonction negotiate qui retourne une réponse de négociation de redirection afin que le client puisse se connecter au service. Une réponse de négociation typique se présente comme suit :

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

Le accessToken est généré à l’aide du même algorithme décrit dans la section authentification. La seule différence est que la revendication aud doit être identique à url.

Vous devez héberger votre API de négociation dans https://<hub_url>/negotiate afin de pouvoir continuer à utiliser le client SignalR pour vous connecter à l’URL du hub.

En savoir plus sur la redirection du client vers Azure SignalR Service ici.

Pour appeler l’API REST liée à l’utilisateur, chacun de vos clients doit s’identifier auprès de SignalR Service. Sinon, SignalR Service ne trouve pas les connexions cibles d’un ID utilisateur donné.

L’identification du client peut être obtenue en incluant une revendication nameid dans le jeton JWT de chaque client lorsqu’il se connecte à SignalR Service. Ensuite, SignalR Service utilise la valeur de la revendication nameid comme ID utilisateur de chaque connexion cliente.

Exemple

Vous trouverez une application console complète pour montrer comment créer manuellement une requête HTTP d’API REST dans SignalR Service ici.

Vous pouvez également utiliser Microsoft.Azure.SignalR.Management pour publier des messages sur SignalR Service à l’aide des interfaces similaires de IHubContext. Vous trouverez des exemples ici. Pour plus d’informations, consultez How to use Management SDK.

Limitation

Actuellement, nous avons les limitations suivantes pour les requêtes d’API REST :

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

Si vous voulez envoyer un message de plus de 1 Mo, utilisez le Management SDK en mode persistent.