Guide pratique pour utiliser Azure SignalR Service avec Azure API Management

Le service Azure API Management fournit une plateforme de gestion hybride et multi-cloud dédiée aux API dans tous les environnements. Cet article vous montre comment ajouter une fonctionnalité en temps réel à votre application grâce à Azure API Management et Azure SignalR Service.

Important

Des chaînes de connexion brutes sont utilisées dans cet article à des fins de démonstration uniquement.

Une chaîne de connexion contient les informations d’autorisation requises pour que votre application accède au service Azure Web PubSub. La clé d’accès à l’intérieur dans la chaîne de connexion est semblable à un mot de passe racine pour votre service. Dans les environnements de production, protégez toujours vos clés d’accès. Utilisez Azure Key Vault pour gérer et faire pivoter vos clés en toute sécurité, et sécurisez votre chaîne de connexion en utilisant Microsoft Entra ID.

Évitez de distribuer des clés d’accès à d’autres utilisateurs, de les coder en dur ou de les enregistrer en texte brut dans un emplacement accessible à d’autres personnes. Effectuez une rotation de vos clés si vous pensez qu’elles ont pu être compromises.

Créer des ressources

• Suivez Démarrage rapide : utiliser un modèle ARM pour déployer Azure SignalR et créer une instance de service SignalR ASRS1

• Suivez Démarrage rapide : Utilisez un modèle ARM pour déployer azure API Management et créer une instance API Management APIM1

Configurer des API

Limites

Il existe deux types de requêtes pour un client SignalR :

• négocier la demande : requête POST HTTP à <APIM-URL>/client/negotiate/
• demande de connexion: demander à <APIM-URL>/client/, il peut être WebSocket ou ServerSentEvent ou LongPolling selon le type de transport de votre client SignalR

Le type de demande de connexion varie en fonction du type de transport des clients SignalR. Pour l’instant, API Management ne prend pas en charge différents types d’API pour le même suffixe. Avec cette limitation, lors de l’utilisation de API Management, votre client SignalR ne prend pas en charge le repli depuis le type de transport WebSocket vers d’autres types de transport. La repli de ServerSentEvent à LongPolling peut être pris en charge. Les sections ci-dessous décrivent les configurations détaillées pour différents types de transport.

Configurer des API lorsque le client se connecte avec un transport WebSocket

Cette section décrit les étapes pour configurer API Management lorsque les clients SignalR se connectent avec un transport WebSocket. Lorsque les clients SignalR se connectent avec un transport WebSocket, trois types de requêtes sont impliqués :

1. requête HTTP préliminaire OPTIONS pour négocier
2. requête HTTP POST pour négocier
3. Demande WebSocket pour la connexion

Nous allons configurer API Management à partir du portail.

1. Accédez à l’onglet API dans le portail pour l’instance API Management APIM1, sélectionnez Ajouter API et choisissez HTTP, Créer avec les paramètres suivants :
   • Nom d’affichage : SignalR negotiate
   • URL du service web : https://<your-signalr-service-url>/client/negotiate/
   • Suffixe de l’URL de l’API : client/negotiate/
2. Sélectionnez l’API créée SignalR negotiate, Enregistrer avec les paramètres ci-dessous :
   1. Sous l’onglet Conception
      1. Sélectionnez Ajouter une opération puis Enregistrer avec les paramètres suivants :
         • Nom d’affichage : negotiate preflight
         • URL : OPTIONS /
      2. Sélectionnez Ajouter une opération puis Enregistrer avec les paramètres suivants :
         • Nom d’affichage : negotiate
         • URL : POST /
   2. Basculez vers l’onglet Paramètres et décochez la case Abonnement requis afin d’avoir une démonstration rapide
3. Sélectionnez Ajouter une API puis choisissez WebSocket, Créer avec les paramètres suivants :
   • Nom d’affichage : SignalR connect
   • URL WebSocket : wss://<your-signalr-service-url>/client/
   • Suffixe de l’URL de l’API : client/
4. Sélectionnez l’API créée SignalR connect, Enregistrer avec les paramètres ci-dessous :
   1. Basculez vers l’onglet Paramètres et décochez la case Abonnement requis afin d’avoir une démonstration rapide

API Management est maintenant configurée avec succès pour prendre en charge le client SignalR avec un transport WebSocket.

Configurer des API lorsque le client se connecte avec un transport ServerSentEvents ou LongPolling

Cette section décrit les étapes pour configurer API Management lorsque les clients SignalR se connectent avec un type de transport ServerSentEvents ou LongPolling. Lorsque les clients SignalR se connectent avec un transport ServerSentEvents ou LongPolling, cinq types de requêtes sont impliqués :

