Atualizar a versão da API Azure Key Vault que você usa

O Azure Key Vault usa APIs versionadas. Se seus aplicativos, scripts ou modelos de infraestrutura chamarem uma versão de API mais antiga, você poderá perder recursos mais recentes, usar o comportamento que foi alterado em uma versão posterior ou depender de uma versão que não seja mais recomendada. Este artigo explica como determinar qual versão da API você usa e como mover para uma versão atual com suporte.

Importante

Todas as versões da API do plano de controle do Key Vault anteriores a 2026-02-01 serão desativadas em 27 de fevereiro de 2027. Após essa data, os key vaults continuam existindo, mas você só pode gerenciá-los com a versão 2026-02-01 ou posterior da API do plano de controle. Não há exceção ou extensão até esta data. Essa desativação não afeta as APIs do plano de dados (as APIs usadas para trabalhar com chaves, segredos e certificados). Para obter detalhes, consulte Planejar o Azure RBAC como o modelo de controle de acesso padrão no Key Vault.

Azure Key Vault tem duas superfícies de API independentes, cada uma com suas próprias versões:

Superfície da API O que gerencia Esquema de versão Ponto de extremidade de exemplo
Plano de controle (gerenciamento) O recurso do cofre de chaves em si: criar, atualizar, excluir cofres e configurar propriedades como SKU, regras de rede e controle de acesso. Baseado na data ({YYYY}-{MM}-{DD}) https://management.azure.com
Plano de dados Objetos dentro de um cofre: chaves, segredos e certificados e operações criptográficas. Baseado na data ({YYYY}-{MM}-{DD}) https://<vault-name>.vault.azure.net

As duas superfícies têm práticas distintas de versionamento e ciclo de vida. Atualizar um não atualiza o outro. Revise os dois caso sua carga de trabalho use ambos.

As versões da API do painel de controle podem ser desativadas, conforme descrito anteriormente neste artigo.

As versões de prévia da API de plano de dados podem ser descontinuadas, portanto, não use versões de prévia em produção, a menos que você aceite esse ciclo de vida. Para as versões da API do plano de dados com suporte, consulte a referência da API REST do Azure Key Vault.

Este artigo se concentra na identificação e atualização de versões da API. Atualizar uma versão da API do painel de controle não exige que você migre um cofre de chaves existente das políticas de acesso para Azure RBAC. Se você quiser migrar o controle de acesso, consulte Migrar para o Azure RBAC das políticas de acesso. Para o comportamento padrão do Azure RBAC introduzido para novos cofres de chaves na versão da API 2026-02-01 e posteriores, consulte Planejar o Azure RBAC como modelo padrão de controle de acesso no Key Vault.

Por que mover para uma versão da API atual

  • Use recursos com suporte. Versões mais recentes da API podem adicionar recursos, comportamento correto ou dar suporte a novos recursos de serviço.
  • Mantenha as cargas de trabalho de produção estáveis. Use uma versão atual da API estável para cargas de trabalho de produção. As versões de API de visualização são para avaliação e teste antecipado, e Suporte do Azure SLAs podem não cobri-las. As versões prévias podem ser descontinuadas.
  • Mantenha as ferramentas e bibliotecas compatíveis. CLI do Azure, Azure PowerShell, SDKs, modelos e o portal podem usar diferentes versões de API. Atualizar a versão de um cliente não atualiza as outras.

Para as versões atuais do plano de controle, consulte Versões com suporte da API do plano de controle. Para versões de plano de dados com suporte, consulte a referência da API REST Azure Key Vault.

Determinar qual versão da API você usa

Especifique a versão da API de forma diferente dependendo de como você chama Key Vault. Verifique cada superfície que sua carga de trabalho usa.

