Importer des API dans votre Centre API à partir de Gestion des API Azure

Cet article explique comment importer (ajouter) des API à partir d’une instance Gestion des API Azure dans votre Centre API à l’aide d’Azure CLI. L’ajout d’API à votre inventaire d’API à partir de Gestion des API permet de les rendre détectables et accessibles aux développeurs, aux gestionnaires de programmes d’API et à d’autres parties prenantes de votre organisation.

Cet article présente deux options d’utilisation d’Azure CLI pour ajouter des API à votre Centre API à partir de Gestion des API :

• Option 1 : Exporter une définition d’API à partir d’une instance Gestion des API à l’aide de la commande az apim api export. Ensuite, importer la définition dans votre Centre API.

  Voici quelques-unes des méthodes possibles d’importation d’une définition d’API exportée à partir de Gestion des API :

  • Exécuter az apic api register pour inscrire une nouvelle API dans votre Centre API.
  • Exécuter az apic api definition import-specification pour importer la définition d’API dans une API existante.

• Option 2 : Importer des API directement à partir de Gestion des API vers votre Centre API à l’aide de la commande az apic import-from-apim.

Après avoir importé des définitions d’API ou des API à partir de Gestion des API, vous pouvez ajouter des métadonnées et de la documentation dans votre Centre API afin d’aider les parties prenantes à découvrir, comprendre et consommer l’API.

Conseil

Vous pouvez également configurer la synchronisation automatique des API entre la Gestion des API et votre centre d’API. Pour plus d’informations, consultez Lier une instance Gestion des API pour synchroniser des API avec votre centre d’API.

Prérequis

• Un Centre d’API dans votre abonnement Azure. Si vous n’en avez pas créé, consultez Démarrage rapide : Créer votre Centre API.

• Une ou plusieurs instances de Gestion des API Azure, dans le même abonnement ou un autre abonnement. Lorsque vous importez des API directement à partir de Gestion des API, l’instance Gestion des API et le Centre API doivent se trouver dans le même annuaire. Si vous n’en avez pas créé, consultez Créer une instance Gestion des API Azure.

• Une ou plusieurs API gérées dans votre instance Gestion des API que vous souhaitez ajouter à votre Centre API.

• Pour 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.

  Notes

  Les commandes az apic nécessitent l’extension Azure CLI apic-extension. Si vous n’avez pas utilisé de commandes az apic, l’extension peut être installée dynamiquement lorsque vous exécutez votre première commande az apic, ou vous pouvez l’installer manuellement. Apprenez-en davantage sur les extensions Azure CLI.

  Consultez les notes de publication pour connaître les derniers changements et les dernières mises à jour de l’extension apic-extension. Certaines fonctionnalités peuvent nécessiter une préversion ou une version spécifique de l’extension.

  Notes

  Les exemples de commandes Azure CLI de cet article peuvent s’exécuter dans PowerShell ou dans un interpréteur de commandes bash. Si c’est nécessaire en raison d’une syntaxe de variables différente, des exemples distincts de commandes sont fournis pour les deux interpréteurs de commandes.

Option 1 : Exporter une définition d’API à partir de Gestion des API et l’importer dans votre Centre API

Tout d’abord, exportez une API de votre instance Gestion des API vers une définition d’API à l’aide de la commande az apim api export. En fonction de votre scénario, vous pouvez exporter la définition d’API vers un fichier local ou une URL.

Exporter l’API vers un fichier de définition d’API local

L’exemple de commande suivant exporte l’API avec l’identificateur my-api dans l’instance d’API myAPIManagement. L’API est exportée au format OpenApiJson vers un fichier de définition OpenAPI local sur le chemin que vous spécifiez.

#! /bin/bash
az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonFile \
    --file-path "/path/to/folder"

