Importer une spécification OpenAPI

S’APPLIQUE À : tous les niveaux de Gestion des API

Cet article montre comment importer une API de serveur principal de « spécification OpenAPI » se trouvant à l’adresse https://conferenceapi.azurewebsites.net?format=json. Cette API de serveur principal est fournie par Microsoft et hébergée sur Azure. L’article explique également comment tester l’API APIM.

Dans cet article, vous apprendrez comment :

• Importez une spécification OpenAPI à l’aide du Portail Azure, d’Azure CLI ou de Azure PowerShell.
• Tester l’API dans le portail Azure

Notes

Les limitations d’importation d’API sont documentées dans les restrictions d’importation d’API et les problèmes connus.

Prérequis

• Une instance APIM. Si vous n’avez pas encore d’instance Gestion des API Azure, suivez ce guide de démarrage rapide : Créer une instance Gestion des API Azure.

• Azure CLI

  • Utilisez l’environnement Bash dans Azure Cloud Shell. Pour plus d’informations, consultez Démarrage rapide pour Bash dans Azure Cloud Shell.

    

  • Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Guide pratique pour exécuter Azure CLI dans un conteneur Docker.

    • Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour connaître les autres options de connexion, consultez Se connecter avec Azure CLI.

    • Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser des extensions avec Azure CLI.

    • Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.

• Azure PowerShell

  • Si vous choisissez d’utiliser Azure PowerShell localement :
    • Installez la dernière version du module Az PowerShell.
    • Connectez-vous à votre compte Azure à l’aide de la cmdlet Connect-AzAccount.
  • Si vous choisissez d’utiliser Azure Cloud Shell :
    • Pour plus d’informations, consultez Vue d’ensemble d’Azure Cloud Shell.

Importer une API back-end

Portail

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

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

3. Sous Créer à partir d’une définition, sélectionnez OpenAPI.

   

4. Entrez les paramètres de l’API. Vous pouvez définir les valeurs lors de la création, ou les configurer ultérieurement en accédant à l’onglet Paramètres. Les paramètres sont expliqués dans le tutoriel Importer et publier votre première API.

5. Sélectionnez Create (Créer).

Azure CLI

L’exemple suivant utilise la commande az apim api import pour importer une spécification OpenAPI à partir de l’URL spécifiée dans une instance Gestion des API nommée apim-hello-world. Pour importer à l’aide d’un chemin d’une spécification au lieu d’une URL, utilisez le paramètre --specification-path.

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="demo-conference-api"
APIPath="conference"
SpecificationFormat="OpenAPI"
SpecificationURL="https://conferenceapi.azurewebsites.net/?format=json"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --specification-format $SpecificationFormat --specification-url $SpecificationURL

Après avoir importé l’API, si nécessaire, vous pouvez mettre à jour les paramètres à l’aide de la commande de mise à jour az apim api .

PowerShell

L’exemple suivant utilise l’applet de commande Azure PowerShell Import-AzApiManagementApi pour importer une spécification OpenAPI à partir de l’URL spécifiée dans une instance Gestion des API nommée apim-hello-world. Pour importer à l’aide d’un chemin d’une spécification au lieu d’une URL, utilisez le paramètre -SpecificationPath.

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "demo-conference-api"
$apiPath = "conference"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://conferenceapi.azurewebsites.net/?format=json"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

Après avoir importé l’API, si nécessaire, vous pouvez mettre à jour les paramètres à l’aide de l’applet de commande Set-AzApiManagementApi .

Tester la nouvelle API dans le portail

Les opérations peuvent être appelées directement à partir du portail, ce qui permet d’afficher et de tester facilement les opérations d’une API.

1. Sélectionnez l’API que vous avez créée à l’étape précédente.

2. Sélectionnez l’onglet Test.

3. Sélectionnez une opération. La page affiche des champs pour les paramètres de requête et des champs pour les en-têtes.

   Notes

   Dans la console de test, Gestion des API renseigne automatiquement un en-tête Ocp-Apim-Subscription-Key, et configure la clé d’abonnement de l’abonnement avec accès complet intégré. Cette clé permet d’accéder à toutes les API dans l’instance Gestion des API. Vous pouvez éventuellement afficher l’en-tête Ocp-Apim-Subscription-Key en sélectionnant l’icône « œil » en regard de la requête HTTP.

4. En fonction de l’opération, entrez des valeurs de paramètre de requête, des valeurs d’en-tête ou un corps de requête. Sélectionnez Envoyer.

   Lorsque le test réussit, le backend répond avec un code de réponse HTTP réussi et quelques données.

   Conseil

   Par défaut, la console de test envoie une demande au proxy CORS de Gestion des API, qui transmet la demande à l'instance d'API Management, qui la transmet ensuite au backend. Ce proxy utilise l'adresse IP publique 13.91.254.72 et ne peut atteindre que les terminaux publics. Si vous souhaitez envoyer une requête directement du navigateur au service Gestion des API, sélectionnez Bypass CORS proxy. Utilisez cette option lorsque vous souhaitez utiliser la console de test et que votre passerelle de Gestion des API est isolée du réseau ou n'autorise pas le trafic provenant du proxy CORS.

Pour déboguer une API, consultez Tutoriel : Déboguer vos API à l’aide du suivi des requêtes.

Ajouter d’autres API

Vous pouvez composer une API à partir de plusieurs API exposées par différents services, notamment :

• Une spécification OpenAPI
• Une API SOAP
• Une API GraphQL
• Une application web hébergée dans Azure App Service
• Application Azure Function
• Azure Logic Apps
• Azure Service Fabric

Pour ajouter une autre API à votre API existante, effectuez les étapes suivantes.

Notes

Une fois que vous avez importé une autre API, les opérations sont ajoutées à votre API actuelle.

1. Accédez à votre instance Gestion des API Azure dans le portail Azure.

   

2. Sélectionnez API dans la page Vue d’ensemble ou dans le menu situé à gauche.

   

3. Cliquez sur ... à côté de l’API à laquelle vous souhaitez ajouter une autre API.

4. Sélectionnez Importer dans le menu déroulant.

   

5. Sélectionnez un service à partir duquel importer une API.

   

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 OData
• Importer des métadonnées OData de SAP
• Importer une API gRPC
• Modifier une API

Valider par rapport à une spécification OpenAPI

Vous pouvez configurer la stratégies de validation Gestion des API pour valider les requêtes et réponses (ou leurs éléments) par rapport au schéma dans une spécification OpenAPI. Par exemple, utilisez la stratégie validate-content pour valider la taille ou le contenu d’une requête//du corps d’une réponse.

Étapes suivantes

• Créer et publier un produit
• Transform and protect your API (Transformer et protéger votre API)