Politique de versionnement pour les services Azure, les SDK et les outils CLI
La plupart des services Azure vous permettent de contrôler et de gérer par programmation leurs ressources avec des API REST. Les services évoluent via de nouvelles versions publiées de leurs API avec différents contrats qui ajoutent de nouvelles fonctionnalités et/ou modifient leurs comportements.
Cet article décrit la stratégie que les équipes azure service, SDK et CLI utilisent pour la gestion des versions des API REST Azure. Bien que les équipes Azure effectuent tous les efforts nécessaires pour respecter cette stratégie, les écarts peuvent parfois se produire.
Contrôle des versions du service
Chaque version publiée d’une API est identifiée par une valeur de date au YYYY-MM-DD format appelé api-version. Les versions plus récentes ont des dates ultérieures.
Toutes les opérations d’API nécessitent que les clients spécifient une version d’API valide pour le service via le api-version paramètre de chaîne de requête dans l’URL. Par exemple : https://management.azure.com/subscriptions?api-version=2020-01-01. Les kits de développement logiciel (SDK) et les outils clients incluent automatiquement la api-version valeur. Pour plus d’informations, consultez la section Des kits sdk client et des versions de service plus loin dans cet article.
Dans la plupart des scénarios, un client de service doit uniquement interagir avec une seule version d’un service pour accéder à toutes les fonctionnalités dont il a besoin.
Les versions de service stables restent généralement disponibles et prises en charge pendant de nombreuses années, même lorsque les versions plus récentes deviennent disponibles. Dans la plupart des cas, la seule fois où vous devez adopter une nouvelle version de service dans le code existant consiste à tirer parti des nouvelles fonctionnalités.
Versions stables
La plupart des versions de service publiées sont des versions stables. Les versions stables sont compatibles descendantes, ce qui signifie que tout code que vous écrivez qui s’appuie sur une version d’un service peut adopter une version stable plus récente sans nécessiter de modifications de code pour maintenir l’exactitude ou les fonctionnalités existantes.
Versions de modification cassants
Une version de modification cassant d’un service n’est pas rétrocompatible. L’adoption d’une version de modification cassante dans le code client existant peut nécessiter des modifications de code pour s’assurer que le client se comporte exactement comme il l’a fait lors du ciblage de la version précédente.
Les versions de modification cassants sont rares, annoncées via la documentation et sont généralement précédées de la publication d’une version préliminaire. La publication d’une version de modification cassant peut entraîner la mise hors service éventuelle des versions stables existantes, qui reste disponible pendant au moins trois ans après les versions de modification cassants. Pour les changements cassants publiés en raison de problèmes de sécurité ou de conformité, les versions de service stables existantes peuvent rester disponibles pendant un an ou moins en fonction de la gravité du problème.
En raison de l’innovation rapide et des développements dans l’IA, les services pilotés par l’IA peuvent avoir une disponibilité minimale réduite d’un an. Chaque service publiera sa stratégie de modification cassant.
Tout service Azure dépendant d’un composant autre que Microsoft peut réduire sa stratégie de support pour qu’elle corresponde à celle de la stratégie du composant. Toute modification cassant due à cette modification est liée à la stratégie du fournisseur du composant montrant la date à laquelle le composant n’est plus pris en charge.
Préversions
Parfois, Microsoft publie une préversion d’un service pour recueillir des commentaires sur les modifications proposées et les nouvelles fonctionnalités. Les versions de service en préversion sont identifiées avec le suffixe -preview dans leur api-version ( par exemple, 2022-07-07-preview.
À moins d’introduire explicitement une modification cassant de la version stable précédente, les nouvelles versions d’évaluation incluent toutes les fonctionnalités de la version stable la plus récente et ajoutent de nouvelles fonctionnalités en préversion. Toutefois, entre les versions préliminaires, un service peut interrompre l’une des fonctionnalités d’aperçu nouvellement ajoutées.
Les préversions ne sont pas destinées à une utilisation à long terme. Chaque fois qu’une nouvelle version stable ou préliminaire d’un service devient disponible, les versions en préversion existantes peuvent devenir indisponibles dès 90 jours après la disponibilité de la nouvelle version. Utilisez les versions en préversion uniquement dans les situations où vous développez activement sur de nouvelles fonctionnalités de service et que vous êtes prêt à adopter une nouvelle version sans préversion peu après sa publication. Si certaines fonctionnalités d’une préversion sont publiées dans une nouvelle version stable, les fonctionnalités restantes toujours en préversion seront généralement publiées dans une nouvelle version d’évaluation.
Kits de développement logiciel (SDK) clients et versions de service
Les kits de développement logiciel (SDK) Azure visent à éliminer le contrôle de version du service en tant que préoccupation lors de l’écriture de code. Chaque KIT SDK est composé de bibliothèques clientes, une pour chaque service, et chaque version de bibliothèque cliente cible une seule version du service sur laquelle elle s’appuie.
Lorsque vous utilisez un SDK pour accéder à un service Azure, tirer parti des nouvelles versions et fonctionnalités nécessite généralement la mise à niveau de la version de bibliothèque cliente utilisée par l’application. De nouvelles versions stables des services sont accompagnées de nouvelles versions point des bibliothèques clientes. Pour les nouvelles versions de modification cassants, les nouvelles bibliothèques clientes sont publiées en tant que versions de version point ou versions principales. Le type de mise en production dépend de la nature du changement du service et de la façon dont la bibliothèque est en mesure de l’adapter. Seules les bibliothèques clientes bêta utilisent des versions préliminaires du service.
Les bibliothèques clientes du SDK prennent en charge la substitution manuelle de la version du service. La substitution de la version de service par défaut d’une bibliothèque cliente est un scénario avancé et peut entraîner un comportement inattendu. Si vous utilisez cette fonctionnalité, testez soigneusement votre application pour vous assurer qu’elle fonctionne comme vous le souhaitez.
Outils en ligne de commande Azure
Comme pour les Kits de développement logiciel (SDK), les outils en ligne de commande Azure (y compris Azure CLI et Azure PowerShell) sont conçus pour permettre l’utilisation des services de gestion Azure sans tenir compte des versions. L’accès aux nouvelles fonctionnalités de service nécessite souvent une nouvelle version d’un outil. Les nouvelles versions d’outils compatibles descendantes sont publiées mensuellement. Les versions avec des modifications cassants sont publiées environ deux fois par an, ou si nécessaire pour résoudre les problèmes de sécurité critiques.
Les outils en ligne de commande Azure peuvent parfois exposer des fonctionnalités en préversion. Ces commandes sont marquées avec une Preview étiquette et affichent un avertissement indiquant une prise en charge limitée et des modifications potentielles dans les futures versions d’outils.