Prise en main du Centre d’API

Effectué

Dans cet exercice, vous allez :

1. Créez un service du Centre d’API.

2. Définissez les propriétés de métadonnées.

3. Ajoutez des API à votre Centre d’API.

4. Ajoutez des déploiements et des environnements.

Prérequis

Pour commencer à gérer vos API via le Centre d’API, vous avez besoin des éléments suivants :

1. Un abonnement Azure.
2. Fournisseur de ressources Microsoft.ApiCenter inscrit dans votre abonnement.
3. Au moins une attribution de rôle Contributeur ou autorisations équivalentes dans l’abonnement Azure.

Remarque

Si ce n’est déjà fait, vous devez inscrire le fournisseur de ressources Microsoft.ApiCenter dans votre abonnement.

1. Connectez-vous au portail Azure.
2. Entrez abonnements dans la barre de recherche.
3. Sélectionnez l’abonnement dans lequel vous souhaitez créer le Centre d’API.
4. Dans le menu de gauche, sous Ressources, sélectionnez fournisseurs de ressources.
5. Recherchez Microsoft.ApiCenter dans la liste des fournisseurs de ressources. S’il n’est pas encore inscrit, sélectionnez Inscrire.

Étape 1 : Créer un service du Centre d’API

1. Connectez-vous au portail Azure.

2. Saisissez les Centres d’API dans la barre de recherche.

3. Sélectionnez + Créer.

4. Dans l’onglet De base, entrez ou sélectionnez les paramètres suivants :

   a. Sélectionnez votre abonnement Azure.

   b. Sélectionnez un groupe de ressources existant ou sélectionnez Nouveau pour en créer un.

   c. Entrez un nom pour votre centre d’API. Il doit être unique dans la région où vous créez votre centre d’API.

   d. Dans Région, sélectionnez l’une des régions disponibles pour le Centre d’API.

   e. Pour le plan tarifaire, sélectionnez essai gratuit (0 $ pendant 90 jours).

   f. Sélectionnez Revoir + créer.

   .h Une fois la validation terminée, sélectionnez Créer.

   Après le déploiement, votre centre d’API est prêt à être utilisé !

Pour exécuter des commandes de référence CLI localement, installer Azure CLI et vous connecter à l’aide de la commande suivante.

az login

Remarque

Si ce n’est déjà fait, vous devez inscrire le fournisseur de ressources Microsoft.ApiCenter dans votre abonnement.

Exécutez la commande suivante pour inscrire le fournisseur de ressources

az provider register –namespace Microsoft.ApiCenter 

Étape 1 : Créer un service du Centre d’API

Créez un groupe de ressources en exécutant la commande suivante en transférant :

• Exemple de nom de groupe de ressources --name. Contoso
• Exemple d’emplacement --location. Eastus

az group create –-name contoso –-location eastus  

Remarque

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

Créez un Centre d’API en exécutant la commande suivante, en transférant :

• Exemple de nom de service du Centre d’API -n. contoso-apis
• Exemple de groupe de ressources -g. Contoso
• emplacement --I Exemple. Eastus

az apic create -n contoso-apis -g contoso -l eastus 

Remarque

Par défaut, le Centre d’API est créé sous le Niveau tarifaire gratuit.

Remarque

La création d’un service de Centre d’API n’est actuellement pas prise en charge sur VS Code. Créez-en un à l’aide d’Azure CLI ou du portail Azure.

Étape 2 : Définir des propriétés de métadonnées

Le Centre d’API utilise des propriétés de métadonnées pour organiser les API dans votre inventaire et activer des opérations telles que le filtrage, la recherche, etc.

Remarque

N’incluez pas d’informations sensibles, confidentielles ou personnelles dans les titres/noms des propriétés de métadonnées.

Contoso, comme beaucoup d’autres organisations, aimeraient que toutes leurs API passent par un approbateur avant qu’elles ne soient disponibles pour être utilisées et s’assurer qu’une révision de conformité est effectuée pour toutes les API. L’organisation dispose également d’API accessibles au public et conçues exclusivement pour une utilisation interne uniquement. Pour appliquer cela à grande échelle sur toutes les API, nous ajoutons trois propriétés de métadonnées personnalisées :

