Mettez à jour la version de l’API Azure Key Vault que vous utilisez

Azure Key Vault utilise des API versionnées. Si vos applications, scripts ou modèles d’infrastructure appellent une ancienne version d’API, vous risquez de manquer des fonctionnalités plus récentes, d’utiliser un comportement modifié dans une version ultérieure ou de dépendre d’une version qui n’est plus recommandée. Cet article explique comment déterminer la version de l’API que vous utilisez et comment passer à une version actuelle prise en charge.

Important

Toutes les versions d’API du plan de contrôle de Key Vault antérieures à 2026-02-01 seront mises hors service le 27 février 2027. Après cette date, vos coffres de clés continuent d’exister, mais vous pouvez les gérer uniquement à l’aide de la version 2026-02-01 ou ultérieure de l’API du plan de contrôle. Il n’existe aucune exception ni extension à cette date. Cette mise hors service n’affecte pas les API du plan de données (les API utilisées pour utiliser des clés, des secrets et des certificats). Pour plus d’informations, consultez Planifier Azure RBAC comme modèle de contrôle d’accès par défaut dans Key Vault.

Azure Key Vault a deux surfaces d’API indépendantes, chacune avec ses propres versions :

Surface d’API Ce qu’il gère Schéma de version Exemple de point de terminaison
Plan de contrôle (gestion) La ressource Key Vault elle-même : créer, mettre à jour et supprimer des coffres de clés, et configurer des propriétés telles que le SKU, les règles de réseau et le contrôle d’accès. Basé sur des dates ({YYYY}-{MM}-{DD}) https://management.azure.com
Plan de données Objets à l’intérieur d’un coffre : clés, secrets et certificats et opérations de chiffrement. Basé sur des dates ({YYYY}-{MM}-{DD}) https://<vault-name>.vault.azure.net

Les deux surfaces ont des pratiques de contrôle de version et de cycle de vie différentes. La mise à jour ne met pas à jour l’autre. Passez en revue les deux si votre charge de travail utilise les deux.

Les versions de l’API du plan de contrôle peuvent être supprimées, comme décrit précédemment dans cet article.

Les versions d’API de plan de données en préversion peuvent être déconseillées. N’utilisez donc pas d’aperçus en production, sauf si vous acceptez ce cycle de vie. Pour connaître les versions d’API de plan de données prises en charge, consultez la référence de l’API REST Azure Key Vault.

Cet article se concentre sur l’identification et la mise à jour des versions d’API. La mise à jour de la version d’API du plan de contrôle n’exige pas de faire migrer un coffre de clés existant des stratégies d’accès vers RBAC Azure. Si vous souhaitez migrer le contrôle d’accès, consultez Migrer vers Azure RBAC à partir de stratégies d’accès. Pour connaître le comportement par défaut Azure RBAC introduit pour les nouveaux coffres de clés dans la version 2026-02-01 de l’API et versions ultérieures, consultez Planifier Azure RBAC comme modèle de contrôle d’accès par défaut dans Key Vault.

Pourquoi passer à une version actuelle de l’API

  • Utilisez les fonctionnalités prises en charge. Les versions d’API plus récentes peuvent ajouter des fonctionnalités, un comportement correct ou prendre en charge de nouvelles fonctionnalités de service.
  • Maintenir les charges de travail de production stables. Utilisez une version d’API stable actuelle pour les charges de travail de production. Les versions préliminaires de l’API sont destinées à l’évaluation et aux tests anticipés, et les contrats de niveau de service (SLA) du support Azure peuvent ne pas les couvrir. Les versions en préversion peuvent être déconseillées.
  • Conservez les outils et les bibliothèques compatibles. Azure CLI, Azure PowerShell, sdk, modèles et portail peuvent utiliser différentes versions d’API. La mise à jour de la version d’un client ne met pas à jour les autres.

Pour connaître les versions actuelles du plan de contrôle, consultez les versions d’API de plan de contrôle prises en charge. Pour connaître les versions de plan de données prises en charge, consultez la référence de l’API REST Azure Key Vault.

Déterminer la version de l’API que vous utilisez

Vous spécifiez la version de l’API différemment en fonction de la façon dont vous appelez Key Vault. Vérifiez chaque surface utilisée par votre charge de travail.

