Tutoriel : Utiliser l'extension Gestion des API Azure pour Visual Studio Code pour importer et gérer des API

Article
10/26/2023

S’APPLIQUE À : Consommation | Développeur | De base | Standard | Premium

Dans ce didacticiel, vous apprendrez à utiliser l'extension Gestion des API pour Visual Studio Code pour les opérations courantes dans Gestion des API. Vous utiliserez l’environnement familier de Visual Studio Code pour importer, mettre à jour, tester et gérer des API.

Vous allez apprendre à effectuer les actions suivantes :

Importer une API dans Gestion des API
Modifier l’API
Appliquer des stratégies Gestion des API
Tester l’API

Capture d’écran de l’API dans l’extension Gestion des API.

Pour obtenir une présentation d’autres fonctionnalités de l’extension Gestion des API, consultez les tutoriels Gestion des API dans le portail Azure.

Prérequis

Comprendre la terminologie relative au service Gestion des API Azure
Assurez-vous d'avoir installé Visual Studio Code et la dernière extension Gestion des API Azure pour Visual Studio Code.
Créer une instance de Gestion des API.

Importer une API

L’exemple suivant importe une spécification OpenAPI au format JSON dans Gestion des API. Microsoft fournit l’API back-end utilisée dans cet exemple et l’héberge sur Azure à l’adresse https://conferenceapi.azurewebsites.net.

Dans Visual Studio Code, sélectionnez l’icône Azure dans la barre d’activités.
Dans le volet de l’Explorateur, développez l’instance Gestion des API que vous avez créée.
Cliquez avec le bouton droit sur API, puis sélectionnez Importer à partir d’un lien OpenAPI.
Quand vous y êtes invité, entrez les valeurs suivantes :
1. Un lien OpenAPI pour du contenu au format JSON. Pour cet exemple : https://conferenceapi.azurewebsites.net?format=json .
  
  Ce fichier spécifie le service backend qui implémente l'exemple d'API, dans ce cas. https://conferenceapi.azurewebsites.net. Gestion des API transmet les requêtes à ce service Web.
2. Un nom d’API unique dans l’instance Gestion des API, par exemple demo-conference-api. Ce nom ne peut contenir que des lettres, des chiffres et des traits d’union. Le premier et le dernier caractères doivent être alphanumériques. Ce nom est utilisé dans le chemin pour appeler l’API.

Une fois l’API importée, elle apparaît dans le volet de l’Explorateur et les opérations d’API disponibles sont listées sous le nœud Opérations.

Capture d’écran de l’API importée dans le volet de l’Explorateur.

Modifier l’API

Vous pouvez modifier l’API dans Visual Studio Code. Par exemple, modifiez la description JSON Resource Manager de l’API dans la fenêtre de l’éditeur pour supprimer le protocole http utilisé pour accéder à l’API.

Capture d’écran de la modification de la description JSON dans Visual Studio Code.

Pour modifier le format OpenAPI, cliquez avec le bouton droit sur le nom de l’API dans le volet de l’Explorateur, puis sélectionnez Modifier OpenAPI. Apportez vos modifications, puis sélectionnez Fichier>Enregistrer.

Appliquer des stratégies à l’API

Gestion des API fournit des stratégies que vous pouvez configurer pour vos API. Les stratégies sont un ensemble d’instructions. Ces instructions sont exécutées de manière séquentielle sur demande ou sur réponse d’une API. Les stratégies peuvent être soit globales (c’est-à-dire qu’elles s’appliquent à toutes les API de votre instance Gestion des API), soit propres à un produit, une API ou une opération d’API.

Cette section montre comment appliquer des stratégies sortantes courantes à votre API pour transformer la réponse de l’API. Les stratégies de cet exemple modifient les en-têtes de réponse et masquent les URL de back-end d’origine qui apparaissent dans le corps de la réponse.

Dans le volet de l’Explorateur, sélectionnez Stratégie sous l’API demo-conference-api que vous avez importée. Le fichier de stratégie s’ouvre dans la fenêtre de l’éditeur. Ce fichier configure des stratégies pour toutes les opérations dans l’API.
Mettez le fichier à jour avec le contenu suivant dans l’élément <outbound> :
```
[...]
<outbound>
    <set-header name="Custom" exists-action="override">
        <value>"My custom value"</value>
    </set-header>
    <set-header name="X-Powered-By" exists-action="delete" />
    <redirect-content-urls />
    <base />
</outbound>
[...]
```
- La première stratégie set-header ajoute un en-tête de réponse personnalisé à des fins de démonstration.
- La deuxième stratégie set-header supprime l’en-tête X-Powered-By, s’il existe. Cet en-tête peut révéler l’infrastructure d’application utilisée dans le back-end d’API, et les éditeurs le suppriment souvent.
- La stratégie redirect-content-urls réécrit (masque) les liens dans le corps de la réponse afin qu’ils pointent vers les liens équivalents par l’intermédiaire de la passerelle Gestion des API.
Enregistrez le fichier . Si vous y êtes invité, sélectionnez Charger pour charger le fichier dans le cloud.