• Approbateur d’API de type Chaîne
• Examen de conformité de type Choix prédéfinis
• Public de type Booléen

1. Dans le menu de gauche, sélectionnez Ressources > Métadonnées > + Nouvelles métadonnées.

2. Sous l’onglet Détails, entrez des informations sur la propriété.

   a. Dans Titre, saisissez Approbateur d’API

   b. Dans Description, saisissez Approbateur d’API par défaut

   c. Sélectionnez le type Chaîne, puis sélectionnez suivant

3. Sous l’onglet Affectations, sélectionnez Obligatoire pour les API. Sélectionnez Facultatif pour Déploiements et environnements. Sélectionnez Suivant.

4. Sélectionnez Créer

5. Répétez les mêmes étapes pour la propriété Public-facing, comme illustré dans l’image ci-dessous. Pour le type, sélectionnez Booléen

6. Sous l’onglet Affectations, sélectionnez Obligatoire pour les API. Sélectionnez Non applicable pour les déploiements et les environnements. Sélectionnez Suivant.

7. Sélectionnez Créer

8. Répétez les mêmes étapes pour la propriété Compliance-review, comme illustré dans l’image ci-dessous. Pour le type, sélectionnez Choix prédéfinis et ajoutez 3 choix, Non démarré, En cours et Terminé

9. Sous l’onglet Affectations, sélectionnez Obligatoire pour les API. Sélectionnez Non applicable pour les déploiements et les environnements

10. Sélectionnez Suivant.

Un schéma de métadonnées JSON pour vos API est désormais disponible pour afficher, modifier et télécharger. Pour afficher, sélectionnez Afficher le schéma de métadonnées, puis sélectionnez les API dans la liste déroulante.

Cela ouvre un modal à droite avec des détails de métadonnées, qui incluent des propriétés intégrées à partir du Centre d’API, telles que LifecycleStage, Name, Description, TermsOfService entre autres. Si vous faites défiler vers le bas du fichier, vous verrez les métadonnées personnalisées que vous avez ajoutées dans les étapes précédentes, comme indiqué ci-dessous.

Remarque

Vous pouvez ajouter et modifier des propriétés dans le schéma à tout moment et les appliquer instantanément à toutes les API de votre Centre d’API

Créez un schéma de métadonnées en exécutant la commande suivante pour définir les éléments suivants :

• Métadonnées nom en tant qu' api-approbateur
• Schéma avec le type de propriété String et le titre en tant qu’approbateur d’API
• Affectations comme requis pour les API tandis que facultative pour Environnement et Déploiement

az apic metadata create -g contoso -n contoso-apis --metadata-name "api-approver" --schema '{"type":"string","title":"API Approver"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

Répétez les mêmes étapes pour :

• Nom des métadonnées en tant que public
• Schéma avec le type de propriété Booléen et Titre Public
• Affectations comme requis pour les API tandis que facultative pour Environnement et Déploiement

En exécutant la commande suivante :

az apic metadata create -g contoso -n contoso-apis --metadata-name "public-facing" --schema '{"type":"boolean", "title":"Public Facing"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

Enfin, répétez les mêmes étapes pour :

• Nom des métadonnées comme Vérification de la conformité
• Schéma avec type de propriété en tant que Chaîneet titre en tant que révision de conformité
• Affectations comme requis pour les API tandis que facultative pour Environnement et Déploiement

En exécutant la commande suivante :

az apic metadata create -g contoso -n contoso-apis --metadata-name "compliance-review" --schema '{"type":"string","title":"Compliance Review", "oneOf":[{"const":"Not Started","description":""},{"const":"In Progress","description":""},{"const":"Completed","description":""}]}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

Vous pouvez exécuter la commande suivante pour afficher la liste de toutes les métadonnées définies dans votre Centre d’API.

az apic metadata list -g <resource-group-name> -n <api-center-name> 

Remarque

Vous pouvez ajouter et modifier des propriétés dans le schéma à tout moment et les appliquer instantanément à toutes les API de votre Centre d’API

Remarque

Cette action n’est pas prise en charge pour l’instant dans VS Code. Créez-en un à l’aide d’Azure CLI ou du portail Azure.

