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

Azure 密钥保管库使用版本控制 API。 如果应用程序、脚本或基础结构模板调用较旧的 API 版本，你可能会错过较新的功能、使用计划更改的行为，或取决于计划停用的版本。 本文介绍如何确定所使用的 API 版本以及如何移动到当前受支持的版本。

Important

所有在 之前的控制平面 API 版本将于 2026-02-01 停用。 在该日期之后，密钥保管库将继续存在，但只能使用控制平面 API 版本 2026-02-01 或更高版本来管理它们。 此次停用不会影响数据平面 API。

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

API 接口面 它管理的内容 版本规则 示例终结点
控制平面 （管理） 密钥保管库资源本身：创建、更新、删除保管库并配置 SKU、网络规则和访问控制等属性。 基于日期（{YYYY}-{MM}-{DD}） https://management.chinacloudapi.cn
数据平面 保管库中的对象：密钥、机密和证书以及加密操作。 版本号 （7.x） https://<vault-name>.vault.azure.cn

这两个界面的版本发布和弃用分别遵循不同的时间安排。 更新一个不会更新另一个。 如果工作负荷同时使用这两者，请查看这两者。

为何迁移到当前 API 版本

  • 避免退休。 在停用日期之前更新控制平面客户端、模板和 REST 调用。 有关详细信息，请参阅 为 密钥保管库 API 版本 2026-02-01 及更高版本做好准备。
  • 持续获得支持。 预览 API 版本仅用于早期测试，Azure 支持 SLA 不涵盖这些版本。 将最新的稳定版本用于生产工作负荷。 Azure 将弃用预览版控制平面版本（2026-04-01-preview 除外），并提前 90 天发出通知。
  • 获得新功能和修复。 较新的 API 版本会随附新的功能和行为变更。 例如，控制平面 API 版本 2026-02-01 将 Azure RBAC 引入为新创建的保管库的默认访问控制模型。

有关受支持的控制平面 API 版本的完整列表，请参阅 支持的控制平面 API 版本。

当前 API 版本

API 接口面 最新稳定版本
控制平面 2026-02-01
数据平面 7.6

确定使用的 API 版本

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

控制平面（管理）

  • REST API：版本是 api-version 请求的 https://management.chinacloudapi.cn查询字符串参数，例如 ?api-version=2026-02-01。
  • ARM、Bicep 和 Terraform 模板：版本是每个Microsoft.KeyVault/vaults资源上的apiVersion属性。 在Bicep中，它是资源类型声明的一部分，例如resource kv 'Microsoft.KeyVault/vaults@2026-02-01'。
  • 控制平面管理 SDK：SDK 包版本确定 API 版本（例如，Azure.ResourceManager.KeyVault.NET或azure-mgmt-keyvaultPython）。 检查项目的依赖项清单中的包版本。
  • Azure CLI和Azure PowerShell：Azure CLI或Az模块的版本决定了 API 版本。 使用 az version 或 Get-InstalledModule -Name Az 检查已安装的版本。
  • Azure Cloud Shell：Cloud Shell始终使用最新的 API 版本。 如果在 Cloud Shell 中运行脚本，请确保它们与控制平面 API 版本2026-02-01或更高版本兼容。

数据平面

  • REST API：版本是 api-version 针对对保管库终结点的请求的查询字符串参数，例如 GET https://<vault-name>.vault.azure.cn/secrets/<name>?api-version=7.6。
  • 数据平面 SDK：SDK 包版本决定所使用的 API 版本（例如，Azure.Security.KeyVault.Secrets、Azure.Security.KeyVault.Keys或Azure.Security.KeyVault.Certificates）。 检查项目的依赖项清单中的包版本。

更新 API 版本

更新控制平面 API 版本

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

  2. 更新控制平面管理 SDK。 当这些 API 版本在 2027 年 2 月 27 日停用时，使用较旧 API 版本的控制平面管理 SDK 停止工作。 升级到支持 API 版本 2026-02-01 或更高版本的软件包版本。 有关每个语言所需的包版本，请参阅 控制平面 SDK 版本。

    注释

    控制平面停用不会影响数据平面 SDK。 你只需针对该变更更新控制平面管理 SDK。

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

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

  1. 在部署之前查看行为变化。 API 版本 2026-02-01 及更高版本会将新创建的保管库的默认访问控制模型更改为 Azure RBAC。 此更改仅影响 创建 操作。 现有保管库保留其当前访问模型。 查看详细信息，并在为 密钥保管库 API 版本 2026-02-01 及更高版本做好准备中决定后续路径。

更新数据平面 API 版本

  1. 更新 REST 调用中的 API 版本。 在发送到保管库端点的请求中，将 api-version 查询字符串参数设置为 7.6。

  2. 更新您的数据平面 SDK。 将 Azure.Security.KeyVault.* 语言包的（或等效版本）升级到最新的稳定版本。 有关每个语言的客户端库，请参阅Azure 密钥保管库客户端库。

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

相关内容

  • Last updated on