Atualize a versão da API do Azure Key Vault que utiliza

Azure Key Vault utiliza APIs versionadas. Se as suas aplicações, scripts ou templates de infraestrutura chamarem uma versão antiga da API, pode perder funcionalidades mais recentes, usar comportamentos que mudaram numa versão posterior ou depender de uma versão que já não é recomendada. Este artigo explica como determinar qual a versão da API que utiliza e como migrar para uma versão atual e suportada.

Importante

Todas as versões da API do Key Vault do plano de controlo anteriores a 2026-02-01 serão descontinuadas em 27 de fevereiro de 2027. Depois dessa data, os teus cofres de chaves continuam a existir, mas só podes geri-los com a versão 2026-02-01 da API do plano de controlo ou posterior. Não há exceção nem extensão a esta data. Esta aposentação não afeta as APIs do plano de dados (as APIs usadas para trabalhar com chaves, segredos e certificados). Para mais detalhes, consulte Plano para Azure RBAC como modelo padrão de controlo de acesso no Key Vault.

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

Superfície API O que ela consegue Esquema de versões Exemplo de ponto final
Plano de controlo (gestão) O próprio recurso do Key Vault: criar, atualizar, eliminar cofres e configurar propriedades como SKU, regras de rede e controlo de acesso. Baseado em datas ({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 em datas ({YYYY}-{MM}-{DD}) https://<vault-name>.vault.azure.net

As duas superfícies têm práticas diferentes de versionamento e ciclo de vida. Atualizar um não atualiza o outro. Revê ambos se a tua carga de trabalho usar ambos.

As versões da API do plano de controlo podem ser retiradas, como descrito anteriormente neste artigo.

As versões da API do plano de dados de pré-visualização podem ser obsoletas, por isso não uses pré-visualizações em produção a menos que aceites esse ciclo de vida. Para versões suportadas da API de planos de dados, consulte a referência da API REST do Azure Key Vault.

Este artigo foca-se na identificação e atualização de versões da API. A atualização de uma versão de API do plano de controlo não exige a migração de um cofre de chaves existente das políticas de acesso para o Azure RBAC. Se quiser migrar o controlo de acesso, veja Migrar para o Azure RBAC a partir das políticas de acesso. Para o comportamento predefinido do Azure RBAC introduzido para novos cofres de chaves na versão da API 2026-02-01 e posteriores, consulte Planear o Azure RBAC como modelo de controlo de acesso predefinido no Key Vault.

Porque mudar para uma versão atual da API

  • Utilize as capacidades suportadas. Versões mais recentes da API podem adicionar capacidades, corrigir comportamentos ou suportar novas funcionalidades de serviço.
  • Mantenha as cargas de trabalho de produção estáveis. Use uma versão estável da API atual para cargas de trabalho em produção. As versões de pré-visualização da API servem para avaliação e testes iniciais, e os SLAs de suporte do Azure podem não cobri-las. As versões de pré-visualização podem ser obsoletas.
  • Mantém as ferramentas e bibliotecas compatíveis. CLI do Azure, Azure PowerShell, SDKs, templates e o portal podem usar diferentes versões da API. Atualizar a versão de um cliente não atualiza os outros.

Para as versões atuais do plano de controlo, veja Versões suportadas da API do plano de controlo. Para versões suportadas de planos de dados, consulte a referência da API REST do Azure Key Vault.

Determina qual a versão da API que usas

Especificas a versão da API de forma diferente consoante a forma como chamas o Key Vault. Verifique cada superfície que a sua carga de trabalho utiliza.

Plano de controlo (gestão)

  • REST API: A versão é o parâmetro api-version da cadeia de consulta nos pedidos para https://management.azure.com, por exemplo ?api-version=<control-plane-version>.
  • Modelos ARM, Bicep e Terraform: A versão é a propriedade apiVersion em cada recurso Microsoft.KeyVault/vaults. No Bicep, faz parte da declaração do tipo de recurso, por exemploresource kv 'Microsoft.KeyVault/vaults@2026-02-01'.
  • SDKs de gestão do plano de controlo: A versão do pacote pode determinar quais as versões da API que um SDK suporta, mas a versão do pacote sozinha nem sempre identifica a versão da API usada por um pedido. Verifique as notas de lançamento do pacote e a referência da 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 seu projeto. Para referências à API por linguagem, consulte as bibliotecas clientes do Azure Key Vault.
  • CLI do Azure e Azure PowerShell: A versão da sua CLI do Azure ou Az módulo determina a versão da API. Verifique a versão instalada com az version ou Get-InstalledModule -Name Az.
  • Portal Azure: O portal seleciona a versão da API do plano de controlo para os seus pedidos. Não podes definir essa versão diretamente. O portal pode usar uma versão diferente da API dos teus templates, scripts ou SDKs, por isso não uses o comportamento do portal para determinar a versão usada pela tua automação.
  • Azure Cloud Shell: Cloud Shell utiliza as versões atuais do CLI do Azure e Azure PowerShell. Se executares scripts no Cloud Shell, certifica-te de que são compatíveis com a versão da API do plano de controlo atualmente suportada.

Plano de dados

  • API REST: A versão é especificada pelo parâmetro api-version da cadeia de consulta nos pedidos para o endpoint do seu cofre, por exemplo, GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>.
  • SDKs do plano de dados: A versão do pacote pode determinar quais as versões da API que um SDK suporta, mas a versão do pacote, por si só, nem sempre identifica a versão da API usada por um pedido. Verifique as notas de lançamento do pacote e a referência da API (por exemplo, para Azure.Security.KeyVault.Secrets, Azure.Security.KeyVault.Keys, ou Azure.Security.KeyVault.Certificates) e compare-as com a versão do pacote no manifesto de dependência do seu projeto. Para referências à API por linguagem, consulte as bibliotecas clientes do Azure Key Vault.

Atualize a versão da sua API

Atualizar a versão da API do plano de controlo

  1. Atualize a versão da API nos seus templates e chamadas REST. Defina apiVersion (ARM, Bicep, Terraform) ou o parâmetro de cadeia de consulta api-version (REST) para uma versão do plano de controlo atualmente suportada em todas as definições Microsoft.KeyVault/vaults e pedidos de gestão.

  2. Atualiza os SDKs de gestão do plano de controlo. Verifique as notas de lançamento do pacote e a referência da API para a versão do pacote que suporta a versão da API do plano de controlo que selecionou. Para referências de API por linguagem e as versões de pacotes que suportam a versão atual do plano de controlo do Key Vault, consulte as bibliotecas de clientes do Azure Key Vault e as versões do SDK do plano de controlo.

    Note

    Atualizar um SDK de gestão do plano de controlo não atualiza os SDKs do plano de dados. Atualize cada SDK separadamente se a sua aplicação usar ambas as superfícies da API.

  3. Atualize CLI do Azure e Azure PowerShell. As versões mais recentes de ferramentas utilizam versões mais recentes da API.

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

  1. Reveja as alterações de comportamento antes de implementar. Leia o registo de alterações e a especificação da versão da API antes de implementar. A versão 2026-02-01 da API e posteriores alteram o modelo de controlo de acesso predefinido apenas para novos cofres de chaves. Para mais detalhes, consulte Plano para Azure RBAC como modelo padrão de controlo de acesso no Key Vault.

Atualizar a versão da API do plano de dados

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

  2. Atualize os seus SDKs do plano de dados. Atualiza os Azure.Security.KeyVault.* pacotes (ou equivalentes para a tua língua) para uma versão estável atual. Consulte as notas de lançamento do pacote e a referência da API para determinar que versões da API do plano de dados o pacote suporta. Para referências de API e links de pacotes por linguagem, consulte as bibliotecas de clientes do Azure Key Vault.

As versões estáveis da API do plano de dados não são afetadas pela atual descontinuação do plano de controlo. Se utilizar uma API de pré-visualização do plano de dados, consulte os comunicados do serviço e a referência da API relativamente ao respetivo ciclo de vida.

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

Conteúdo relacionado

  • Última atualização a