Étape 3 : Ajouter des API à l’inventaire

L’organisation Contoso souhaite recommander des conférences techniques pour leurs équipes d’ingénierie dans le cadre de leur expérience interne. Nous allons ajouter une API conférence avec des conférenciers, des sessions et des sujets.

URL de l’API de conférence : https://bigconference.azurewebsites.net/

Pour les étapes suivantes, vous pouvez copier la définition OpenAPI à partir du site web ci-dessus et l’enregistrer sous forme de fichier JSON sur votre ordinateur local. Ou remplacez une définition d’API différente lors de l’ajout d’une API à l’inventaire.

1. Dans le portail, accédez à votre Centre API.

2. Dans le menu de gauche, sélectionnez Ressources > API > + Inscrire l’API.

3. Dans la page Inscrire l’API, ajoutez les informations requises suivantes pour l’API. Vous verrez l’approbateur d’API personnalisé, les propriétés de métadonnées *Public-facing et compliance-review que vous avez définies dans les étapes précédentes en bas de la page.

Pour afficher votre API créée, dans le menu de gauche, sélectionnez Ressources > API > API de conférence.

L’onglet Vue d’ensemble donne une vue de la configuration de l’API. Développez Détails pour afficher et modifier des informations supplémentaires telles que la version de l’API et les déploiements (nous n’avons pas de déploiements à ce stade).

Vous souhaitez normalement ajouter une définition d’API pour votre version de l’API et le Centre d’API prend en charge les formats de spécification de texte, notamment OpenAPI 2, OpenAPI 3 pour REST.

Pour ajouter une définition.

1. Dans le menu de gauche, sélectionnez Ressources > API > Sélectionner votre API (API de conférence).
2. Développez Détails et sélectionnez Versions.
3. Sélectionnez votre version (v1) et développez Détails.
4. Sous Détails, sélectionnez Définitions > Ajouter une définition.

Vous pouvez utiliser l’extension Centre d’API Azure pour Visual Studio Code pour inscrire une API dans votre instance d’API.

Étape 1 : Installer l’extension

Étape 2 : Ouvrez la palette de commandes, ‘Ctrl + Maj + P’ et tapez Centre d’API : Inscrire une API

Suivez les invites pour fournir les informations suivantes pour votre API :

Inscrire une API	Pas à pas
Sélectionner le service Centre d’API	Sélectionner votre instance Centre d’API
Titre de l’API	Saisissez le nom de votre API (API de conférence)
Type d’API	REST
Titre de la version de l’API	Saisissez un nom de version pour votre API (v1)
Cycle de vie des versions de l’API	Sélectionnez un cycle de vie dans la liste déroulante (Développement)
Titre de la définition de l’API	Saisissez un nom pour votre définition (définition d’API de conférence)
Nom de la spécification de l’API	Sélectionnez une spécification dans la liste déroulante (OpenAPI 2)
Sélectionner le fichier de définition d’API à importer	Parcourir et sélectionner le fichier de définition dans votre stockage

Actualisez l’onglet Extension du Centre d’API et votre API nouvellement créée s’affiche dans l’instance/ressource APIC correspondante.

Utilisez la commande suivante pour créer une API, en transférant :

• Exemple de groupe de ressources -g. Contoso
• Exemple de nom de service du Centre d’API -n. contoso-api-center
• Exemple de titre --title. API de conférence
• Exemple d’ID d’API --api-id. conference-api
• Exemple de type --type. REST

az apic api create -g contoso -n contoso-apis --title "Conference API" --api-id conference-api --type REST

Créez une version d’API à l’aide de la commande suivante, en transférant :

• Exemple de groupe de ressources -g. contoso
• Exemple de nom de service du Centre d’API -n. contoso-apis
• Exemple d’ID d’API --api-id. conference-api
• Exemple de titre --title. v1.2.2
• Exemple d’ID de version --version-id. 2024-07-03
• Exemple de phase de cycle de vie --lifecycle-stage. DC2015

az apic api version create -g contoso -n contoso-apis --api-id conference-api --title v1.2.2 --version-id 2024-07-03 --lifecycle-stage design