Plan de contrôle (gestion)

  • API REST : La version correspond au paramètre de la chaîne de requête api-version dans les requêtes vers https://management.azure.com, par exemple ?api-version=<control-plane-version>.
  • Modèles ARM, Bicep et Terraform : la version correspond à la propriété apiVersion de chaque ressource Microsoft.KeyVault/vaults. Dans Bicep, il fait partie de la déclaration de type de ressource, par exemple resource kv 'Microsoft.KeyVault/vaults@2026-02-01'.
  • SDK de gestion du plan de contrôle : la version du package peut déterminer les versions d’API prises en charge par un SDK, mais la version du package à elle seule n’identifie pas toujours la version d’API utilisée par une requête. Consultez les notes de publication du package et les informations de référence sur l'API (par exemple, pour Azure.ResourceManager.KeyVault ou azure-mgmt-keyvault) et comparez-les à la version du package dans le manifeste de dépendance de votre projet. Pour connaître les références d’API par langage, consultez Azure Key Vault bibliothèques clientes.
  • Azure CLI et Azure PowerShell : la version de votre Azure CLI ou Az module détermine la version de l’API. Vérifiez votre version installée avec az version ou Get-InstalledModule -Name Az.
  • Azure portail : le portail sélectionne la version de l’API du plan de contrôle pour ses demandes. Vous ne pouvez pas définir cette version directement. Le portail peut utiliser une version d’API différente de vos modèles, scripts ou kits sdk. N’utilisez donc pas le comportement du portail pour déterminer la version utilisée par votre automatisation.
  • Azure Cloud Shell : Cloud Shell utilise les versions actuelles Azure CLI et Azure PowerShell. Si vous exécutez des scripts dans Cloud Shell, vérifiez qu'ils sont compatibles avec la version de l'API de plan de contrôle actuellement prise en charge.

Plan de données

  • API REST : la version correspond au paramètre de chaîne de requête api-version dans les requêtes envoyées au point de terminaison de votre coffre, par exemple GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>.
  • Sdk de plan de données : la version du package peut déterminer les versions d’API prises en charge par un KIT de développement logiciel (SDK), mais la version du package seule n’identifie pas toujours la version de l’API utilisée par une demande. Vérifiez les notes de publication du package et les informations de référence sur l'API (par exemple, pour Azure.Security.KeyVault.Secrets, Azure.Security.KeyVault.Keysou Azure.Security.KeyVault.Certificates) et comparez-les à la version du package dans le manifeste de dépendance de votre projet. Pour connaître les références d’API par langage, consultez Azure Key Vault bibliothèques clientes.

Mettre à jour votre version d’API

Mettre à jour la version de l’API du plan de contrôle

  1. Mettez à jour la version de l’API dans vos modèles et appels REST. Définissez apiVersion (ARM, Bicep, Terraform) ou api-version comme paramètre de chaîne de requête (REST) sur une version de plan de contrôle actuellement prise en charge dans toutes les définitions Microsoft.KeyVault/vaults et toutes les requêtes de gestion.

  2. Mettez à jour vos kits SDK de gestion du plan de contrôle. Consultez les notes de publication du package et les informations de référence sur l’API pour la version du package qui prend en charge la version de l’API du plan de contrôle que vous avez sélectionnée. Pour connaître les références d’API par langue et les versions de package qui prennent en charge la version actuelle du plan de contrôle Key Vault, consultez Azure Key Vault bibliothèques clientes et versions du Kit de développement logiciel (SDK) du plan de contrôle.

    Note

    La mise à jour d’un SDK de gestion de plan de contrôle ne met pas à jour les kits SDK de plan de données. Mettez à jour chaque KIT SDK séparément si votre application utilise les deux surfaces d’API.

  3. Mettez à jour Azure CLI et Azure PowerShell. Les versions d’outils plus récentes appellent des versions d’API plus récentes.

    Mettez à jour Azure CLI vers la dernière version. Pour plus d’informations, consultez Comment mettre à jour Azure CLI.

  1. Passez en revue les modifications de comportement avant de déployer. Lisez le journal des modifications et la spécification de la version de l’API avant de déployer. La version 2026-02-01 de l’API et les suivantes modifient le modèle de contrôle d’accès par défaut uniquement pour les nouveaux coffres de clés. Pour plus d’informations, consultez Planifier Azure RBAC comme modèle de contrôle d’accès par défaut dans Key Vault.

Mettre à jour la version de l’API du plan de données

  1. Mettez à jour la version de l’API dans vos appels REST. Définissez le paramètre de chaîne de requête api-version sur une version du plan de données actuellement prise en charge indiquée dans la référence de l’API REST Azure Key Vault.

  2. Mettez à jour vos kits SDK de plan de données. Mettez à niveau les Azure.Security.KeyVault.* packages (ou équivalents pour votre langue) vers une version stable actuelle. Consultez les notes de publication du package et la référence d’API pour déterminer les versions de l’API de plan de données prises en charge par le package. Pour connaître les références d’API et les liens de package par langue, consultez Azure Key Vault bibliothèques clientes.

Les versions stables de l’API du plan de données ne sont pas affectées par la mise hors service du plan de contrôle actuelle. Si vous utilisez une API de plan de données en préversion, passez en revue les annonces de service et la référence de l’API pour son cycle de vie.

Pour plus d’informations sur l’appel de l’API REST du plan de données, consultez Authentification, demandes et réponses et référence de l’API REST Azure Key Vault.

Contenu connexe

  • Dernière mise à jour :