Tutoriel : Publier plusieurs versions de votre API
S’APPLIQUE À : Tous les niveaux de Gestion des API
Il est parfois peu pratique que tous les appelants de votre API utilisent exactement la même version. Quand des appelants souhaitent effectuer une mise à niveau vers une version ultérieure, ils veulent une approche facile à comprendre. Comme indiqué dans ce tutoriel, il est possible de fournir plusieurs versions dans Gestion des API Azure.
Pour plus d’informations, consultez Versions et Révisions.
Dans ce tutoriel, vous allez apprendre à :
- Ajouter une nouvelle version à une API existante
- Choisir un schéma de version
- Ajouter la version à un produit
- Parcourir le portail des développeurs pour afficher la version
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 nouvelle version
- Dans le portail Azure, accédez à votre instance APIM.
- Sélectionnez API.
- Sélectionnez Swagger Petstore dans la liste des API.
- Sélectionnez le menu contextuel (...) en regard de Swagger Petstore.
- Sélectionnez Ajouter une version.
Conseil
Les versions peuvent également être activées quand 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 Azure, vous choisissez la manière dont les appelants spécifient la version de l’API en sélectionnant un schéma de gestion de versions : chemin d’accès, en-tête ou chaîne de requête. Dans l’exemple suivant, le chemin d’accès est utilisé comme schéma de gestion de versions.
Entrez les valeurs du tableau suivant. Sélectionnez ensuite Créer pour créer votre version.
| Paramètre | valeur | Description |
|---|---|---|
| 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 En-tête ou Chaîne de requête est sélectionné, 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-v1 | Nom unique dans votre instance Gestion des API. Une version étant de fait une nouvelle API basée sur la révision d’une API, ce paramètre 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. |
Une fois la version créée, elle apparaît sous Swagger Petstore dans la liste des API. Vous voyez maintenant deux API : Original et v1.
Remarque
Si vous ajoutez une version à une API sans version, une API Original est également automatiquement créée. Cette version répond sur l’URL par défaut. La création d’une version Original permet aux appelants existants de ne pas être interrompus par le processus d’ajout d’une version. Si vous créez une API avec des versions activées au démarrage, une API Original n’est pas créée.
Modifier une version
Lorsque vous avez ajouté la version, vous pouvez maintenant la modifier et la configurer en tant qu’API distincte de celle d’origine. Les modifications apportées à une version n’affectent pas l’autre. Par exemple, 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, elle doit être ajoutée à un produit. Si vous n’avez pas encore ajouté la version à un produit, vous pouvez le faire à tout moment.
Par exemple, pour ajouter la version au produit Illimité :
- Dans le portail Azure, accédez à votre instance APIM.
- Sélectionnez Produits>Illimité>API>+ Ajouter.
- Sélectionnez Swagger Petstore, version v1.
- 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. Sélectionnez le nom d’une API qui a plusieurs versions. Le portail Azure affiche son ensemble de versions. Vous pouvez personnaliser le nom et la description d’un ensemble virtuel.
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 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.
Pour afficher tous vos ensembles de versions, exécutez la commande az apim api versionset list :
az apim api versionset list --resource-group apim-hello-world-resource-group \
--service-name apim-hello-world --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 apim-hello-world-resource-group \
--service-name apim-hello-world --version-set-id 00000000000000000000000
Pour plus d’informations sur les ensembles de versions, consultez Versions dans Gestion des API Azure.
Parcourir le portail des développeurs pour afficher la version
Si vous avez essayé le portail des développeurs, vous pouvez y voir les versions de l’API.
- Sélectionnez Portail des développeurs dans le menu supérieur.
- Sélectionnez API, puis Swagger Petstore.
- Vous devez voir une liste déroulante avec plusieurs versions à côté 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.
Étapes suivantes
Dans ce didacticiel, vous avez appris à :
- Ajouter une nouvelle version à une API existante
- Choisir un schéma de version
- Ajouter la version à un produit
- Parcourir le portail des développeurs pour afficher la version
Passez au tutoriel suivant :