Tester l’API

Pour tester l'API, obtenez une clé de la souscription puis faites une requête à la passerelle de Gestion des API.

Obtenir la clé d’abonnement

Vous avez besoin d’une clé d’abonnement pour permettre à votre instance Gestion des API de tester l’API importée et les stratégies appliquées.

Dans le volet de l’Explorateur, cliquez avec le bouton droit sur le nom de votre instance Gestion des API.
Sélectionnez Copier la clé d’abonnement. Cette clé concerne l'abonnement à accès illimité intégré créé lorsque vous créez une instance de Gestion des API.

Attention

La souscription à accès illimité permet d'accéder à chaque API de cette instance de Gestion des API et ne doit être utilisé que par les utilisateurs autorisés. Ne l'utilisez jamais pour un accès de routine à l'API et n'intégrez jamais la clé d'accès complet dans les applications clientes.

Tester une opération d’API

Dans le volet de l’Explorateur, développez le nœud Opérations sous l’API demo-conference-api que vous avez importée.
Sélectionnez une opération comme GetSpeakers, puis cliquez avec le bouton droit sur l’opération et sélectionnez Opération de test.
Dans la fenêtre de l’éditeur, en regard de Ocp-Apim-Subscription-Key, remplacez {{SubscriptionKey}} par la clé d’abonnement que vous avez copiée.
À côté de Ocp-Apim-Trace, entrez false. Ce paramètre désactive le suivi des requêtes.
Sélectionnez Envoyer une demande.

Capture d’écran d’envoi d’une demande d’API à partir de Visual Studio Code.

Quand la demande réussit, le back-end répond avec 200 OK et des données.

Capture d’écran de la réponse de test d’API dans Visual Studio Code.

Notez les détails suivants dans la réponse :

L’en-tête Custom est ajouté à la réponse.
L’en-tête X-Powered-By n’apparaît pas dans la réponse.
Les URL au back-end d’API sont redirigées vers la passerelle Gestion des API, dans ce cas https://apim-hello-world.azure-api.net/demo-conference-api.

Traitement des requêtes de trace

Vous pouvez éventuellement obtenir des informations détaillées sur le suivi des requêtes pour vous aider à déboguer et dépanner l'API.

Pour suivre le traitement des requêtes, activez d’abord le paramètre Autoriser le suivi pour la souscription utilisé pour déboguer votre API. Pour connaître les étapes permettant d'activer ce paramètre à l'aide du portail, voir Vérifier le paramètre Autoriser le traçage. Pour limiter la divulgation involontaire d’informations sensibles, le traçage n’est autorisé que pendant 1 heure.

Après avoir autorisé le traçage avec votre abonnement, suivez ces étapes :

Dans le volet de l’Explorateur, développez le nœud Opérations sous l’API demo-conference-api que vous avez importée.
Sélectionnez une opération comme GetSpeakers, puis cliquez avec le bouton droit sur l’opération et sélectionnez Opération de test.
Dans la fenêtre de l'éditeur, à côté de Ocp-Apim-Subscription-Key, remplacez {{SubscriptionKey}} par la clé d'abonnement que vous souhaitez utiliser.
À côté de Ocp-Apim-Trace, entrez true. Ce paramètre active le suivi de cette requête.
Sélectionnez Envoyer une demande.

Lorsque la requête réussit, la réponse du backend inclut un en-tête Ocp-APIM-Trace-Location.

Capture d’écran de l’emplacement de suivi dans la réponse de test d’API dans Visual Studio Code.

Sélectionnez le lien en regard de Ocp-APIM-Trace-Location pour afficher les informations de trace entrante, backend et sortante. Les informations de trace vous aident à déterminer où les problèmes se sont produits à l’exécution de la requête.

Conseil

Lorsque vous testez les opérations de l'API, l'extension Gestion des API permet le débogage de stratégie facultatif (disponible uniquement dans le niveau de service Développeur).

Nettoyer les ressources

Quand vous n’en avez plus besoin, enlevez l’instance Gestion des API en cliquant avec le bouton droit et en sélectionnant Ouvrir dans le portail pour supprimer le service Gestion des API et son groupe de ressources.

Vous pouvez également sélectionner Supprimer Gestion des API pour supprimer uniquement l’instance Gestion des API (cette opération ne supprime pas son groupe de ressources).

Capture d’écran de la suppression de l’instance Gestion des API à partir de Visual Studio Code.

Ce didacticiel a présenté plusieurs fonctionnalités de l'extension Gestion des API pour Visual Studio Code. Vous pouvez utiliser ces fonctionnalités pour importer et gérer des API. Vous avez appris à :

Importer une API dans Gestion des API
Modifier l’API
Appliquer des stratégies Gestion des API
Tester l’API

L'extension Gestion des API fournit plus de fonctionnalités pour travailler avec vos API. Vous pouvez par exemple déboguer des stratégies (disponibles dans le niveau de service Développeur) ou créer et gérer des valeurs nommées.