更新使用的 Azure 密钥保管库 API 版本

Azure 密钥保管库使用版本控制 API。 如果应用程序、脚本或基础结构模板调用较旧的 API 版本，则可能错过较新的功能、使用在更高版本中更改的行为，或依赖于不再推荐的版本。 本文介绍如何确定所使用的 API 版本以及如何移动到当前受支持的版本。

Azure 密钥保管库有两个独立的 API 图面，每个图面都有其自己的版本：

这两个图面具有不同的版本控制和生命周期做法。 更新一个不会更新另一个。 如果工作负荷同时使用这两者，请查看这两者。

可以停用控制平面 API 版本，如本文前面所述。

可以弃用预览数据平面 API 版本，因此请勿在生产中使用预览版，除非你接受该生命周期。 有关受支持的数据平面 API 版本，请参阅 Azure 密钥保管库 REST API 参考。

本文重点介绍如何识别和更新 API 版本。 更新控制平面 API 版本不需要将现有密钥保管库从访问策略迁移到 Azure RBAC。 如果要迁移访问控制，请参阅从访问策略迁移到 Azure RBAC。 有关在 API 版本 2026-02-01 及更高版本中针对新密钥保管库引入的 Azure RBAC 默认行为，请参阅 规划将 Azure RBAC 用作密钥保管库中的默认访问控制模型。

为何迁移到当前 API 版本

• 使用受支持的功能。 较新的 API 版本可以添加功能、正确行为或支持新的服务功能。
• 使生产工作负荷保持稳定。 将当前的稳定 API 版本用于生产工作负荷。 预览版 API 版本用于评估和早期测试，Azure 支持 SLA 可能未涵盖这些版本。 可以弃用预览版本。
• 使工具和库保持兼容。 Azure CLI、Azure PowerShell、SDK、模板和门户可以使用不同的 API 版本。 更新一个客户端的版本不会更新其他客户端。

有关当前控制平面版本，请参阅 支持的控制平面 API 版本。 有关受支持的数据平面版本，请参阅 Azure 密钥保管库 REST API 参考。

确定使用的 API 版本

根据调用密钥保管库的方式，以不同的方式指定 API 版本。 检查您的工作负载所使用的每个表面。

控制平面（管理）

• REST API：版本是 api-version 请求的 https://management.chinacloudapi.cn查询字符串参数，例如 ?api-version=<control-plane-version>。
• ARM、Bicep 和 Terraform 模板：版本是每个Microsoft.KeyVault/vaults资源上的apiVersion属性。 在Bicep中，它是资源类型声明的一部分，例如resource kv 'Microsoft.KeyVault/vaults@2026-02-01'。
• 控制平面管理 SDK：包版本可以确定 SDK 支持的 API 版本，但包版本并不总是标识请求使用的 API 版本。 检查包发行说明和 API 参考（例如，Azure.ResourceManager.KeyVaultazure-mgmt-keyvault或），并将其与项目的依赖项清单中的包版本进行比较。 有关按语言的 API 引用，请参阅Azure 密钥保管库客户端库。
• Azure CLI和Azure PowerShell：Azure CLI或Az模块的版本决定了 API 版本。 使用 az version 或 Get-InstalledModule -Name Az 检查已安装的版本。
• Azure门户：门户为其请求选择控制平面 API 版本。 无法直接设置该版本。 门户可以使用不同于模板、脚本或 SDK 的 API 版本，因此不要使用门户行为来确定自动化使用的版本。
• Azure Cloud Shell：Cloud Shell使用当前Azure CLI和Azure PowerShell版本。 如果在Cloud Shell中运行脚本，请确保它们与当前支持的控制平面 API 版本兼容。

数据平面

• REST API：版本是 api-version 针对对保管库终结点的请求的查询字符串参数，例如 GET https://<vault-name>.vault.azure.cn/secrets/<name>?api-version=<data-plane-version>。
• 数据平面 SDK：包版本可以确定 SDK 支持的 API 版本，但包版本并不总是标识请求使用的 API 版本。 检查软件包发行说明和 API 参考文档（例如，Azure.Security.KeyVault.Secrets、Azure.Security.KeyVault.Keys 或 Azure.Security.KeyVault.Certificates 的文档），并将其与项目依赖清单中的软件包版本进行比较。 有关按语言的 API 引用，请参阅Azure 密钥保管库客户端库。

更新 API 版本

更新控制平面 API 版本

1. 更新模板和 REST 调用中的 API 版本。 在所有 apiVersion 定义和管理请求中，将 Microsoft.KeyVault/vaults（ARM、Bicep、Terraform）或 api-version 查询字符串参数（REST）设置为当前受支持的控制平面版本。

2. 更新控制平面管理 SDK。 请查看支持您所选控制平面 API 版本的软件包版本的发行说明和 API 参考。 有关按语言分类的 API 参考，以及支持当前 密钥保管库 控制平面版本的包版本，请参阅 Azure 密钥保管库 客户端库和控制平面 SDK 版本。

   注释

   更新控制平面管理 SDK 不会更新数据平面 SDK。 如果应用程序使用这两个 API 图面，请单独更新每个 SDK。

3. 更新Azure CLI和Azure PowerShell。 较新的工具版本调用较新的 API 版本。

   • Azure CLI
   • Azure PowerShell

   将 Azure CLI 更新到最新版本。 有关详细信息，请参阅如何更新 Azure CLI。

4. 在部署之前查看行为变化。 在部署之前读取 API 版本的更改日志和规范。 API 版本 2026-02-01 及更高版本仅对新密钥保管库更改默认访问控制模型。 有关详细信息，请参阅“规划 Azure RBAC”作为密钥保管库中的默认访问控制模型。

更新数据平面 API 版本

1. 更新 REST 调用中的 API 版本。 将api-version查询字符串参数设置为Azure 密钥保管库 REST API 引用中列出的当前支持的数据平面版本。

2. 更新您的数据平面 SDK。 将 Azure.Security.KeyVault.* 语言包的（或等效版本）升级到当前稳定版本。 检查包发行说明和 API 参考，以确定包支持的数据平面 API 版本。 有关按语言的 API 引用和包链接，请参阅Azure 密钥保管库客户端库。

稳定数据平面 API 版本不受当前控制平面停用的影响。 如果使用预览数据平面 API，请查看服务公告和 API 参考，了解其生命周期。

有关调用数据平面 REST API 的详细信息，请参阅身份验证、请求和响应以及Azure 密钥保管库 REST API 参考。

相关内容

• 在 密钥保管库 中将 Azure RBAC 规划为默认访问控制模型
• 从访问策略迁移到 Azure RBAC
• Azure 密钥保管库 的新增功能
• 支持的控制平面 API 版本
• 身份验证、请求和响应
• Azure 密钥保管库 客户端库
• Azure 密钥保管库开发人员指南
• Azure 密钥保管库 REST API 参考