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.
Notes
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.
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.
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.
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.
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.
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é.
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. |
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.
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.
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.