Révisions dans Gestion des API Azure

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

Les révisions vous permettent d’apporter des modifications à vos API de manière contrôlée et sécurisée. Lorsque vous souhaitez apporter des modifications, créez une nouvelle révision. Vous pouvez ensuite modifier et tester votre API sans déranger vos consommateurs d’API. Lorsque vous êtes prêt, vous mettez votre révision à jour. En même temps, vous pouvez éventuellement publier une entrée dans le journal des modifications pour que vos consommateurs d’API restent à jour avec les modifications que vous avez apportées. Le journal des modifications est publié sur votre portail des développeurs.

Note

Le portail des développeurs n’est pas disponible dans le niveau Consommation.

Avec les révisions, vous pouvez :

• Apportez en toute sécurité des modifications à vos définitions et stratégies d’API, sans déranger votre API de production.
• Essayez les modifications avant de les publier.
• Documentez les modifications que vous apportez, afin que vos développeurs puissent comprendre ce qui est nouveau.
• Procéder à une restauration en cas de problèmes.

Prise en main des révisions en suivant notre procédure pas à pas.

Accéder à des versions précises

Chaque révision de votre API est accessible à l’aide d’une URL spécialement formée. Ajoutez ;rev={revisionNumber} à la fin de votre URL d’API, mais 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 3 de l’API customers :

https://apis.contoso.com/customers;rev=3/leads?customerId=123

Par défaut, chaque révision a les mêmes paramètres de sécurité que la révision actuelle. Vous pouvez modifier délibérément les stratégies d’une révision spécifique si vous souhaitez appliquer une sécurité différente à chaque révision. Par exemple, vous pouvez ajouter une stratégie de filtrage IP pour empêcher les appelants externes d’accéder à une révision qui est toujours en cours de développement.

Note

;rev={id} doit être ajouté à l’id d’api, et non au chemin d'accès uri.

Révision actuelle

Une révision unique peut être définie comme révision actuelle . Cette révision est celle utilisée pour toutes les demandes d’API qui ne spécifient pas de numéro de révision explicite dans l’URL. Vous pouvez revenir à une révision précédente en définissant cette révision comme étant en cours.

Vous pouvez définir une révision comme étant en cours à l’aide du portail Azure. Si vous utilisez PowerShell, vous pouvez utiliser le cmdlet New-AzApiManagementApiRelease.

Descriptions de révision

Lorsque vous créez une révision, vous pouvez définir une description à des fins de suivi. Les descriptions ne sont pas affichées aux utilisateurs de votre API.

Lorsque vous définissez une révision en tant que version actuelle, vous pouvez également spécifier une note de journal des modifications publique. Le journal des modifications est inclus dans le portail des développeurs pour que vos utilisateurs d’API puissent les afficher. Vous pouvez modifier votre note de journal des modifications à l’aide de l’applet Update-AzApiManagementApiRelease de commande PowerShell.

Caution

Si vous modifiez une révision non actuelle d’une API, vous ne pouvez pas modifier les propriétés suivantes :

• Nom
• Type
• Descriptif
• Abonnement requis
• Version de l’API
• Description de la version de l’API
• Chemin
• Protocoles

Ces propriétés ne peuvent être modifiées que dans la révision actuelle. Si vos modifications modifient l’une de ces propriétés dans une révision non actuelle, le message Can't change property for non-current revision d’erreur s’affiche.

Effectuer une révision hors connexion

Une révision peut être mise hors connexion, ce qui rend inaccessible aux appelants même s’ils tentent d’accéder à la révision via son URL. Vous pouvez marquer une révision comme hors connexion à l’aide du portail Azure.

Note

Nous vous suggérons de mettre hors connexion les révisions lorsque vous ne les utilisez pas pour les tester.

Versions et révisions

Les versions et les révisions sont des fonctionnalités distinctes. Chaque version peut avoir plusieurs révisions, comme une API non versionnée. Vous pouvez utiliser des révisions sans utiliser de versions, ou d’une autre façon. En général, les versions sont utilisées pour séparer les versions d’API avec des modifications disruptives, tandis que les révisions peuvent être utilisées pour les modifications mineures et non disruptives apportées à une API.

Si votre révision a des modifications radicales ou si vous souhaitez transformer formellement votre révision en version bêta, vous pouvez créer une version à partir de votre révision. À l’aide du portail Azure, sélectionnez « Créer une version à partir de révision » dans le menu contextuel révision sous l’onglet Révisions.