Tutoriel : Importer et publier votre première API

CONCERNE : Tous les niveaux de gestion des API

Ce tutoriel montre comment importer une API principale de spécification OpenAPI au format JSON dans Azure API Management. Pour cet exemple, vous importez l’API open source Petstore.

Lorsque vous importez l’API back-end dans API Management, votre API API Management devient la passerelle pour l’API back-end. Vous pouvez personnaliser la passerelle en fonction de vos besoins dans API Management sans modifier l’API back-end. Pour plus d’informations, consultez Transformer et protéger votre API.

Dans ce tutoriel, vous allez apprendre à :

Après l’importation, vous pouvez gérer l’API dans le Azure portal.

Prérequis

• Comprendre Azure API Management terminologie.
• Créez une instance Azure API Management.

Accédez à votre instance de API Management

1. Dans le Azure portal, recherchez et sélectionnez API Management services :

   

2. Dans la page API Management services, sélectionnez votre instance de API Management :

   

Importer et publier une API back-end

Cette section montre comment importer et publier une API de serveur principal à la spécification OpenAPI.

1. Dans votre instance de API Management, sous APIs dans le menu de la barre latérale, sélectionnez APIs.

2. Sélectionnez la vignette OpenAPI.

3. Dans la fenêtre Créer à partir de la spécification OpenAPI, sélectionnez Complet.

4. Entrez les valeurs du tableau suivant.

   Vous pouvez définir les valeurs de l’API au moment de la création, ou un peu plus tard en accédant à l’onglet Paramètres.

   

   Réglage	valeur	Description
   Spécification OpenAPI	https://petstore3.swagger.io/api/v3/openapi.json -ou- https://petstore.swagger.io/v2/swagger.json	Spécifie le service back-end implémentant l’API et les opérations que l’API prend en charge. L’URL du service principal apparaît ultérieurement en tant qu’URL du service Web dans la page Paramètres de l’API. Après l’importation, vous pouvez ajouter, modifier, renommer ou supprimer des opérations dans la spécification.
   Inclure des paramètres de requête dans les modèles d’opération	Sélectionné par défaut	Spécifie s’il faut importer les paramètres de requête requis dans la spécification en tant que paramètres de modèle dans API Management.
   Nom d'affichage	Après avoir entré l’URL de spécification OpenAPI, API Management remplit ce champ en fonction du json.	Nom affiché dans le portail des développeurs.
   Nom	Après avoir entré l’URL de spécification OpenAPI, API Management remplit ce champ en fonction du json.	Nom unique de l’API.
   Description	Après avoir entré l’URL de spécification OpenAPI, API Management remplit ce champ en fonction du json.	Description facultative de l’API.
   Modèle d’URL	HTTPS	Quels protocoles peuvent access l’API.
   Suffixe de l’URL de l’API	petstore	Suffixe ajouté à l’URL de base du service API Management. API Management distingue et route les API par leur suffixe, de sorte que le suffixe doit être unique pour chaque API pour une publisher donnée. En savoir plus sur comment API Management gère les requêtes.
   Balises		Étiquettes permettant d’organiser les API pour la recherche, le regroupement ou le filtrage.
   Produits	Illimité	Association d’une ou de plusieurs API. Dans certains niveaux, API Management instance est fournie avec deux exemples de produits : Starter et Unlimited. Vous publiez une API dans le portail des développeurs en associant l’API à un produit. Vous pouvez inclure plusieurs API dans un produit et proposer des abonnements aux développeurs via le portail des développeurs. Pour ajouter cette API à un autre produit, tapez ou sélectionnez le nom du produit. Répétez cette étape pour ajouter l’API à plusieurs produits. Vous pouvez également ajouter des API aux produits plus tard à partir de la page Paramètres. Pour plus d’informations sur les produits, consultez Créer et publier un produit.
   Passerelles	Géré	Passerelles d’API qui exposent l’API. Ce champ est disponible uniquement dans les services des niveaux Développeur et Premium. Managed indique la passerelle intégrée au service API Management et hébergée par Microsoft dans Azure. Les passerelles auto-hébergées sont disponibles seulement dans les niveaux de service Premium et Développeur. Vous pouvez les déployer localement ou dans d’autres clouds. Si vous ne sélectionnez aucune passerelle, l’API n’est pas disponible et vos demandes d’API ne réussissent pas.
   Créer une version pour cette API ?	Sélectionner ou désélectionner	Pour plus d’informations, consultez Publier plusieurs versions de votre API.

