Controllo delle versioni per Archiviazione di Azure

Archiviazione di Azure supporta più versioni. Per effettuare una richiesta ai servizi di archiviazione, è necessario specificare la versione da usare per tale operazione, a meno che la richiesta non sia anonima.

A partire dal 14 luglio 2025, l'ultima versione completamente distribuita del servizio di archiviazione di Azure è 2025-05-05. 2025-07-05 è anche ampiamente distribuito, come indicato nella tabella seguente. Tutte le versioni sono di qualità GA.

Se la tabella indica che è x-ms-version abilitato in una regione, vengono abilitati anche tutti i precedenti x-ms-versions . Il tentativo di usare una versione del servizio che non è completamente distribuita nell'area dell'account di archiviazione potrebbe generare un errore di mancata corrispondenza x-ms-version.

L'impostazione predefinita x-ms-version usata dagli SDK del piano dati di Archiviazione di Azure è disponibile nei log delle modifiche nella tabella seguente:

Gli SDK di archiviazione del piano dati non eseguono versioni disponibili a livello generale negli altri feed di pacchetti ufficiali fino a quando l'impostazione predefinita x-ms-version per la versione in questione non ha un'implementazione completa in tutte le aree. Pertanto, l'ultima versione di GA SDK dei gestori di pacchetti ufficiali può essere utilizzata in sicurezza in qualsiasi regione.

La versione più recente dei servizi di archiviazione di Azure è 2025-11-05 e si consiglia di usarla dove possibile. Per un elenco di tutte le altre versioni supportate e per informazioni sull'uso di ogni versione, vedere versioni precedenti del servizio archiviazione di Azure.

La versione del servizio 2025-11-05 include le seguenti funzionalità:

• Le API seguenti restituiscono x-ms-copy-source-status-code ora e x-ms-copy-source-error-code. Per ulteriori informazioni, vedere Codici di stato e di errore.
  • Copy Blob
  • Copiare un BLOB da un URL
  • Put Blob From URL
  • Posiziona blocco dall'URL
  • Inserisci pagina dall'URL
  • BLOB di copia incrementale
  • Aggiungi blocco da URL
  • Inserisci intervallo da URL
  • Copy File

Specificare le versioni del servizio nelle richieste

Il modo in cui si specifica la versione dei servizi di archiviazione da usare per una richiesta è correlata alla modalità di autorizzazione della richiesta. Le sezioni seguenti descrivono le opzioni di autorizzazione e il modo in cui viene specificata la versione del servizio per ognuna.

• Richieste che usano un token OAuth 2.0 da Microsoft Entra: per autorizzare una richiesta con MICROSOFT Entra ID, passare l'intestazione x-ms-version nella richiesta con una versione del servizio 2017-11-09 o successiva. Per altre informazioni, vedere Call storage operations with OAuth tokens in Authorize with Microsoft Entra ID.

• Richieste che usano chiave condivisa o chiave condivisa Lite: per autorizzare una richiesta con chiave condivisa o Chiave condivisa Lite, passare l'intestazione x-ms-version nella richiesta. Quando si usa Archiviazione BLOB di Azure, è possibile specificare la versione predefinita per tutte le richieste chiamando Set Blob Service Properties.

• Richieste che usano una firma di accesso condiviso (SAS): è possibile specificare due opzioni di controllo delle versioni in una firma di accesso condiviso. L'intestazione facoltativa api-version indica quale versione del servizio usare per eseguire l'operazione API. Il parametro SignedVersion (sv) obbligatorio specifica la versione del servizio da usare per autorizzare la richiesta effettuata con la firma di accesso condiviso. Se l'intestazione api-version non è specificata, il valore del parametro SignedVersion (sv) indica anche la versione da usare per eseguire l'operazione API.

• Richieste che usano l'accesso anonimo: quando si usa l'accesso anonimo nell'archiviazione BLOB, non viene passata alcuna versione. L'euristica per determinare quale versione usare per la richiesta sono descritte nelle sezioni successive.

Autorizzare le richieste usando Microsoft Entra ID, Shared Key o Shared Key Lite

Per autorizzare una richiesta con Microsoft Entra ID, Shared Key o Shared Key Lite, specificare l'intestazione x-ms-version nella richiesta. Il valore dell'intestazione della richiesta x-ms-version deve essere specificato nel formato AAAA-MM-GG. For example:

Request Headers:  
x-ms-version: 2020-04-08

Le regole seguenti descrivono come queste richieste vengono valutate per determinare quale versione usare per elaborare la richiesta.

• Se una richiesta ha un'intestazione di x-ms-version valida, il servizio di archiviazione usa la versione specificata. Tutte le richieste ad Archiviazione tabelle di Azure e Archiviazione code di Azure che non usano una firma di accesso condiviso devono specificare un'intestazione x-ms-version. Tutte le richieste all'archiviazione BLOB che non usano una firma di accesso condiviso devono specificare un'intestazione x-ms-version a meno che non sia impostata la versione predefinita, come descritto nel paragrafo successivo.

