Tutoriel : Publier plusieurs versions de votre API

2025-06-23

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

Il existe des situations où il est difficile pour tous les consommateurs d’API d’utiliser la même version. Lorsque les consommateurs sont prêts à effectuer une mise à niveau vers une version plus récente, ils préfèrent une approche simple et compréhensible. Comme illustré dans ce tutoriel, Gestion des API Azure prend en charge l’exposition de plusieurs versions d’API pour répondre à ce besoin.

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 nouvelle version à une API existante
Choisir un schéma de version
Ajouter la version à un produit
Afficher la version dans le portail des développeurs

Prérequis

Découvrez la terminologie gestion des API Azure.
Terminez le démarrage rapide Créer une instance Azure API Management.
Suivez le tutoriel Importer et publier votre première API.

Ajouter une nouvelle version

Dans le portail Azure, accédez à votre instance APIM.
Dans le menu de gauche, dans la section API , sélectionnez API.
Recherchez Swagger Petstore - OpenAPI 3.0 dans la liste des API. Sélectionnez les points de suspension (...) à côté de Swagger Petstore - OpenAPI 3.0, puis sélectionnez Ajouter une version. Vous allez ajouter des valeurs à la fenêtre résultante dans la section suivante.

Conseil

Vous pouvez également activer les versions lorsque vous créez une API. Dans l’écran Ajouter l’API, sélectionnez Créer une version pour cette API ? .

Choisissez un schéma de contrôle de version

Dans Gestion des API, vous choisissez la façon dont les appelants spécifient la version de l’API en sélectionnant un schéma de contrôle de version : chemin d’accès, en-tête ou chaîne de requête. Dans l’exemple suivant, Path est utilisé comme schéma de contrôle de version.

Dans la fenêtre Créer une nouvelle API en tant que version, entrez les valeurs du tableau suivant. Sélectionnez ensuite Créer pour créer votre version.

Paramètre	valeur	Descriptif
Identificateur de version	v1	Indicateur de la version lié au schéma. Pour Chemin d’accès, le suffixe du chemin de l’URL de l’API.
Schéma de gestion de version	Chemin d’accès	Façon dont les appelants spécifient la version de l’API. Si vous sélectionnez En-tête ou chaîne de requête, entrez une autre valeur : le nom du paramètre d’en-tête ou de chaîne de requête. Un exemple d’utilisation est affiché.
Nom complet de la version de l’API	swagger-petstore-openapi-3-0-v1	Nom unique dans votre instance Gestion des API. Étant donné qu’une version est en fait une nouvelle API basée sur la révision d’une API, cette valeur est le nom de la nouvelle API.
Produits	Illimité (fourni dans certains niveaux de service)	Éventuellement, un ou plusieurs produits auxquels la version de l’API est associée. Pour publier l’API, vous devez l’associer à un produit. Vous pouvez également ajouter la version à un produit ultérieurement.

Après avoir créé la version, elle apparaît sous Swagger Petstore - OpenAPI 3.0 dans la liste des API. Vous voyez maintenant deux API : Original et v1 :

Remarque

Si vous ajoutez une version à une API non versionnée, une version d’origine est également créée automatiquement. Cette version répond sur l’URL par défaut. La version d’origine garantit que les appels des appelants existants fonctionnent toujours après l’ajout de la version. Si vous créez une API avec des versions activées au début, un original n’est pas créé.

Modifier une version

Après avoir ajouté la version, vous pouvez la modifier et la configurer en tant qu’API distincte de l’original. Les modifications apportées à une version n’affectent pas une autre version (par exemple, si vous ajoutez ou supprimez des opérations d’API, ou modifiez la spécification OpenAPI). Pour plus d’informations, consultez Modifier une API.

Ajouter la version à un produit

Pour que les appelants puissent voir la nouvelle version, il doit être ajouté à un produit. Si vous n’avez pas déjà ajouté la version à un produit, vous pouvez le faire à tout moment.

Pour ajouter la version à un produit :

Dans le portail Azure, accédez à votre instance APIM.
Sous API dans le volet gauche, sélectionnez Produits.
Sélectionnez le produit, puis sélectionnez LES API dans le volet gauche.
Sélectionnez + Ajouter.
Sélectionnez l’API.
Cliquez sur Sélectionner.

Utiliser des ensembles de versions

Lorsque vous créez plusieurs versions, le portail Azure crée un ensemble de versions, qui représente un ensemble de versions pour une API logique unique. Si vous sélectionnez le nom d’une API avec plusieurs versions, le portail affiche son jeu de versions. Vous pouvez personnaliser le nom et la description d’un ensemble de versions.

Vous pouvez interagir directement avec les ensembles de versions à l’aide de l’interface 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.

Pour afficher tous vos ensembles de versions, exécutez la commande az apim api versionset list :

az apim api versionset list --resource-group <resource-group-name> \
    --service-name <API-Management-service-name> --output table

Lorsque le portail Azure crée un ensemble de versions pour vous, il attribue un nom alphanumérique, qui apparaît dans la colonne Nom de la liste. Utilisez ce nom dans les autres commandes Azure CLI.

Pour afficher les détails d’un ensemble de versions, exécutez la commande az apim api versionset show :

az apim api versionset show --resource-group <resource-group-name> \
    --service-name <API-Management-service-name> --version-set-id <ID from the Name column>

Pour plus d’informations sur les ensembles de versions, consultez Versions dans Gestion des API Azure.

Afficher la version dans le portail des développeurs

Si vous utilisez le portail des développeurs, vous pouvez y voir les versions de l’API.

Sélectionnez Le portail des développeurs en haut de la fenêtre.
Sélectionnez API, puis Swagger Petstore.
Vous devez voir une liste déroulante qui répertorie plusieurs versions en regard du nom de l’API.
Sélectionnez v1.
Notez l’URL de la demande de la première opération de la liste. Il indique que le chemin d’accès de l’URL de l’API inclut v1.

Étape suivante

Accédez au tutoriel suivant :

Personnaliser le style des pages du portail des développeurs