Informations de référence sur l’API REST du plan de données Azure SignalR Service
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.
- 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 |
La plus récente | 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.
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.
API REST liée à l’utilisateur
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.