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.

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

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 se és afetado

Um aviso de serviço não significa necessariamente que a telemetria detetou uma versão da API a desativar-se em cada subscrição ou Key Vault que possui. Os avisos podem alcançar um público mais vasto do que os recursos detetados na telemetria recente. Utilize os passos seguintes para avaliar as suas integrações.

Configura o registo de auditoria cedo. O Key Vault começa a recolher registos de auditoria depois de a definição de diagnóstico ser ativada e entrar em vigor. Os pedidos feitos antes disso não são preenchidos retroativamente, por isso reserve algum tempo para configuração e ingestão. Se o registo já estiver ativado, verifique o destino existente antes de adicionar outra definição de diagnóstico.

Selecione ou crie um espaço de trabalho de Log Analytics

Podes partilhar o espaço de trabalho, mas tens de configurar a coleção em todos os Key Vault que quiseres monitorizar. Criar um espaço de trabalho ou exportar o registo de atividade de uma subscrição não ativa o registo de auditoria do Key Vault. Inclua todos os cofres de chaves relevantes, não apenas os cofres de chaves que uma recomendação lista.

1. Reutilizar ou criar um espaço de trabalho. Se já existir um espaço de trabalho Log Analytics aprovado, registe o seu nome, subscrição e ID de recurso. Caso contrário, crie uma. Para obter mais informações, consulte Criar um espaço de trabalho do Log Analytics. Utilize um espaço de trabalho por subscrição, ou selecione um espaço central para múltiplas subscrições.

2. Confirme o acesso. Precisas de permissão para configurar as definições de diagnóstico nos cofres de chaves de origem e no destino, e o acesso de consulta que cubra os cofres de chaves contribuintes. Para obter mais informações, consulte Gerenciar o acesso a espaços de trabalho do Log Analytics.

Ative o registo de auditoria em cada Key Vault

Configure uma definição de diagnóstico em cada key vault seguindo os passos do portal Azure em Ativar o registo do Key Vault. Aplique estas definições para esta investigação:

• Logs: Selecione o grupo de categorias allLogs.
• Destino: Selecione Enviar para o espaço de trabalho do Log Analytics e depois selecione o espaço de trabalho que escolheu na secção anterior. Utilize o mesmo espaço de trabalho para cada Key Vault que partilhe um destino.
• Métricas: AllMetrics não é necessário para identificar versões da API ou os autores das chamadas.

Os eventos de auditoria podem incluir tanto operações no plano de controlo como no plano de dados, mas esta desativação afeta apenas as operações do plano de controlo. Métricas e exportações de registos de atividade de subscrição não substituem o registo de auditoria.

Para muitos Key Vaults ou subscrições, use Azure Policy em vez disso. Atribui a política incorporada: Ativa o registo por grupo de categorias para cofres de chaves (microsoft.keyvault/vaults) ao Log Analytics com o grupo de categorias allLogs e o ID do teu recurso de trabalho. Atribua-o entre as subscrições exigidas, usando o mesmo ID de recurso de espaço de trabalho para um destino partilhado. Crie uma tarefa de remediação e a identidade gerida que a política exige. Uma atribuição de política sozinha não configura os cofres de chaves existentes. Após a conclusão da remediação, verifique se a definição de diagnóstico de cada Key Vault aponta para o espaço de trabalho pretendido. Para mais informações, consulte Criar definições de diagnóstico em escala usando a Azure Policy incorporada.

Confirme que os registos estão a chegar

Abra a página de Logs do workspace de destino para executar consultas. Para obter mais informações, consulte o tutorial do Log Analytics. Para esta investigação, utilize o modo KQL, defina o âmbito para o espaço de trabalho e selecione Últimos 30 dias para corresponder aos exemplos. Não restrinja o âmbito a um único Key Vault quando investigar todas as subscrições contribuintes.

Reserve tempo para a ingestão inicial. Depois de criar uma definição de diagnóstico, os dados devem começar a fluir para o espaço de trabalho dentro de 90 minutos, e uma tabela só é criada após a chegada dos primeiros registos. Para mais informações, consulte Latência esperada após criar uma configuração de diagnóstico. Após a configuração, execute em segurança fluxos de trabalho de gestão representativos e depois volte a executar a consulta. Atualizar o Key Vault no portal do Azure pode ajudar a verificar a recolha, mas não testa todas as integrações de produção. Não mudes o modelo de controlo de acesso de um Key Vault apenas para testar o registo.

