Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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 |
|---|---|---|---|
| Control plane (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 su data, ad esempio 2026-02-01. Le versioni di anteprima aggiungono un -preview suffisso, ad esempio 2026-03-01-preview. |
https://management.azure.com |
| data plane | Oggetti contenuti in un insieme di credenziali: chiavi, segreti, certificati e operazioni crittografiche. | Basato sulla data, ad esempio 2026-04-01, o numerico, ad esempio 7.6. Le versioni di anteprima aggiungono un suffisso, ad esempio 2026-03-01-preview o 7.6-preview.2. |
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.
Poiché entrambi i piani usano versioni basate sulla data, una stringa di versione da sola non identifica il piano. Ad esempio, sia il piano di controllo che il piano dati hanno una 2026-03-01-preview versione.
È 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.
Identificare le chiamate API interessate usando i log
Un avviso del servizio non significa necessariamente che i dati di telemetria hanno rilevato una versione dell'API ritirata in ogni sottoscrizione o Key Vault di cui si è proprietari. Gli avvisi possono raggiungere un pubblico più ampio rispetto alle risorse rilevate nei dati di telemetria recenti.
Usare i log di controllo di Key Vault per individuare gli insiemi di credenziali e le operazioni che usavano una versione dell'API in dismissione. Individuare quindi il percorso in cui il codice, i modelli o gli strumenti impostano tale versione, come descritto in Trovare i riferimenti alla versione dell'API nel codice e nei flussi di lavoro e aggiornare la versione dell'API.
Raccogliere Key Vault log di controllo
Inviare i log di controllo per ogni Key Vault da analizzare a un'area di lavoro Log Analytics. Per la procedura, vedere Abilitare la registrazione di Key Vault. Per configurare più insiemi di credenziali contemporaneamente, vedere Creare impostazioni di diagnostica su larga scala usando Criteri di Azure predefinita. Usare un'area di lavoro per questi insiemi di credenziali in modo che sia possibile eseguirne una query insieme.
Configurare la registrazione in anticipo. I registri includono solo le richieste effettuate dopo l'applicazione dell'impostazione di diagnostica e le richieste precedenti non vengono aggiunte retroattivamente. Dopo aver creato un'impostazione di diagnostica, la visualizzazione dei dati può richiedere fino a 90 minuti. Per altre informazioni, vedere Latenza prevista dopo la creazione di un'impostazione di diagnostica.
Gli eventi di audit includono sia operazioni del piano di controllo che del piano dati, ma questo ritiro influisce solo sulle operazioni del piano di controllo.
Il log attività Azure non registra la versione api di una richiesta, quindi usa i log di controllo di Key Vault per trovare le richieste che usano una versione in fase di ritiro.
Per verificare che i record arrivino, eseguire la query seguente nell'area di lavoro. Per altre informazioni sull'esecuzione di query, vedere esercitazione di Log Analytics.
AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| order by TimeGenerated desc
| take 50
Controllare _ResourceId e TimeGenerated per verificare che i record arrivino dagli insiemi di credenziali previsti. Per controllare un Key Vault che non si trova nelle ultime 50 righe, filtrare in base a _ResourceId prima di order by.
Se manca una tabella o la query non restituisce alcun record, controllare nuovamente l'area di lavoro, l'impostazione di diagnostica salvata, il Key Vault di origine, l'ambito della query, l'intervallo di tempo e le autorizzazioni. Se l'impostazione di diagnostica invia i log alle tabelle specifiche delle risorse, eseguire una query sulla AZKVAuditLogs tabella, come descritto alla fine della sezione successiva.
Trovare le richieste che usano una versione dell'API in dismissione
Importante
I log includono solo le richieste ricevute da un Key Vault mentre l'impostazione di diagnostica è attiva e solo entro l'intervallo di tempo su cui si esegue la query. Se le query non restituiscono richieste corrispondenti, ciò non significa che non si è immuni. Ad esempio, i log non mostrano le richieste che hanno creato insiemi di credenziali anni fa, anche se i modelli o gli script che hanno creato tali insiemi di credenziali specificano ancora una versione in dismissione. Esaminare sempre il codice dell'applicazione, i modelli di distribuzione, gli script di automazione e altri flussi di lavoro per i riferimenti a una versione dell'API in dismissione.
Le query seguenti restituiscono solo le richieste del piano di controllo filtrando in base all'endpoint Azure Resource Manager nell'URI della richiesta. Le richieste del piano dati passano invece all'endpoint del vault, ad esempio https://<vault-name>.vault.azure.net. Le query usano l'endpoint per Azure cloud pubblico. Per altri cloud, sostituire https://management.azure.com/ con l'endpoint per il tuo cloud:
| Cloud | endpoint Azure Resource Manager |
|---|---|
| Cloud pubblico di Azure | https://management.azure.com/ |
| Azure per enti pubblici | https://management.usgovcloudapi.net/ |
| Azure gestito da 21Vianet | https://management.chinacloudapi.cn/ |
Altri cloud usano il proprio endpoint Azure Resource Manager.
Le query filtrano sull'endpoint perché alcune versioni dell'API del piano dati usano lo stesso formato basato su data delle versioni del piano di controllo. Ad esempio, il piano dati ha anche una 2026-03-01-preview versione. Per i nomi delle operazioni che Key Vault registra, vedere Tabella Nomi operazioni.
Per elencare gli insiemi di credenziali che hanno ricevuto richieste del piano di controllo con una versione API precedente a 2026-02-01, eseguire la query seguente. Restituisce una riga per ogni insieme di credenziali delle chiavi e versione dell'API, con il numero di richieste, la richiesta più recente e le operazioni richieste.
AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where requestUri_s startswith "https://management.azure.com/"
| where strcmp(OperationVersion, "2026-02-01") < 0
| summarize Requests = count(), LastSeen = max(TimeGenerated), Operations = make_set(OperationName) by _ResourceId, OperationVersion
| order by Requests desc
Per analizzare le singole richieste, usare una delle query seguenti.
Per trovare le richieste che usano una specifica versione in dismissione, ad esempio 2026-03-01-preview, filtrare in base a tale versione:
AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where requestUri_s startswith "https://management.azure.com/"
| where OperationVersion == "2026-03-01-preview"
| order by TimeGenerated desc
Per trovare le richieste che usano qualsiasi versione dell'API del piano di controllo precedente a 2026-02-01, filtrare in base alle versioni che precedono 2026-02-01:
AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where requestUri_s startswith "https://management.azure.com/"
| where strcmp(OperationVersion, "2026-02-01") < 0
| order by TimeGenerated desc
Le query in questo articolo usano la tabella AzureDiagnostics, che riceve i log di controllo di Key Vault quando la tabella di destinazione dell'impostazione di diagnostica è Azure diagnostics. Se la tabella di destinazione è specifica della risorsa, i log di controllo passano invece alla AZKVAuditLogs tabella. In tal caso, modificare ogni query in questo articolo, incluso il controllo raccolta: sostituire AzureDiagnostics con AZKVAuditLogs, rimuovere i ResourceProvider filtri e Category e sostituire requestUri_s con RequestUri. Ad esempio, la query relativa agli insiemi di credenziali interessati diventa:
AZKVAuditLogs
| where TimeGenerated >= ago(30d)
| where RequestUri startswith "https://management.azure.com/"
| where strcmp(OperationVersion, "2026-02-01") < 0
| summarize Requests = count(), LastSeen = max(TimeGenerated), Operations = make_set(OperationName) by _ResourceId, OperationVersion
| order by Requests desc
Non filtrare in base ai nomi delle operazioni che iniziano con Vault, perché tale filtro può escludere le operazioni delle risorse figlio registrate. Usare OperationName e l'URI della richiesta per comprendere quale operazione di gestione si è verificata. Usare i dettagli in questi log per identificare il chiamante. Individuare quindi dove il chiamante imposta la versione dell'API, come descritto nella sezione successiva e aggiornarlo come descritto in Aggiornare la versione dell'API.
Trovare riferimenti alla versione dell'API nel codice e nei flussi di lavoro
La posizione in cui si imposta la versione dell'API dipende dalla modalità con cui si chiama Key Vault. Controllare ogni metodo che il carico di lavoro utilizza, anche se i log non visualizzano richieste da esso.
Piano di controllo (gestione)
-
API REST: la versione è il parametro della
api-versionstringa di query sulle richieste ahttps://management.azure.com, ad esempio?api-version=<control-plane-version>. -
Modelli di Resource Manager e file Bicep: la versione è la proprietà
apiVersionin ogni risorsaMicrosoft.KeyVault/vaults. In Bicep fa parte della dichiarazione del tipo di risorsa, ad esempioresource kv 'Microsoft.KeyVault/vaults@2026-02-01'. Le risorse figlio, ad esempioMicrosoft.KeyVault/vaults/secrets,Microsoft.KeyVault/vaults/keyseMicrosoft.KeyVault/vaults/accessPoliciessono anche risorse del piano di controllo e ognuna dichiara la propria versione dell'API. L'aggiornamento della versione dell'insieme di credenziali padre non aggiorna le risorse figlio. -
Terraform: con il provider AzAPI, la versione fa parte del tipo di risorsa, ad esempio
Microsoft.KeyVault/vaults@2026-02-01. Con il provider AzureRM, la versione del provider determina la versione dell'API e le risorse non hanno un'impostazione della versione dell'API. Controllare le note sulla versione del provider e la documentazione delle risorse per la versione dell'API usata dalla versione del provider. -
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.KeyVaultoazure-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 di interfaccia della riga di comando di Azure o del modulo
Azdetermina la versione dell'API. Controllare la versione installata con az version o Get-InstalledModule -Name Az. -
Azure portal: il portale seleziona la versione dell'API del piano di controllo per le richieste. Non è possibile impostare direttamente tale versione. Il portale usa la versione
2026-02-01dell'API, quindi le operazioni del portale non usano una versione ritirata. 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 della
api-versionstringa di query nelle richieste all'endpoint del vault, ad esempioGET 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.KeysoAzure.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.
Aggiornare la versione dell'API
Aggiornare la versione dell'API del piano di controllo
Aggiornare la versione dell'API nei modelli e nelle chiamate REST. Impostare
apiVersion(ARM, Bicep), il tipo di risorsa con versione (Terraform AzAPI) o ilapi-versionparametro della stringa di query (REST) su una versione del piano di controllo attualmente supportata. Aggiornare tutte le definizioniMicrosoft.KeyVault/vaults, le relative risorse figlio e le richieste di gestione. Se si usa il provider Terraform AzureRM, aggiornare il provider a una versione che usa una versione dell'API del piano di controllo supportata.Aggiornare gli SDK di gestione del piano di controllo. Controllare le note sulla versione del pacchetto e le informazioni di riferimento sulle API per la versione del pacchetto che supporta la versione dell'API del piano di controllo selezionata. Per informazioni di riferimento sulle API per linguaggio e sulle versioni dei pacchetti che supportano la versione corrente del control plane di Key Vault, vedere librerie client di Azure Key Vault e release dell'SDK del control plane.
Note
L'aggiornamento di un SDK di gestione del piano di controllo non aggiorna gli SDK del piano dati. Aggiornare ogni SDK separatamente se l'applicazione usa entrambe le superfici API.
Aggiornare interfaccia della riga di comando di Azure e Azure PowerShell. Le versioni più recenti degli strumenti richiamano le versioni più recenti delle API.
- interfaccia della riga di comando di Azure
- Azure PowerShell
Aggiornare l'interfaccia della riga di comando di Azure alla versione più recente. Per altre informazioni, vedere Come aggiornare il interfaccia della riga di comando di Azure.
- Esaminare le modifiche del comportamento prima della distribuzione. Leggere il log delle modifiche e la specifica della versione dell'API prima della distribuzione. La versione
2026-02-01dell'API e quelle successive modificano il modello predefinito di controllo di accesso solo per i nuovi insiemi di credenziali. Per i dettagli, vedi Pianificare Azure RBAC come modello predefinito di controllo di accesso in Key Vault.
Aggiornare la versione dell'API del piano dati
Aggiornare la versione dell'API nelle chiamate REST. Imposta il parametro di stringa di query
api-versionsu una versione del piano dati attualmente supportata tra quelle elencate nella documentazione di riferimento dell'API REST di Azure Key Vault.Aggiorna gli SDK del piano di dati. Aggiorna i pacchetti
Azure.Security.KeyVault.*(o l'equivalente nella tua lingua) a una versione stabile attuale. Verifica le note di rilascio del pacchetto e la documentazione di riferimento dell'API per determinare quali versioni dell'API del piano dati sono supportate dal pacchetto. Per i riferimenti alle API e i collegamenti ai pacchetti per linguaggio, vedere librerie client di Azure Key Vault.
Le versioni stabili dell'API del piano dati non sono interessate dall'attuale disattivazione del piano di controllo. Se si usa un'API in anteprima del piano dati, consultare gli annunci del servizio e la documentazione di riferimento dell'API per conoscerne il ciclo di vita.
Per altre informazioni sulla chiamata all'API REST del piano dati, vedere Autenticazione, richieste e risposte e informazioni di riferimento sull'API REST Azure Key Vault.
Contenuti correlati
- Pianificare il controllo degli accessi in base al ruolo di Azure come modello di controllo di accesso predefinito in Key Vault
- Eseguire la migrazione ad Azure RBAC dai criteri di accesso
- Novità di Azure Key Vault
- Versioni DELL'API del piano di controllo supportate
- Autenticazione, richieste e risposte
- librerie client Azure Key Vault
- Guida per sviluppatori di Azure Key Vault
- Informazioni di riferimento sulle API REST Azure Key Vault