• Se una richiesta all'archiviazione BLOB non include un'intestazione x-ms-version , ma il proprietario dell'account imposta una versione predefinita usando l'operazione Set Blob Service Properties , la versione predefinita specificata viene usata come versione per la richiesta.

Autorizzare le richieste usando una firma di accesso condiviso

Una firma di accesso condiviso generata tramite la versione 2014-02-14 o successiva supporta due opzioni di controllo delle versioni:

• Il parametro di query api-version definisce la versione del protocollo REST da usare per l'elaborazione di una richiesta effettuata tramite la firma di accesso condiviso.

• Il parametro di query SignedVersion (sv) definisce la versione della firma di accesso condiviso da usare per l'autorizzazione.

Il parametro di query SignedVersion viene usato per l'autorizzazione quando un client effettua una richiesta usando la firma di accesso condiviso. I parametri di autorizzazione, ad esempio si, sr, sp, sig, st, se, tn, spk, srk, epke erk vengono interpretati usando la versione specificata.

I parametri del protocollo REST, ad esempio , , , rscc, , vengono rscd applicati utilizzando la versione fornita nell'intestazione del rsce parametro. rsclrsctapi-version Se l'intestazione api-version non è specificata, viene usata la versione del servizio fornita SignedVersion .

Il parametro api-version non fa parte della stringa per accedere all'intestazione di autorizzazione, come descritto in Creare una firma di accesso condiviso del servizio.

La tabella seguente illustra lo schema di controllo delle versioni usato dal servizio per l'autorizzazione e per chiamare il protocollo REST quando il parametro SignedVersion è impostato sulla versione 2014-02-14 o successiva.

Example 1

The following sample request calls List Blobs with sv=2015-04-05, and without the api-version parameter.

https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&sv=2015-04-05&si=readpolicy&sig=a39 %2BYozJhGp6miujGymjRpN8tsrQfLo9Z3i8IRyIpnQ%3d

In questo caso, il servizio autentica e autorizza la richiesta usando la versione 2015-04-05 ed esegue l'operazione usando la versione 2015-04-05.

Example 2

The following sample request calls List Blobs with sv=2015-04-05 and with the api-version parameter.

https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&sv=2015-04-05&si=readpolicy&sig=a39 %2BYozJhGp6miujGymjRpN8tsrQfLo9Z3i8IRyIpnQ%3d&api-version=2012-02-12

In questo caso, il servizio autorizza la richiesta usando la versione 2015-04-05 ed esegue l'operazione usando la versione 2012-02-12.

Richieste tramite accesso anonimo

Le richieste effettuate tramite accesso anonimo vengono gestite in modo diverso, a seconda del tipo di account di archiviazione in cui vengono effettuate.

Account di archiviazione per utilizzo generico

Se una richiesta anonima a un account di archiviazione per utilizzo generico non specifica l'intestazione x-ms-version e la versione predefinita per il servizio non viene impostata usando l'impostazione delle proprietà del servizio BLOB, il servizio usa la versione più breve possibile per elaborare la richiesta. Se il contenitore è stato reso pubblico utilizzando l'operazione Set Container ACL utilizzando la versione 2009-09-19 o successiva, la richiesta viene elaborata utilizzando la versione 2009-09-19.

Per gli account di archiviazione BLOB

Se una richiesta anonima a un account di archiviazione BLOB non specifica l'intestazione x-ms-version e la versione predefinita per il servizio non viene impostata usando l'impostazione delle proprietà del servizio BLOB, il servizio usa la versione più breve possibile per elaborare la richiesta. Per un account di archiviazione BLOB, la versione più recente possibile è 2014-02-14.

Known issues

Questa sezione descrive in dettaglio i problemi noti per le API REST di Archiviazione di Azure.

InvalidHeaderValue messaggio di errore

In rari scenari, le applicazioni che effettuano chiamate API REST dirette possono ricevere un messaggio di errore InvalidHeaderValue. L'errore è simile all'esempio seguente:

HTTP/1.1 400 The value for one of the HTTP headers is not in the correct format.
Content-Length: 328
Content-Type: application/xml
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: <REMOVED>
Date: Fri, 19 May 2023 17:10:33 GMT
 
<?xml version="1.0" encoding="utf-8"?><Error><Code>InvalidHeaderValue</Code><Message>The value for one of the HTTP headers is not in the correct format.
RequestId:<REMOVED>
Time:2023-05-19T17:10:34.2972651Z</Message><HeaderName>x-ms-version</HeaderName><HeaderValue>yyyy-mm-dd</HeaderValue></Error> 

Si consiglia di utilizzare una versione precedente dell'API REST per tentare di risolvere il problema. Se il problema persiste o se la raccomandazione non è fattibile, apri un ticket di supporto per discutere ulteriori opzioni.

See also

• REST di Servizi di archiviazione
• procedure consigliate per il controllo delle versioni
• supporto della versione del protocollo per le versioni della libreria client .NET