# Formatted for PowerShell
az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonFile `
    --file-path '/path/to/folder'

Exporter l’API vers une URL

Dans l’exemple suivant, az apim api export exporte l’API avec l’identificateur my-api au format OpenApiJson vers une URL dans le stockage Azure. L’URL est disponible pendant environ cinq minutes. Ici, la valeur de l’URL est stockée dans la variable $link.

#! /bin/bash
link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
    --output tsv)

# Formatted for PowerShell
$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
    --output tsv)

Inscrire l’API dans votre Centre API à partir de la définition d’API exportée

Vous pouvez inscrire une nouvelle API dans votre Centre API à partir de la définition exportée à l’aide de la commande az apic api register.

L’exemple suivant inscrit une API dans le Centre API myAPICenter à partir d’un fichier de définition OpenAPI local nommé definitionFile.json.

az apic api register --resource-group myResourceGroup --service-name myAPICenter --api-location "/path/to/definitionFile.json"

Importer une définition d’API vers une API existante dans votre Centre API

L’exemple suivant utilise la commande az apic api definition import-specification pour importer une définition d’API dans une API existante dans le Centre API myAPICenter. Ici, la définition d’API est importée à partir d’une URL stockée dans la variable $link.

Cet exemple part du principe que vous disposez d’une API nommée my-api ainsi que d’une version d’API associée v1-0-0 et d’une entité de définition openapi dans votre Centre API. Si ce n’est pas le cas, consultez Ajouter des API à votre Centre API.

#! /bin/bash
az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id my-api --version-id v1-0-0 \
    --definition-id openapi --format "link" --value '$link' \
    --specification '{"name":"openapi","version":"3.0.2"}'

# Formatted for PowerShell
az apic api definition import-specification `
    --resource-group myResourceGroup --service-name myAPICenter `
    --api-id my-api --version-id v1-0-0 `
    --definition-id openapi --format "link" --value '$link' `
    --specification '{"name":"openapi","version":"3.0.2"}'

Option 2 : Importer des API directement à partir de votre instance Gestion des API

Les étapes suivantes permettent d’importer des API à partir de votre instance Gestion des API dans votre Centre API à l’aide de la commande az apic import-from-apim. Cette commande est utile lorsque vous souhaitez importer plusieurs API de Gestion des API vers votre Centre API, mais vous pouvez également l’utiliser pour importer une seule API.

Lorsque vous ajoutez des API à partir d’une instance Gestion des API à votre Centre API à l’aide de az apic import-from-apim, les opérations suivantes se produisent automatiquement :

• Les versions, définitions et informations de déploiement de chaque API sont copiées dans votre Centre API.
• L’API reçoit un nom d’API généré par le système dans votre Centre API. Elle conserve son nom complet (titre) de Gestion des API.
• La phase du cycle de vie de l’API est définie sur Conception.
• Gestion des API Azure est ajoutée en tant qu’environnement.

Ajouter une identité managée dans votre Centre API

Activer une identité managée dans votre centre API

Pour ce scénario, votre centre API utilise une identité managée pour accéder aux ressources Azure. Selon vos besoins, activez une identité managée affectée par le système, ou une ou plusieurs identités managées affectées par l’utilisateur.

Les exemples suivants montrent comment activer une identité managée affectée par le système à l’aide du portail Azure ou d’Azure CLI. À un niveau élevé, les étapes de configuration sont similaires pour une identité gérée attribuée à un utilisateur.

Portail

1. Dans le portail, accédez à votre Centre API.
2. Dans le menu de gauche, sous Sécurité, sélectionnez Identités managées.
3. Sélectionnez Affectée par le système, puis définissez l’état sur Activé.
4. Cliquez sur Enregistrer.

Azure CLI

Définissez l’identité affectée par le système dans votre Centre API à l’aide de la commande az apic update suivante. Remplacez les noms de votre Centre API et de votre groupe de ressources :

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

Attribuer à l’identité managée le rôle Lecteur du service Gestion des API

Pour autoriser l’importation d’API, attribuez à l’identité managée de votre Centre API le rôle Lecteur du service Gestion des API dans votre instance Gestion des API. Vous pouvez utiliser le portail Azure ou Azure CLI.

Portail

1. Dans le portail, accédez à votre instance Gestion des API.
2. Dans le menu de gauche, sélectionnez Contrôle d’accès (IAM) .
3. Sélectionnez + Ajouter une attribution de rôle.
4. Dans la page Ajouter une attribution de rôle, définissez les valeurs comme suit :
   1. Sous l’onglet Rôle, sélectionnez Lecteur du service Gestion des API.
   2. Sous l’onglet Membres, dans Attribuer l’accès à : sélectionnez Identité managée>+ Sélectionner des membres.
   3. Dans la page Sélectionner les identités managées, sélectionnez l’identité managée affectée par le système de votre centre API que vous avez ajoutée dans la section précédente. Cliquez sur Sélectionner.
   4. Sélectionnez Vérifier + attribuer.

Azure CLI

1. Obtenez l’ID principal de l’identité. Pour une identité affectée par le système, utilisez la commande az apic show.

   #! /bin/bash
   apicObjID=$(az apic show --name <api-center-name> \
       --resource-group <resource-group-name> \
       --query "identity.principalId" --output tsv)
   

   # Formatted for PowerShell
   $apicObjID=$(az apic show --name <api-center-name> `
       --resource-group <resource-group-name> `
       --query "identity.principalId" --output tsv)
   

2. Obtenez l’ID de ressource de votre instance Gestion des API à l’aide de la commande az apim show.

   #! /bin/bash
   apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

   # Formatted for PowerShell
   $apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

3. Attribuez à l’identité managée le rôle Lecteur du service Gestion des API dans votre instance Gestion des API à l’aide de la commande az role assignment create.

   #! /bin/bash
   scope="${apimID:1}"
   
   az role assignment create \
       --role "API Management Service Reader Role" \
       --assignee-object-id $apicObjID \
       --assignee-principal-type ServicePrincipal \
       --scope $scope 
   

   # Formatted for PowerShell
   $scope=$apimID.substring(1)
   
   az role assignment create `
       --role "API Management Service Reader Role" `
       --assignee-object-id $apicObjID `
       --assignee-principal-type ServicePrincipal `
       --scope $scope 
   

Importer des API à partir de Gestion des API

Utilisez la commande az apic import-from-apim pour importer une ou plusieurs API à partir de votre instance Gestion des API dans votre Centre API.

Notes

• Cette commande dépend d’une identité managée configurée dans votre Centre API disposant d’autorisations de lecture sur l’instance Gestion des API. Si vous n’avez pas ajouté ou configuré d’identité managée, consultez Ajouter une identité managée dans votre Centre API plus haut dans cet article.

• Si votre Centre API a plusieurs identités managées, la commande recherche d’abord une identité affectée par le système. Si aucune n’est trouvée, elle sélectionne la première identité affectée par l’utilisateur dans la liste.

Importer toutes les API à partir d’une instance Gestion des API

Dans la commande suivante, remplacez les noms de votre Centre API, du groupe de ressources de votre Centre API, de votre instance Gestion des API et du groupe de ressources de votre instance. Utilisez * pour spécifier toutes les API de l’instance Gestion des API.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis '*'  

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis '*'  

Notes

Si votre instance Gestion des API a un grand nombre d’API, l’importation dans votre Centre API peut prendre un certain temps.

Importer une API spécifique à partir d’une instance Gestion des API

Spécifiez une API à importer à partir de l’instance Gestion des API en utilisant son nom.

Dans la commande suivante, remplacez les noms de votre Centre API, du groupe de ressources de votre Centre API, de votre instance Gestion des API et du groupe de ressources de votre instance. Passez un nom d’API tel que petstore-api à l’aide du paramètre --apim-apis.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis 'petstore-api'        

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis 'petstore-api'    

Notes

Spécifiez un nom d’API en utilisant le nom de ressource d’API dans l’instance Gestion des API, et pas le nom complet. Par exemple, petstore-api plutôt que Petstore API.

Après avoir importé des API à partir de Gestion des API, vous pouvez afficher et gérer les API importées dans votre Centre API.

Contenu connexe

• Informations de référence Azure CLI pour le Centre d’API Azure
• Informations de référence Azure CLI pour Gestion des API
• Gérer l’inventaire des API avec des commandes Azure CLI
• Attribuer des rôles Azure à une identité managée
• Documentation Gestion des API Azure