Plano de controle (gerenciamento)

  • API REST: a versão é o parâmetro de cadeia de caracteres de consulta api-version em solicitações para https://management.azure.com, por exemplo ?api-version=<control-plane-version>.
  • Modelos ARM, Bicep e Terraform: a versão é a propriedade apiVersion de cada recurso Microsoft.KeyVault/vaults. No Bicep, faz parte da declaração de tipo de recurso, por exemploresource kv 'Microsoft.KeyVault/vaults@2026-02-01'.
  • SDKs de gerenciamento do plano de controle: a versão do pacote pode determinar quais versões da API um SDK oferece suporte, mas a versão do pacote, por si só, nem sempre identifica a versão da API usada por uma requisição. Verifique as notas de versão do pacote e a referência de API (por exemplo, para Azure.ResourceManager.KeyVault ou azure-mgmt-keyvault) e compare-as com a versão do pacote no manifesto de dependência do projeto. Para referências de API por idioma, consulte Azure Key Vault bibliotecas de cliente.
  • CLI do Azure e Azure PowerShell: a versão do CLI do Azure ou Az módulo determina a versão da API. Verifique sua versão instalada com az version ou Get-InstalledModule -Name Az.
  • Azure portal: o portal seleciona a versão da API do painel de controle para suas solicitações. Você não pode definir essa versão diretamente. O portal pode usar uma versão de API diferente dos modelos, scripts ou SDKs, portanto, não use o comportamento do portal para determinar a versão usada pela automação.
  • Azure Cloud Shell: Cloud Shell usa as versões CLI do Azure e Azure PowerShell atuais. Se você executar scripts em Cloud Shell, verifique se eles são compatíveis com a versão da API do painel de controle com suporte no momento.

Plano de dados

  • API REST: a versão é o parâmetro de consulta api-version nas solicitações ao ponto de extremidade do seu cofre, por exemplo GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>.
  • SDKs de plano de dados: a versão do pacote pode determinar quais versões de API um SDK oferece suporte, mas a versão do pacote, por si só, nem sempre identifica a versão da API usada em uma solicitação. Verifique as notas de versão do pacote e a referência de API (por exemplo, para Azure.Security.KeyVault.Secrets, Azure.Security.KeyVault.Keysou Azure.Security.KeyVault.Certificates) e compare-as com a versão do pacote no manifesto de dependência do projeto. Para referências de API por idioma, consulte Azure Key Vault bibliotecas de cliente.

Atualizar sua versão da API

Atualizar a versão da API do painel de controle

  1. Atualize a versão da API em seus modelos e chamadas REST. Defina apiVersion (ARM, Bicep, Terraform) ou o parâmetro api-version de cadeia de consulta (REST) como uma versão do plano de controle atualmente com suporte em todas as definições de Microsoft.KeyVault/vaults e solicitações de gerenciamento.

  2. Atualize os SDKs de gerenciamento do painel de controle. Verifique as notas de versão do pacote e a referência de API para a versão do pacote que dá suporte à versão da API do painel de controle selecionada. Para referências de API por linguagem e as versões do pacote que dão suporte à versão atual do plano de controle Key Vault, consulte Azure Key Vault bibliotecas de clientes e versões do SDK do painel de controle.

    Note

    Atualizar um SDK de gerenciamento de plano de controle não atualiza os SDKs do plano de dados. Atualize cada SDK separadamente se o aplicativo usar ambas as superfícies de API.

  3. Atualize CLI do Azure e Azure PowerShell. Versões mais recentes da ferramenta usam versões mais recentes da API.

    Atualize a CLI do Azure para a versão mais recente. Para obter mais informações, confira Como atualizar a CLI do Azure.

  1. Examine as alterações de comportamento antes de implantar. Leia o log de alterações e a especificação da versão da API antes de implantar. A versão da API 2026-02-01 e posteriores alteram o modelo de controle de acesso padrão apenas para novos cofres de chaves. Para obter detalhes, consulte Planejar o Azure RBAC como o modelo de controle de acesso padrão no Key Vault.

Atualizar a versão da API do plano de dados

  1. Atualize a versão da API em suas chamadas REST. Defina o parâmetro de cadeia de consulta api-version para uma versão do plano de dados atualmente com suporte, listada na referência da API REST do Azure Key Vault.

  2. Atualize os SDKs do plano de dados. Atualize os Azure.Security.KeyVault.* pacotes (ou o equivalente para seu idioma) para uma versão estável atual. Verifique as notas de versão do pacote e a referência à API para determinar quais versões da API do plano de dados o pacote dá suporte. Para referências de API e links de pacote por idioma, consulte Azure Key Vault bibliotecas de cliente.

As versões estáveis da API do plano de dados não são afetadas pela desativação atual do plano de controle. Se você usar uma API de plano de dados em versão prévia, examine os comunicados do serviço e a referência da API sobre o ciclo de vida dela.

Para obter mais informações sobre como chamar a API REST do plano de dados, consulte Autenticação, solicitações e respostas e a referência da API REST Azure Key Vault.

Conteúdo relacionado

  • Última atualização em