Tutoriel : Utiliser des révisions pour apporter en toute sécurité des modifications d’API non cassantes

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

Lorsque votre API est utilisée par les développeurs, vous devez éventuellement apporter des modifications à cette API sans perturber les appelants de votre API. Il est également utile d’informer les développeurs des modifications apportées.

Dans Azure API Management, utilisez des révisions pour effectuer des modifications d’API non perturbatrices. Vous pouvez modéliser et tester les modifications en toute sécurité. Lorsque vous êtes prêt, effectuez votre révision actuelle et remplacez l’API actuelle.

Pour plus d’informations, consultez Versions et révisions.

Conseil

Les équipes d’API peuvent utiliser cette fonctionnalité dans des espaces de travail. Les espaces de travail fournissent un accès d’administration isolé aux API et à leurs propres environnements d’exécution d’API.

Dans ce tutoriel, vous allez apprendre à :

• Ajouter une révision
• Apporter des modifications non cassantes à votre révision
• Rendre cette révision actuelle et ajouter une entrée au journal des modifications
• Parcourir le portail des développeurs pour voir les modifications et le journal des modifications
• Accéder à une révision d’API

Prérequis

• Apprenez la terminologie relative à Gestion des API Azure.
• Suivez le guide de démarrage rapide suivant : Créer une instance du service Gestion des API Azure.
• Effectuez toutes les étapes du tutoriel suivant : Importer et publier votre première API.

Ajouter une révision

1. Connectez-vous au portail Azure et accédez à votre instance de Gestion des API.

2. Dans le menu de gauche, sous API, sélectionnez API.

3. Sélectionnez Swagger Petstore dans la liste des API ou une AUTRE API à laquelle vous souhaitez ajouter des révisions.

4. Sélectionnez l’onglet Révisions.

5. Sélectionnez + Ajouter une révision.

   

   Conseil

   Vous pouvez également sélectionner Ajouter une révision dans le menu contextuel ( ... ) de l’API.

6. Fournissez une description de votre nouvelle version pour vous rappeler à quoi elle sert.

7. Sélectionnez Créer.

   Vous venez de créer une nouvelle révision.

   Notes

   Votre API d’origine reste dans Revision 1. Il s’agit de la révision que vos utilisateurs continuent d’appeler, jusqu’à ce que vous choisissiez d’effectuer une autre révision actuelle.

Apporter des modifications non cassantes à votre révision

1. Sélectionnez Swagger Petstore dans la liste des API.

2. Sélectionnez Création en haut de l’écran.

   Le sélecteur de révision au-dessus de l’onglet Création affiche la révision 2 , comme actuellement sélectionné.

   Conseil

   Utilisez le sélecteur de révision pour basculer entre les révisions sur lesquelles vous souhaitez travailler.

3. Sélectionnez + Ajouter une opération.

4. Définissez votre nouvelle opération sur POST, puis les champs Nom d’affichage, Nom et URL de l’opération sur la valeur test.

5. Enregistrez votre nouvelle opération.

   

   Vous avez modifié Revision 2.

6. Utilisez le sélecteur de révision situé près du haut de la page pour revenir à Revision 1.

   Notez que votre nouvelle opération n’apparaît pas dans Revision 1.

Rendre cette révision actuelle et ajouter une entrée au journal des modifications

Portail

1. Dans le menu situé en haut de la page, sélectionnez Révisions.

2. Ouvrez le menu contextuel (...) pour Revision 2.

3. Sélectionnez Rendre actuel.

4. Si vous souhaitez publier des notes sur cette modification, sélectionnez Publier dans le journal des modifications publiques pour cette API. Fournissez une description de votre modification destinée aux développeurs, par exemple : Test des révisions. Nouvelle opération « test » ajoutée.

   Revision 2 est maintenant la révision actuelle.

   

Azure CLI

Pour commencer avec Azure CLI :

• Utilisez l’environnement Bash dans Azure Cloud Shell. Pour obtenir plus d’informations, consultez Démarrage d’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 obtenir d’autres options de connexion, consultez S’authentifier auprès d’Azure à l’aide d’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 et gérer 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.

Utilisez cette procédure pour créer et mettre à jour une version.

1. Exécutez la commande az api list pour voir vos ID d’API :

   az apim api list --resource-group apim-hello-word-resource-group \
       --service-name apim-hello-world --output table
   

   L’ID d’API à utiliser dans la commande suivante est la valeur Name. La révision de l’API se trouve dans la colonne ApiRevision.

2. Pour créer la version, avec une note de publication, exécutez la commande az apim api release create :

   az apim api release create --resource-group apim-hello-word-resource-group \
       --api-id swagger-petstore --api-revision 2 --service-name apim-hello-world \
       --notes 'Testing revisions. Added new "test" operation.'
   

   La révision que vous publiez devient la révision actuelle.

3. Pour voir vos versions, utilisez la commande az apim api release list :

   az apim api release list --resource-group apim-hello-word-resource-group \
       --api-id swagger-petstore --service-name apim-hello-world --output table
   

   Les notes que vous spécifiez s’affichent dans le journal des modifications. Vous pouvez les voir dans la sortie de la commande précédente.

4. Lorsque vous créez une version, le paramètre --notes est facultatif. Vous pouvez ajouter ou modifier ultérieurement les notes à l’aide de la commande az apim api release update :

   az apim api release update --resource-group apim-hello-word-resource-group \
       --api-id swagger-petstore --release-id 00000000000000000000000000000000 \
       --service-name apim-hello-world --notes "Revised notes."
   

   Utilisez la valeur de la colonne Name pour l’ID de version.

Vous pouvez supprimer n’importe quelle version en exécutant la commande az apim api release delete :

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id swagger-petstore --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

Parcourir le portail des développeurs pour voir les modifications et le journal des modifications

Si vous essayez le portail des développeurs, vous pouvez consulter les modifications de l’API et le journal des modifications là-bas.

1. Dans le portail Azure, accédez à votre instance APIM.
2. Dans le menu de gauche, sous API, sélectionnez API.
3. Sélectionnez Portail des développeurs dans le menu supérieur.
4. Dans le portail des développeurs, sélectionnez API, puis Swagger Petstore.
5. Notez que votre nouvelle opération test est désormais disponible.
6. Sélectionnez Modifier le journal près du nom de l’API.
7. Notez que l’entrée du journal des modifications apparaît dans cette liste.

Accéder à une révision d’API

Chaque révision de votre API est accessible à l’aide d’une URL spécialement formée. Ajoutez ;rev={revisionNumber} à la fin de votre chemin d’URL d’API, avant la chaîne de requête, pour accéder à une révision spécifique de cette API. Par exemple, vous pouvez utiliser une URL semblable à la suivante pour accéder à la révision 2 de l’API Swagger Petstore :

https://apim-hello-world.azure-api.net/store/pet/1;rev=2/

Vous trouverez les chemins d’URL des révisions de votre API sous l’onglet Révisions sur le Portail Azure.

Conseil

Vous pouvez accéder à la révision actuelle de votre API à l’aide du chemin d’accès de l’API sans la chaîne ;rev, en plus de l’URL complète qui ajoute ;rev={revisionNumber} à votre chemin d’API.

Résumé

Dans ce didacticiel, vous avez appris à :

• Ajouter une révision
• Apporter des modifications non cassantes à votre révision
• Rendre cette révision actuelle et ajouter une entrée au journal des modifications
• Parcourir le portail des développeurs pour voir les modifications et le journal des modifications
• Accéder à une révision d’API

Étape suivante

Passez au tutoriel suivant :

Publier plusieurs versions de votre API