Vous pouvez également ajouter une définition d’API pour votre version d’API et le Centre d’API prend en charge les formats de spécification de texte, notamment OpenAPI 2, OpenAPI 3 pour REST.

Pour ajouter une définition, utilisez la commande suivante, en transférant :

• Exemple de groupe de ressources -g. contoso
• Exemple de nom de service du Centre d’API -n. contoso-apis
• Exemple d’ID d’API --api-id. conference-api
• Exemple d’ID de version --version-id. 2024-07-03
• Exemple de titre --title. OpenAPI
• Exemple d’ID de définition --definition-id. openapi

az apic api definition create -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --title OpenAPI --definition-id openapi 

Pour importer un fichier de définition OpenAPI à partir d’une URL, utilisez la commande az apic api definition import-specification à importer. Exemple : https://learn.microsoft.com/cli/azure/apic/api/definition?view=azure-cli-latest#az-apic-api-definition-import-specification-examples

az apic api definition import-specification -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --definition-id openapi --format "link" --value 'https://petstore3.swagger.io/api/v3/openapi.json' --specification '{"name":"openapi","version":"3.0.2"}'

Étape 4 : Ajouter des déploiements et des environnements

Environnements

Un environnement (développement, test, gestion intermédiaire ou production) représente un emplacement où un runtime d’API est déployé. Les ingénieurs de plateforme d’API chez Contoso définissent deux environnements – de test et de production, dans leur instance du Centre des API pour gérer et suivre différents runtimes d’API dans leur organisation.

Pour créer un environnement.

1. Dans le menu de gauche, sélectionnez Ressources > Environnements > + Nouvel environnement.

2. Ajoutez les informations suivantes.

3. Sélectionnez Créer.

4. Répétez les mêmes étapes pour l’Environnement de production.

   

Pour créer un environnement, exécutez la commande CLI suivante

az apic environment create -g contoso -n contoso-apis --title ContosoTesting --environment-id contosotesting --type testing

Répétez la même opération pour l’environnement de production

az apic environment create -g contoso -n contoso-apis-new --title ContosoProduction --environment-id contosoproduction --type production

Remarque

La création d’environnements n’est actuellement pas prise en charge sur VS Code. Utilisez l’interface de ligne de commande Azure ou l’option du portail Azure pour cette étape.

Déploiements

Un emplacement (adresse) unique pour que les utilisateurs interagissent avec votre API est fourni pour chaque runtime d’API dans un environnement donné. Cet emplacement est appelé déploiement, et une seule version d’API peut avoir deux déploiements, un déploiement intermédiaire et un déploiement de production.

Contoso dispose d’une API, l’API de conférence, que nous associions aux environnements que nous avons créés.

1. Dans le portail, accédez à votre Centre API.

2. Dans le menu de gauche, sélectionnez les API, puis sélectionnez une API, par exemple, l’API de Conférence.

3. Dans la page API de Conférence, développez Détails > Déploiements > + Ajouter un déploiement.

4. Ajoutez les informations suivantes :

   a. Sélectionnez Test Contoso dans la liste déroulante du champ Environnement.

   b. Pour la définition, cliquez sur Sélectionner, choisissez la version de l’API v1 dans la liste déroulante et sélectionnez la définition que vous avez ajoutée précédemment. Cliquez sur Sélectionner.

   c. Après avoir ajouté la définition, ajoutez une URL de runtime de base qui sera spécifique à l’API dans l’environnement sélectionné.

   

Pour créer un déploiement et l’associer à l’environnement que nous avons créé à l’étape ci-dessus, exécutez la commande CLI suivante

az apic api deployment create -g contoso-corporation -s contoso-api-center --deployment-id "v1-conference-api" --title "Conference OpenAPI 2" --description "Conference Demo API deployment." --api-id conference-api --environment-id "/workspaces/default/environments/contoso-testing" --definition-id "/workspaces/default/apis/conference-api/versions/v1/definitions/conference-openapi-2" --server '{"runtimeUri":["https://conferenceapi.azurewebsites.net/"]}'

Remarque

La création de déploiements n’est actuellement pas prise en charge sur VS Code. Utilisez l’interface de ligne de commande Azure ou l’option du portail Azure pour cette étape.