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

Une fois que votre API est prête et est utilisée par les développeurs, vous devez finir par lui apporter des modifications sans interrompre les appelants de l’API. Il est également utile d’informer les développeurs des modifications apportées.

Dans Gestion des API Azure, utilisez des révisions pour apporter des modifications d’API non cassantes afin de pouvoir modéliser et tester ces modifications de manière sécurisée. Quand vous êtes prêt, vous pouvez rendre actuelle une révision et remplacer votre API actuelle.

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

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.
• Suivez également le didacticiel 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. Dans la liste des API, sélectionnez API de conférence de démonstration (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. Indiquez une description pour votre nouvelle révision, ce qui vous aidera à vous souvenir à quoi elle sert.

7. Sélectionnez Créer.

8. 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 à appeler, jusqu’à ce que vous choisissiez d’actualiser une autre révision.

Apporter des modifications non cassantes à votre révision

1. Dans la liste des API, sélectionnez API de conférence de démonstration.

2. Sélectionnez l’onglet Conception situé près du haut de l’écran.

3. Notez que dans le sélecteur de révision (juste au-dessus de l’onglet Conception), Revision 2 est sélectionné.

   Conseil

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

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

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

6. Enregistrez votre nouvelle opération.

   

7. Vous avez modifié Revision 2. Utilisez le sélecteur de révision situé près du haut de la page pour revenir à Revision 1.

8. 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. Sélectionnez l’onglet Révisions dans le menu situé en haut de la page.

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

3. Sélectionnez Rendre actuel.

4. Cochez la case Publier sur le journal des modifications public de cette API, si vous souhaitez publier les remarques relatives à cette modification. Fournissez une description de votre modification destinée aux développeurs, par exemple : Test des révisions. Nouvelle opération « test » ajoutée.

5. Revision 2 est maintenant la révision actuelle.

   

Azure CLI

Pour commencer avec 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.

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

1. Exécutez la commande az apim 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 demo-conference-api --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 echo-api --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 demo-conference-api --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 demo-conference-api --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 avez essayé le portail des développeurs, vous pouvez passer en revue les modifications apportées à l’API et y changer le journal.

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 API de conférence de démonstration.
5. Notez que votre nouvelle opération test est désormais disponible.
6. Sélectionnez Journal des modifications en regard 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 cette URL pour accéder à la révision 2 de l’API Demo Conference :

https://apim-hello-world.azure-api.net/conf;rev=2/speakers

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

Étapes suivantes

Passez au tutoriel suivant :

Publier plusieurs versions de votre API