Обновление используемой версии API Azure Key Vault

Azure Key Vault использует версионируемые API. Если приложения, скрипты или шаблоны инфраструктуры вызывают более старую версию API, вы можете пропустить более новые функции, использовать поведение, измененное в более поздней версии, или зависеть от версии, которая больше не рекомендуется. В этой статье объясняется, как определить используемую версию API и как перейти к текущей поддерживаемой версии.

Important

Все версии API плоскости управления Key Vault, предшествующие 2026-02-01, будут выведены из эксплуатации 27 февраля 2027 г. После этой даты хранилища ключей продолжают существовать, но управлять ими можно только с помощью версии 2026-02-01 API уровня управления или более поздней версии. Для этой даты не предусмотрены исключения или продление. Это прекращение работы не влияет на API плоскости данных (API, используемые для работы с ключами, секретами и сертификатами). Дополнительные сведения см. в разделе Планирование использования Azure RBAC в качестве модели управления доступом по умолчанию в Key Vault.

Azure Key Vault имеет две независимые поверхности API, каждая из которых имеет собственные версии:

Поверхность API Чем он управляет Схема версий Пример конечной точки
Плоскость управления (управление) Сам ресурс хранилища ключей: создание, обновление, удаление хранилищ и настройка таких свойств, как SKU, правила сети и управление доступом. На основе даты ({YYYY}-{MM}-{DD}) https://management.azure.com
Плоскость данных Объекты внутри хранилища: ключи, секреты и сертификаты, а также криптографические операции. На основе даты ({YYYY}-{MM}-{DD}) https://<vault-name>.vault.azure.net

Две поверхности имеют различные методики управления версиями и жизненным циклом. Обновление одного не обновляет другое. Проверьте оба варианта, если рабочая нагрузка использует оба.

Версии API уровня управления можно удалить, как описано ранее в этой статье.

Версии API уровня данных предварительной версии могут быть устаревшими, поэтому не используйте предварительные версии в рабочей среде, если вы не принимаете этот жизненный цикл. Поддерживаемые версии API плоскости данных см. в справочнике по REST API Azure Key Vault.

В этой статье рассматривается определение и обновление версий API. Обновление версии API уровня управления не требует переноса существующего хранилища ключей из политик доступа в Azure RBAC. Если вы хотите перенести управление доступом, см. статью "Миграция на Azure RBAC" из политик доступа. Сведения о поведении Azure RBAC по умолчанию, введенном для новых хранилищ ключей в версии API 2026-02-01 и более поздних версиях, см. в статье Планирование использования Azure RBAC в качестве модели управления доступом по умолчанию в Key Vault.

Почему переход к текущей версии API

  • Используйте поддерживаемые возможности. Более новые версии API могут добавлять возможности, правильное поведение или поддерживать новые функции службы.
  • Сохраняйте стабильную рабочую нагрузку. Используйте текущую стабильную версию API для рабочих нагрузок. Предварительные версии API предназначены для оценки и раннего тестирования, и поддержка Azure соглашения об уровне обслуживания могут не охватывать их. Предварительные версии могут быть объявлены устаревшими.
  • Сохраняйте совместимость средств и библиотек. Azure CLI, Azure PowerShell, пакеты SDK, шаблоны и портал могут использовать разные версии API. Обновление версии для одного клиента не обновляет другие.

Сведения о текущих версиях плоскости управления см. в разделе "Поддерживаемые версии API плоскости управления". Поддерживаемые версии плоскости данных см. в справочнике по REST API Azure Key Vault.

Определение используемой версии API

Вы указываете версию API по-разному в зависимости от способа вызова Key Vault. Проверьте каждую область, которую использует ваша рабочая нагрузка.

