Controllo delle versioni per Archiviazione di Azure

  • Articolo

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.

La versione corrente dei servizi di archiviazione di Azure è 2024-11-04 ed è consigliabile usarla laddove 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 2024-11-04 include le funzionalità seguenti:

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. Nel caso di Archiviazione BLOB di Azure, è possibile specificare la versione predefinita per tutte le richieste chiamando Impostare le proprietà del servizio BLOB.

  • 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: nel caso dell'accesso anonimo all'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. Per esempio:

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 stata impostata la versione predefinita, come descritto nel paragrafo successivo.

  • Se una richiesta all'archiviazione BLOB non dispone di un'intestazione x-ms-version, ma il proprietario dell'account ha impostato una versione predefinita usando l'operazione Impostare le proprietà del servizio BLOB, 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, rscd, rsce, rscle rsct vengono applicati usando la versione fornita nell'intestazione del parametro api-version. Se l'intestazione api-version non è specificata, viene usata la versione del servizio fornita per 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.

Valore del parametro versione API Versione usata per l'autorizzazione Versione usata per il comportamento del protocollo
Non specificato Versione specificata nel parametro sv Versione specificata nel parametro sv
Qualsiasi versione valida dei servizi di archiviazione nel formato XXXX-XX-XX Versione specificata nel parametro sv Versione valida dei servizi di archiviazione XXXX-XX-XX

Esempio 1

La richiesta di esempio seguente chiama list BLOB con sv=2015-04-05e senza il parametro api-version.

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.

Esempio 2

La richiesta di esempio seguente chiama list BLOB con sv=2015-04-05 e con il parametro api-version.

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.

Nota

La libreria client di archiviazione .NET imposta sempre la versione del protocollo REST (nel parametro api-version) sulla versione su cui si basa.

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.

Per gli 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 è stata impostata usando Impostare le proprietà del servizio BLOB, il servizio usa la versione meno recente possibile per elaborare la richiesta. Tuttavia, se il contenitore è stato reso pubblico con un'operazione di Set Container ACL eseguita usando la versione 2009-09-19 o successiva, la richiesta viene elaborata usando 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 è stata impostata usando Impostare le proprietà del servizio BLOB, il servizio usa la versione meno recente possibile per elaborare la richiesta. Per un account di archiviazione BLOB, la versione più recente possibile è 2014-02-14.

Problemi noti

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>

È consigliabile usare una versione precedente dell'API REST per verificare se il problema viene risolto. Se il problema persiste o se la raccomandazione non è fattibile, aprire un ticket di supporto per discutere altre opzioni.

Vedere anche