1. requête HTTP préliminaire OPTIONS pour négocier
2. requête HTTP POST pour négocier
3. requête HTTP préliminaire OPTIONS pour la connexion
4. requête HTTP POST pour la connexion
5. requête GET HTTP pour la connexion

Nous allons maintenant configurer API Management à partir du portail.

1. Accédez à l’onglet API dans le portail pour l’instance API Management APIM1, sélectionnez Ajouter API et choisissez HTTP, Créer avec les paramètres suivants :
   • Nom d’affichage : SignalR
   • URL du service web : https://<your-signalr-service-url>/client/
   • Suffixe de l’URL de l’API : client/
2. Sélectionnez l’API créée SignalR, Enregistrer avec les paramètres ci-dessous :
   1. Sous l’onglet Conception
      1. Sélectionnez Ajouter une opération puis Enregistrer avec les paramètres suivants :
         • Nom d’affichage : negotiate preflight
         • URL : OPTIONS /negotiate
      2. Sélectionnez Ajouter une opération puis Enregistrer avec les paramètres suivants :
         • Nom d’affichage : negotiate
         • URL : POST /negotiate
      3. Sélectionnez Ajouter une opération puis Enregistrer avec les paramètres suivants :
         • Nom d’affichage : connect preflight
         • URL : OPTIONS /
      4. Sélectionnez Ajouter une opération puis Enregistrer avec les paramètres suivants :
         • Nom d’affichage : connect
         • URL : POST /
      5. Sélectionnez Ajouter une opération puis Enregistrer avec les paramètres suivants :
         • Nom d’affichage : connect get
         • URL : GET /
      6. Sélectionnez l’opération connecter, obtenir récemment ajoutée et modifiez la stratégie back-end pour désactiver la mise en mémoire tampon pour ServerSentEvents, consultez ici pour plus d’informations.

         <backend>
             <forward-request buffer-response="false" />
         </backend>
         

   2. Basculez vers l’onglet Paramètres et décochez la case Abonnement requis afin d’avoir une démonstration rapide

API Management est maintenant configurée avec succès pour prendre en charge le client SignalR avec un transport ServerSentEvents ou LongPolling.

Exécuter une conversation

Désormais, le trafic peut atteindre SignalR Service via API Management. Utilisons cette application de conversation en guise d’exemple. Commençons par l’exécuter localement.

Des chaînes de connexion brutes sont utilisées dans cet article à des fins de démonstration uniquement. Dans les environnements de production, protégez toujours vos clés d’accès. Utilisez Azure Key Vault pour gérer et faire pivoter vos clés en toute sécurité, et sécurisez votre chaîne de connexion en utilisant Microsoft Entra ID.

• Obtenons d’abord la chaîne de connexion d’ASRS1

  • Sous l’onglet Chaînes de connexion d’ASRS1
    • Point de terminaison client : Entrez l’URL à l’aide de l’URL de passerelle de APIM1, par exemple https://apim1.azure-api.net. Il s’agit d’un générateur de chaîne de connexion intervenant lors de l’utilisation de proxys inverses, dont la valeur n’est pas conservée en vue d’un prochain accès à cet onglet. Une fois la valeur entrée, la chaîne de connexion ajoute une section ClientEndpoint.
    • Copier la chaîne de connexion

• Cloner le dépôt GitHub https://github.com/aspnet/AzureSignalR-samples

• Accédez au dossier samples/Chatroom :

• Définissez la chaîne de connexion copiée et exécutez l’application localement. Vous pouvez voir la présence d’une section ClientEndpoint dans ConnectionString.

  cd samples/Chatroom
  dotnet restore
  dotnet user-secrets set Azure:SignalR:ConnectionString "<copied-connection-string-with-client-endpoint>"
  dotnet run
  

• Configurer le type de transport pour le client

  Ouvrez index.html dans le dossier wwwroot et cherchez le code lorsque connection est créé, mettez-le à jour pour spécifier le type de transport.

  Par exemple, pour spécifier à la connexion d’utiliser des événements envoyés par le serveur ou une interrogation longue, mettez à jour le code pour :

  const connection = new signalR.HubConnectionBuilder()
    .withUrl(
      "/chat",
      signalR.HttpTransportType.ServerSentEvents |
        signalR.HttpTransportType.LongPolling
    )
    .build();
  

  Pour spécifier la connexion à utiliser WebSockets, mettez à jour le code pour :

  const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chat", signalR.HttpTransportType.WebSockets)
    .build();
  

• Ouvrez http://localhost:5000 à partir du navigateur et utilisez F12 pour afficher les traces. Vous pouvez voir que la connexion est établie via APIM1

Étapes suivantes

Vous avez maintenant ajouté une fonctionnalité en temps réel à votre API Management à l’aide de Azure SignalR. En savoir plus sur SignalR Service.