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

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 :

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.

1. Dans Visual Studio Code, sélectionnez l’icône Azure dans la barre d’activités.
2. Dans le volet de l’Explorateur, développez l’instance Gestion des API que vous avez créée.
3. Cliquez avec le bouton droit sur API, puis sélectionnez Importer à partir d’un lien OpenAPI.
4. 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.

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.

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.

1. 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.

2. 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.

3. 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.

1. Dans le volet de l’Explorateur, cliquez avec le bouton droit sur le nom de votre instance Gestion des API.

2. 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

1. Dans le volet de l’Explorateur, développez le nœud Opérations sous l’API demo-conference-api que vous avez importée.
2. Sélectionnez une opération comme GetSpeakers, puis cliquez avec le bouton droit sur l’opération et sélectionnez Opération de test.
3. 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.
4. Sélectionnez Envoyer une demande.

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

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 connaître les étapes permettant d’activer le suivi pour une API, consultez Activer le suivi pour une API. Pour limiter la divulgation involontaire d’informations sensibles, le traçage n’est autorisé que pendant 1 heure par défaut.

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).

Contenu connexe

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 à :

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.