5. Sélectionnez Créer pour créer votre API.

Si vous rencontrez des problèmes lors de l’importation d’une définition d’API, consultez les restrictions d’importation d’API et les problèmes connus.

Afficher et modifier les paramètres d’API

Après avoir importé votre API, vous pouvez afficher et modifier ses paramètres et ses opérations dans le Azure portal.

1. Dans votre instance de API Management, sous APIs dans le menu de la barre latérale, sélectionnez APIs.

2. Sélectionnez votre API importée (par exemple , Swagger Petstore).

3. Sélectionnez l’onglet Création pour afficher et modifier les opérations d’API dans la spécification OpenAPI, notamment :

   • Détails de l’opération, tels que l’URL, la méthode et la description
   • Définitions de demande et de réponse
   • Stratégies de modification des demandes et des réponses

4. Sélectionnez l’onglet Paramètres pour afficher et modifier les détails de configuration de l’API, notamment :

   • Nom d’affichage, nom et description
   • URL du service web (service principal), schéma d’URL et suffixe d’URL d’API
   • Produits, étiquettes et contrôle de version
   • Paramètres plus avancés, tels que les exigences d’abonnement, la sécurité et la surveillance

À mesure que vous parcourez les didacticiels API Management, vous en apprendrez davantage sur la configuration des paramètres d’API. Vous pouvez mettre à jour ces paramètres à tout moment pour personnaliser votre configuration d’API.

Tester la nouvelle API dans le Azure portal

Vous pouvez appeler des opérations d’API directement à partir de l’Azure portal, ce qui offre un moyen pratique d’afficher et de tester les opérations. Dans la console de test du portail, par défaut, les API sont appelées en utilisant une clé de l'abonnement intégré tout accès. Vous pouvez également tester les appels d’API à l’aide d’une clé d’abonnement limitée à un produit.

1. Dans votre instance de API Management, sélectionnez APIs>APIs>Swagger Petstore.

2. Sélectionnez l’onglet Test, puis Finds Pets by status (Recherche d’animaux par disponibilité). La page affiche le paramètre de requêtestatus. Sélectionnez l’une des valeurs disponibles, telles que pending (en attente). Vous pouvez également ajouter des paramètres de requête et des en-têtes ici.

   Dans la section requête HTTP, l’en-tête Ocp-Apim-Subscription-Key est renseigné automatiquement pour vous, ce que vous pouvez voir si vous sélectionnez l’icône « œil ».

3. Sélectionnez Envoyer.

   

   Le back-end répond avec 200 OK et des données.

Comment API Management achemine les demandes

API Management agit comme une passerelle entre vos clients API et vos services back-end. Lorsqu’un client effectue une demande à une API gérée par API Management, le routage suit ce modèle :

URL de demande du client :
[API Management gateway URL] + [API URL suffix] + [Operation endpoint]

API Management transfère la requête au service principal à l’aide de ce modèle :

URL du service principal :
[Web service URL] + [Operation endpoint]

Le tableau suivant décrit chaque paramètre de routage dans le contexte de l’exemple d’API Petstore utilisé dans ce tutoriel :

Exemple : Recherche d’animaux de compagnie par état

Utilisation de l’API Petstore importée dans ce tutoriel :

• Client appelle API Management :
  https://apim-hello-world.azure-api.net/petstore/pet/findByStatus?status=pending

  • URL de passerelle API Management : https://apim-hello-world.azure-api.net
  • Suffixe d’URL de l’API : petstore
  • Point de terminaison d’opération : /pet/findByStatus

• API Management route vers backend :
  https://petstore3.swagger.io/api/v3/pet/findByStatus?status=pending

  • URL du service web : https://petstore3.swagger.io/api/v3
  • Point de terminaison d’opération : /pet/findByStatus (identique à la définition de API Management)

Étape suivante

Passez au tutoriel suivant pour découvrir comment créer et publier un produit :