Para verificar a coleção, execute primeiro esta consulta sem um filtro de versão da API:

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| order by TimeGenerated desc
| take 50

Verifique _ResourceId e TimeGenerated para confirmar que os registos chegam dos cofres de chaves pretendidos após a configuração. Para verificar um cofre de chaves que não esteja nas últimas 50 linhas, filtre por _ResourceId antes order byde .

Se uma tabela estiver em falta ou a consulta não devolver registos, verifique novamente o espaço de trabalho, a definição de diagnóstico guardada, o cofre da chave de origem, o âmbito da consulta, o intervalo de tempo e as suas permissões. Uma tabela em falta ou um resultado vazio não provam que nenhuma versão da API em descontinuação está em uso.

Encontre pedidos que utilizem uma versão da API em descontinuação

Depois de confirmar a recolha, substitua a consulta por uma das seguintes consultas e depois selecione Executar.

Para encontrar pedidos que utilizem uma versão específica em descontinuação, como 2026-03-01-preview, filtre nessa versão:

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where OperationVersion == "2026-03-01-preview"
| order by TimeGenerated desc

Para encontrar pedidos que utilizem qualquer versão da API do plano de controlo anterior a 2026-02-01, filtre por versões anteriores a 2026-02-01:

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where strcmp(OperationVersion, "2026-02-01") < 0
| order by TimeGenerated desc

Os resultados identificam pedidos registados que utilizam uma versão desativada, incluindo os seus IDs de recursos. A segunda consulta pode também devolver pedidos de plano de dados que utilizam as versões legadas do plano de dados 2015-06-01 ou 2016-10-01. Esta descontinuação não afeta os pedidos de data plane. Os nomes das operações do plano de dados começam por Secret, Key, ou Certificate.

Não filtre pelos nomes de operações que começam por Vault, porque esse filtro pode excluir operações de recursos filhos registadas. Use OperationName e o URI de pedido para perceber qual operação de gestão ocorreu. Use os detalhes destes registos para identificar o chamador e depois atualize a sua versão da API conforme descrito em Atualizar a sua versão da API.

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)

• API REST: A versão é o api-version parâmetro da string de consulta em pedidos para https://management.azure.com, por exemplo ?api-version=<control-plane-version>.
• Modelos ARM e ficheiros Bicep: A versão é a propriedade apiVersion de 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'. Recursos filhos como Microsoft.KeyVault/vaults/secrets, Microsoft.KeyVault/vaults/keys, e Microsoft.KeyVault/vaults/accessPolicies também são recursos do plano de controlo, e cada um declara a sua própria versão da API. Atualizar a versão do cofre principal não atualiza os seus recursos filhos.
• Terraform: Com o fornecedor AzAPI, a versão faz parte do tipo de recurso, por exemplo Microsoft.KeyVault/vaults@2026-02-01. Com o fornecedor AzureRM, a versão do fornecedor determina a versão da API, e os recursos não têm uma definição de versão da API. Consulte as notas de lançamento do fornecedor e a documentação de recursos para a versão da API que a versão do seu fornecedor utiliza.
• 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 do CLI do Azure ou do módulo Az determina a versão da API. Verifique a versão instalada com az version ou Get-InstalledModule -Name Az.
• Portal do 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 é o api-version parâmetro de string de consulta nos pedidos para o endpoint do seu vault, por GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>exemplo.
• 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. Definir apiVersion (ARM, Bicep), o tipo de recurso versionado (Terraform AzAPI) ou o api-version parâmetro de cadeia de consulta (REST) para uma versão atualmente suportada no plano de controlo. Atualize todas as definições Microsoft.KeyVault/vaults, os respetivos recursos subordinados e os pedidos de gestão. Se usar o fornecedor Terraform AzureRM, atualize o fornecedor para uma versão que utilize uma versão suportada pela API do plano de controlo.

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.

   • CLI do Azure
   • Azure PowerShell

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

4. 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

• Planeie o Azure RBAC como modelo predefinido de controlo de acesso no Key Vault
• Migrar para o Azure RBAC a partir das políticas de acesso
• Novidades para o Azure Key Vault
• Versões suportadas da API do plano de controlo
• Autenticação, pedidos e respostas
• Azure Key Vault client libraries
• Azure Key Vault Developer's Guide
• Referência da API REST do Azure Key Vault