Aggiornare la versione dell'API Azure Key Vault usata

Azure Key Vault usa le API con controllo delle versioni. Se le applicazioni, gli script o i modelli di infrastruttura chiamano una versione precedente dell'API, è possibile che non si verifichino funzionalità più recenti, usare il comportamento modificato in una versione successiva o dipendere da una versione non più consigliata. Questo articolo illustra come determinare la versione dell'API usata e come passare a una versione corrente supportata.

Importante

Tutte le versioni dell'API del piano di controllo di Key Vault precedenti a 2026-02-01 saranno ritirate il 27 febbraio 2027. Dopo tale data, gli insiemi di credenziali delle chiavi continuano a esistere, ma è possibile gestirli solo con la versione dell'API del piano di controllo 2026-02-01 o successiva. Non esiste alcuna eccezione o estensione a questa data. Questo ritiro non influisce sulle API del piano dati (le API usate per usare chiavi, segreti e certificati). Per i dettagli, vedi Pianificare Azure RBAC come modello predefinito di controllo di accesso in Key Vault.

Azure Key Vault ha due superfici API indipendenti, ognuna con le proprie versioni:

Superficie delle API	Cosa gestisce	Schema di versione	Endpoint di esempio
Piano di controllo (gestione)	La risorsa dell'insieme di credenziali stessa: creare, aggiornare ed eliminare insiemi di credenziali e configurare proprietà come SKU, regole di rete e controllo degli accessi.	Basato sulla data (`{YYYY}-{MM}-{DD}`)	`https://management.azure.com`
Piano dati	Oggetti contenuti in un insieme di credenziali: chiavi, segreti, certificati e operazioni crittografiche.	Basato sulla data (`{YYYY}-{MM}-{DD}`)	`https://<vault-name>.vault.azure.net`

Le due superfici presentano pratiche diverse per la gestione delle versioni e del ciclo di vita. L'aggiornamento di uno non aggiorna l'altro. Esaminare entrambi se il carico di lavoro li usa entrambi.

È possibile ritirare le versioni dell'API del piano di controllo, come descritto in precedenza in questo articolo.

Le versioni dell'API del piano dati di anteprima possono essere deprecate, quindi non usare le anteprime nell'ambiente di produzione a meno che non si accetti tale ciclo di vita. Per le versioni supportate dell'API del piano dati, vedere le informazioni di riferimento su Azure Key Vault REST API.

Questo articolo è incentrato sull'identificazione e l'aggiornamento delle versioni dell'API. L'aggiornamento della versione di un'API del piano di controllo non richiede di migrare un insieme di credenziali delle chiavi esistente dai criteri di accesso a RBAC di Azure. Se si vuole eseguire la migrazione del controllo di accesso, vedere Eseguire la migrazione ad Azure RBAC dai criteri di accesso. Per il comportamento predefinito di Azure RBAC introdotto per i nuovi insiemi di credenziali nella versione dell'API 2026-02-01 e successive, vedere Pianificare Azure RBAC come modello di controllo di accesso predefinito in Key Vault.

Perché passare a una versione dell'API corrente

Usare le funzionalità supportate. Le versioni più recenti dell'API possono aggiungere funzionalità, un comportamento corretto o supportare nuove funzionalità del servizio.
Mantenere stabili i carichi di lavoro di produzione. Usare una versione attuale dell'API stabile per i carichi di lavoro di produzione. Le versioni di anteprima dell'API sono destinate alla valutazione e ai test preliminari e i contratti di servizio di supporto di Azure potrebbero non coprirle. Le versioni di anteprima possono essere dichiarate obsolete.
Mantenere compatibili strumenti e librerie. interfaccia della riga di comando di Azure, Azure PowerShell, SDK, modelli e il portale possono usare versioni api diverse. L'aggiornamento della versione per un client non aggiorna gli altri.

Per le versioni correnti del piano di controllo, vedere Versioni dell'API del piano di controllo supportate. Per le versioni supportate del piano dati, vedere la documentazione di riferimento dell'API REST di Azure Key Vault.

Determinare la versione dell'API usata

Specificare la versione dell'API in modo diverso a seconda della modalità di chiamata Key Vault. Controllare ogni superficie usata dal carico di lavoro.

Piano di controllo (gestione)

API REST: la versione è il parametro della api-version stringa di query sulle richieste a https://management.azure.com, ad esempio ?api-version=<control-plane-version>.
Modelli ARM, Bicep e Terraform: la versione è la proprietà apiVersion in ogni risorsa Microsoft.KeyVault/vaults. In Bicep fa parte della dichiarazione del tipo di risorsa, ad esempio resource kv 'Microsoft.KeyVault/vaults@2026-02-01'.
SDK di gestione del piano di controllo: la versione del pacchetto può determinare le versioni api supportate da un SDK, ma la sola versione del pacchetto non identifica sempre la versione api usata da una richiesta. Controllare le note sulla versione del pacchetto e le informazioni di riferimento sulle API (ad esempio, per Azure.ResourceManager.KeyVault o azure-mgmt-keyvault) e confrontarle con la versione del pacchetto nel manifesto delle dipendenze del progetto. Per informazioni di riferimento sulle API in base al linguaggio, vedere Azure Key Vault librerie client.
interfaccia della riga di comando di Azure e Azure PowerShell: la versione del modulo o Az del interfaccia della riga di comando di Azure determina la versione dell'API. Controllare la versione installata con az version o Get-InstalledModule -Name Az.
Portale di Azure: il portale seleziona la versione dell'API del piano di controllo per le proprie richieste. Non è possibile impostare direttamente tale versione. Il portale può usare una versione diversa dell'API rispetto a modelli, script o SDK, quindi non usare il comportamento del portale per determinare la versione usata dall'automazione.
Azure Cloud Shell: Cloud Shell usa le versioni correnti di interfaccia della riga di comando di Azure e Azure PowerShell. Se si eseguono script in Cloud Shell, assicurarsi che siano compatibili con la versione dell'API del piano di controllo attualmente supportata.

Piano di dati

API REST: la versione è il parametro di stringa di query api-version nelle richieste all'endpoint dell'insieme di credenziali, ad esempio GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>.
SDK del piano dati: la versione del pacchetto può determinare le versioni API supportate da un SDK, ma la sola versione del pacchetto non identifica sempre la versione dell'API usata da una richiesta. Controllare le note sulla versione del pacchetto e le informazioni di riferimento sulle API (ad esempio, per Azure.Security.KeyVault.Secrets, Azure.Security.KeyVault.Keyso Azure.Security.KeyVault.Certificates) e confrontarle con la versione del pacchetto nel manifesto delle dipendenze del progetto. Per informazioni di riferimento sulle API in base al linguaggio, vedere Azure Key Vault librerie client.