Плоскость управления (управление)

  • REST API: версия указывается в параметре строки запроса api-version в запросах к https://management.azure.com, например ?api-version=<control-plane-version>.
  • Шаблоны ARM, Bicep и Terraform: версия — это apiVersion свойство для каждого Microsoft.KeyVault/vaults ресурса. В Bicep это часть объявления типа ресурса, например resource kv 'Microsoft.KeyVault/vaults@2026-02-01'.
  • Пакеты SDK для управления плоскостями управления: версия пакета может определить, какие версии API поддерживает пакет SDK, но только версия пакета не всегда определяет версию API, используемую запросом. Проверьте заметки о выпуске пакета и справочник по API (например, для Azure.ResourceManager.KeyVault или azure-mgmt-keyvault) и сравните их с версией пакета в манифесте зависимости проекта. Ссылки на API по языку см. в Azure Key Vault клиентских библиотеках.
  • Azure CLI и Azure PowerShell: версия Azure CLI или Az модуля определяет версию API. Проверьте установленную версию с помощью az version или Get-InstalledModule -Name Az.
  • Портал Azure: портал выбирает версию API уровня управления для своих запросов. Эту версию нельзя задать напрямую. Портал может использовать другую версию API, отличную от шаблонов, скриптов или пакетов SDK, поэтому не используйте поведение портала для определения версии, используемой службой автоматизации.
  • Azure Cloud Shell: Cloud Shell использует текущие Azure CLI и Azure PowerShell версии. Если вы запускаете скрипты в Cloud Shell, убедитесь, что они совместимы с текущей поддерживаемой версией API плоскости управления.

Плоскость данных

  • REST API: версия задаётся параметром строки запроса api-version в запросах к конечной точке вашего хранилища, например GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>.
  • Пакеты SDK для плоскости данных: версия пакета может определить, какие версии API поддерживает пакет SDK, но только версия пакета не всегда определяет версию API, используемую запросом. Проверьте заметки о выпуске пакета и справочник по API (например, для Azure.Security.KeyVault.Secrets, Azure.Security.KeyVault.Keysили Azure.Security.KeyVault.Certificates) и сравните их с версией пакета в манифесте зависимости проекта. Ссылки на API по языку см. в Azure Key Vault клиентских библиотеках.

Обновление версии API

Обновить версию API плоскости управления

  1. Обновите версию API в шаблонах и вызовах REST. Задайте apiVersion (ARM, Bicep, Terraform) или параметр строки запроса api-version (REST) на одну из поддерживаемых в настоящее время версий плоскости управления во всех определениях Microsoft.KeyVault/vaults и запросах управления.

  2. Обновите пакеты SDK для управления плоскостями управления. Проверьте заметки о выпуске пакета и справочник по API для версии пакета, поддерживающей выбранную версию API уровня управления. Ссылки на API по языку и версиям пакетов, которые поддерживают текущую версию уровня управления Key Vault, см. в Azure Key Vault клиентских библиотеках и выпусках пакета SDK уровня управления.

    Note

    Обновление SDK для управления плоскостью управления не обновляет SDK плоскости данных. Обновите каждый пакет SDK отдельно, если приложение использует обе поверхности API.

  3. Обновите Azure CLI и Azure PowerShell. Новые версии инструментов вызывают более новые версии API.

    Обновите Azure CLI до последней версии. Дополнительные сведения см. в статье Как обновить Azure CLI.

  1. Перед развертыванием просмотрите изменения поведения. Перед развертыванием ознакомьтесь с журналом изменений и спецификацией версии API. Начиная с версии API 2026-02-01 модель контроля доступа по умолчанию изменяется только для новых хранилищ ключей. Дополнительные сведения см. в статье Планирование Azure RBAC как модели управления доступом по умолчанию в Key Vault.

Обновление версии API плоскости данных

  1. Обновите версию API в вызовах REST. api-version Задайте для параметра строки запроса поддерживаемую версию плоскости данных, указанную в справочнике по REST API Azure Key Vault.

  2. Обновите SDK уровня данных. Обновите пакеты Azure.Security.KeyVault.* (или их эквиваленты для вашего языка) до актуальной стабильной версии. Проверьте заметки о выпуске пакета и справочник по API, чтобы определить, какие версии API плоскости данных поддерживает пакет. Справочные материалы по API и ссылки на пакеты для разных языков см. в клиентских библиотеках Azure Key Vault.

Стабильные версии API плоскости данных не затрагиваются текущим выводом из эксплуатации плоскости управления. Если вы используете предварительную версию API плоскости данных, ознакомьтесь с объявлениями о службе и справочником по API, чтобы узнать о его жизненном цикле.

Дополнительные сведения о вызове REST API плоскости данных см. в статье Аутентификация, запросы и ответы, а также в справочнике по REST API Azure Key Vault.

Связанные материалы

  • Последнее обновление: