Importer une API WebSocket

S’applique à : Développeur | Essentiel | Essentiel v2 | Standard | Standard v2 | Premium | Premium v2

Avec la solution d’API WebSocket de Gestion des API, les éditeurs d’API peuvent rapidement ajouter une API WebSocket dans Gestion des API via le Portail Azure, Azure CLI, Azure PowerShell et d’autres outils Azure.

Remarque

Cette fonctionnalité n’est actuellement pas disponible dans les espaces de travail.

Vous pouvez sécuriser les API WebSocket en appliquant des stratégies de contrôle d’accès existantes, telles que la validation JWT. Vous pouvez également tester les API WebSocket à l’aide des consoles de test de l’API dans le Portail Azure et le portail des développeurs. En se basant sur les capacités d’observation existantes, API Management fournit des indicateurs de performance et des journaux pour la surveillance et le dépannage des API WebSocket.

En lisant cet article, vous pourrez :

• Comprendre le flux direct du WebSocket.
• Ajouter une API WebSocket dans votre instance API Management.
• Tester votre API WebSocket.
• Consulter les métriques et les journaux de votre API WebSocket.
• Découvrez les limitations de l’API WebSocket.

Prérequis

• Disposer d’une instance d’API Management. Si vous ne l’avez pas déjà fait, créez-en un.
• Une API WebSocket.
• Azure CLI

Relais WebSocket

API Management prend en charge le relais WebSocket.

Pendant le transfert WebSocket, l’application cliente établit une connexion WebSocket avec la passerelle API Management, qui établit ensuite une connexion avec les services principaux correspondants. API Management transmet ensuite les messages client-serveur WebSocket.

1. L’application cliente envoie une requête d’établissement de liaison WebSocket à la passerelle APIM, en appelant l’opération onHandshake.
2. La passerelle APIM envoie une requête d’établissement d'une liaison WebSocket au service principal correspondant.
3. Le service principal met à niveau une connexion à WebSocket.
4. La passerelle APIM met à niveau la connexion correspondante à WebSocket.
5. Une fois la paire de connexions établie, APIM répartira les messages entre l’application cliente et le service principal.
6. L’application cliente envoie un message à la passerelle APIM.
7. La passerelle APIM transfère le message au service principal.
8. Le service principal envoie un message à la passerelle APIM.
9. La passerelle APIM transfère le message à l’application cliente.
10. Lorsque l’une ou l’autre se déconnecte, APIM met fin à la connexion correspondante.

Notes

Les connexions côté client et côté serveur se composent d’un mappage un-à-un.

Opération onHandshake

Selon le protocole WebSocket, lorsqu’une application cliente essaie d’établir une connexion WebSocket avec un service principal, elle envoie d’abord une requête d’établissement d'une liaison d’ouverture. Chaque API WebSocket dans API Management a une opération onHandshake. onHandshake est une opération système non modifiable, non amovible, créée automatiquement. L’opération onHandshake permet aux éditeurs d’API d’intercepter ces requêtes d’établissement d'une liaison et d’appliquer des stratégies d’API Management à celles-ci.

Ajouter une API WebSocket

Portail

1. 1. Dans le portail Azure, accédez à votre instance APIM.

2. Dans le menu de gauche, cliquez sur API>+Ajouter une API.

3. Sous Définir une nouvelle API, sélectionnez WebSocket.

4. Dans la boîte de dialogue, sélectionnez Complète et renseignez les champs de formulaire requis.

   Champ	Description
   Nom complet	Le nom par lequel votre API WebSocket sera affichée.
   Nom	Nom brut de l’API WebSocket. Se remplit automatiquement à mesure que vous tapez le nom complet.
   URL WebSocket	URL de base avec le nom de votre WebSocket. Par exemple : ws://example.com/your-socket-name
   Modèle d’URL	Accepter la valeur par défaut
   Suffixe de l’URL de l’API	Ajoutez un suffixe d’URL pour identifier cette API spécifique dans cette instance de gestion des API. Il doit être unique dans cette instance APIM.
   Produits	Associez votre API WebSocket à un produit pour la publier.
   Passerelles	Associez votre API WebSocket à des passerelles existantes.

