Partager via

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

  • Article

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 :

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

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 :

    Remarque

    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.

    Pour connaître les dernières modifications et mises à jour relatives à apic-extension, consultez les notes de publication.

    Remarque

    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"

#! PowerShell syntax
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)

# PowerShell syntax
$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"}'

# PowerShell syntax
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

Pour ce scénario, votre Centre API utilise une identité managée afin d’accéder aux API dans votre instance Gestion des API. Selon vos besoins, configurez une identité managée affectée par le système ou une identité managée ou plus affectée par l’utilisateur.

Les exemples suivants montrent comment configurer 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.

  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.

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.

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

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.

Remarque

  • 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 '*'  

# PowerShell syntax
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 '*'

Remarque

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
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'        

# PowerShell syntax
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'

Remarque

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