Versions dans Gestion des API Azure

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

Les versions vous permettent de présenter des groupes d’API associées à vos développeurs. Vous pouvez utiliser des versions pour traiter en toute sécurité les changements cassants dans votre API. Les clients peuvent choisir d’utiliser la nouvelle version de votre API lorsqu’ils sont prêts, tandis que les clients existants continuent d’utiliser une version antérieure. Les versions sont différenciées via un identificateur de version (qui est n’importe quelle valeur de chaîne que vous choisissez), et un schéma de contrôle de version permet aux clients d’identifier la version d’une API qu’ils souhaitent utiliser. Cet article explique comment utiliser des versions dans Gestion des API.

Dans la plupart des cas, chaque version d’API peut être considérée comme sa propre API indépendante. Deux versions d’API distinctes peuvent avoir différents ensembles d’opérations et des stratégies spécifiques.

Avec les versions, vous pouvez :

• Publiez simultanément plusieurs versions de votre API.
• Utilisez un chemin d’accès, une chaîne de requête ou un en-tête pour différencier les versions.
• Utilisez n’importe quelle valeur de chaîne pour identifier votre version. Il peut s’agir d’un nombre, d’une date ou d’un nom.
• Affichez vos versions d’API regroupées sur le portail des développeurs.
• Créez une nouvelle version d’une API existante (non versionnée) sans affecter les clients existants.

Prise en main des versions en effectuant une procédure pas à pas.

Schémas de contrôle de version

Différents développeurs d’API ont des exigences différentes pour le contrôle de version. Gestion des API Azure ne prescrit pas une approche unique du contrôle de version, mais fournit plutôt plusieurs options.

Contrôle de version basé sur le chemin d’accès

Lorsque le schéma de contrôle de version du chemin d’accès est utilisé, l’identificateur de version doit être inclus dans le chemin d’URL pour toutes les demandes d’API.

Par exemple, https://apis.contoso.com/products/v1 et https://apis.contoso.com/products/v2 peut faire référence à la même products API, mais aux versions v1 et v2.

Le format d’une URL de requête d’API lorsque vous utilisez le contrôle de version basé sur le chemin est https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Versionnage basé sur l’en-tête

Lorsque le schéma de contrôle de version d’en-tête est utilisé, l’identificateur de version doit être inclus dans un en-tête de requête HTTP pour toutes les demandes d’API. Vous pouvez spécifier le nom de l’en-tête de requête HTTP.

Par exemple, vous pouvez créer un en-tête personnalisé nommé Api-Version, et les clients peuvent spécifier v1 ou v2 dans la valeur de cet en-tête.

Contrôle de version basé sur une chaîne de requête

Lorsque le schéma de contrôle de version de chaîne de requête est utilisé, l’identificateur de version doit être inclus dans un paramètre de chaîne de requête pour toutes les demandes d’API. Vous pouvez spécifier le nom du paramètre de chaîne de requête.

Le format d’une URL de requête d’API lorsque vous utilisez le contrôle de version basé sur des chaînes de requête est https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

Par exemple, https://apis.contoso.com/products?api-version=v1 et https://apis.contoso.com/products?api-version=v2 peut faire référence à la même products API, mais aux versions v1 et v2.

Remarque

Les paramètres de requête ne sont pas autorisés dans la servers propriété d’une spécification OpenAPI. Si vous exportez une spécification OpenAPI à partir d’une version d’API, une chaîne de requête n’apparaît pas dans l’URL du serveur.

Versions d’origine

Si vous ajoutez une version à une API non versionnée, une Original version est automatiquement créée et répond sur l’URL par défaut, sans identificateur de version spécifié. La Original version garantit que tous les appelants existants ne sont pas affectés par le processus d’ajout d’une version. Si vous créez une API avec des versions activées au début, une Original version n’est pas créée.

Représentation des versions

Gestion des API gère une ressource appelée ensemble de versions, qui représente un ensemble de versions pour une API logique unique. Un jeu de versions contient le nom complet de l’API versionnée et le schéma de contrôle de version utilisé pour diriger les requêtes vers les versions spécifiées.

Chaque version d’une API est conservée en tant que ressource d’API et associée à un jeu de versions. Un jeu de versions peut contenir des API avec différentes opérations ou stratégies. Vous pouvez apporter des modifications significatives entre les versions d’un ensemble.

Le portail Azure crée des ensembles de versions pour vous. Vous pouvez modifier le nom et la description d’un ensemble de versions dans le portail Azure.

Un jeu de versions est automatiquement supprimé lorsque la version finale est supprimée.

Vous pouvez afficher et gérer directement les ensembles de versions à l’aide d’Azure CLI, d’Azure PowerShell, de modèles Resource Manager ou de l’API Azure Resource Manager.

Remarque

Toutes les versions d’un jeu de versions ont le même schéma de versionnement. Elle est basée sur le schéma de contrôle de version utilisé lors de la première ajout d’une version à une API.

Migration d’une API non versionnée vers une API avec version

Lorsque vous utilisez le portail Azure pour activer le contrôle de version sur une API existante, les modifications suivantes sont apportées à vos ressources Gestion des API :

• Un jeu de versions est créé.
• La version existante est conservée et configurée comme version de l’APIOriginal. L’API est liée au jeu de versions, mais un identificateur de version n’a pas besoin d’être spécifié.
• La nouvelle version est créée en tant que nouvelle API et est liée à l'ensemble de versions. Un schéma et un identificateur de contrôle de version doivent être utilisés pour accéder à la nouvelle API.

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 règle générale, les versions sont utilisées pour séparer les versions d’API qui ont des modifications cassantes, et les révisions peuvent être utilisées pour les modifications mineures et non cassantes apportées à une API.

Si vous constatez que votre révision a des changements cassants ou que vous souhaitez transformer formellement votre révision en version bêta/test, vous pouvez créer une version à partir d’une révision. Dans le portail Azure, sélectionnez Créer une version à partir de cette révision dans le menu contextuel de révision (...) sous l’onglet Révisions .

Portail des développeurs

Le portail des développeurs répertorie chaque version d’une API séparément :

Dans les détails d’une API, vous pouvez également voir la liste de toutes les versions de l’API. Une Original version s’affiche sans identificateur de version :

Conseil / Astuce

Vous devez ajouter des versions d’API à un produit pour les rendre visibles dans le portail des développeurs.