5. Cliquez sur Créer.

Tester votre API WebSocket.

1. Accédez à votre API WebSocket.

2. Dans votre API WebSocket, sélectionnez l'opération onHandshake.

3. Sélectionnez l'onglet Test pour accéder à la console de test.

4. Si vous le souhaitez, fournissez les paramètres de chaîne de requête requis pour l'établissement d'une liaison WebSocket.

   

5. Cliquez sur Connexion.

6. Consultez l'état de la connexion dans Sortie.

7. Entrez la valeur dans Charge utile.

8. Cliquez sur Envoyer.

9. Consultez les messages reçus dans Sortie.

10. Répétez les étapes précédentes pour tester différentes charges utiles.

11. Une fois le test terminé, sélectionnez Déconnecter.

Afficher les métriques et les journaux

Utilisez les fonctionnalités API Management et Azure Monitor standard pour surveiller les API WebSocket :

• Afficher des métriques d’API dans Azure Monitor
• Vous pouvez éventuellement activer les paramètres de diagnostic pour collecter et afficher les journaux de la passerelle API Management, y compris les opérations de l’API WebSocket

Par exemple, la capture d’écran suivante montre les réponses récentes de l’API WebSocket avec le code 101 de la table ApiManagementGatewayLogs. Ces résultats indiquent la réussite du basculement des demandes de TCP vers le protocole WebSocket.

Limites

Voici les restrictions actuelles de la prise en charge de WebSocket dans API Management :

• Les API WebSocket ne sont pas encore prises en charge dans le niveau Consommation.
• Les API WebSocket prennent en charge les types de tampons valides suivants pour les messages : Close, BinaryFragment, BinaryMessage, UTF8Fragment et UTF8Message.
• Pour le moment, la stratégie set-header ne prend pas en charge la modification de certains en-têtes connus, comme les en-têtes Host, dans les requêtes onHandshake.
• Lors de l’établissement d’une liaison TLS avec un serveur principal WebSocket, Gestion des API vérifie que le certificat de serveur est approuvé et que son nom d’objet correspond au nom d’hôte. Avec les API HTTP, Gestion des API vérifie que le certificat est approuvé, mais ne valide pas que le nom d’hôte et le sujet correspondent.

Pour connaître les limites de connexion WebSocket, consultez limites de gestion des API.

Stratégies non prises en charge

Les stratégies suivantes ne sont pas prises en charge par et ne peuvent pas être appliquées à l’opération onHandshake :

• Réponse factice
• Obtention à partir du cache
• Stockage dans le cache
• Autorisation des appels inter-domaines
• CORS
• JSONP
• Set request method
• Définir le corps
• Conversion de XML à JSON
• Convert JSON to XML
• Transformation de XML à l’aide de XSLT
• Valider le contenu
• Valider les paramètres
• Valider les en-têtes
• Valider le code d’état

Notes

Si vous avez appliqué les stratégies aux étendues supérieures (par exemple, générale ou produit) et qu’elles ont été héritées par une API WebSocket via la stratégie, elles seront ignorées au moment de l’exécution.

Rubriques connexes

• Limitations de l’importation d’API
• Importer une spécification OpenAPI
• Importer une API SOAP
• Importer une API SOAP et la convertir pour REST
• Importer une API App Service
• Importer une API Container App
• Importer une API WebSocket
• Importer une API GraphQL
• Importer un schéma GraphQL et configurer des résolveurs de champs
• Importer une application de fonction Azure
• Importer une application logique Azure
• Importer un service Service Fabric
• Importer une API Azure OpenAI
• Importer une API OData
• Importer des métadonnées OData de SAP
• Importer une API gRPC
• Modifier une API

Étapes suivantes

Transform and protect your API (Transformer et protéger votre API)