Controllo delle versioni per Archiviazione di Azure

Archiviazione di Azure supporta più versioni. Per fare una richiesta per i servizi di archiviazione, è necessario specificare la versione che si desidera usare per l'operazione, a meno che la richiesta non sia anonima.

La versione corrente dei servizi di archiviazione di Azure è 2023-11-03 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 2023-11-03 include le funzionalità seguenti:

  • Nessuno.

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 sulla richiesta con una versione del servizio 2017-11-09 o successiva. Per altre informazioni, vedere Chiamare le operazioni di archiviazione con token OAuth in Autorizzare con 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 sulla richiesta. Nel caso di Archiviazione BLOB di Azure, è possibile specificare la versione predefinita per tutte le richieste chiamando Imposta proprietà del servizio BLOB.

  • Richieste che usano una firma di accesso condiviso: è possibile specificare due opzioni di controllo delle versioni in una firma di accesso condiviso. L'intestazione facoltativa api-version indica la versione del servizio da usare per eseguire l'operazione API. Il parametro obbligatorio SignedVersion (sv) 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 SignedVersion (sv) parametro indica anche la versione da usare per eseguire l'operazione API.

  • Richieste che usano l'accesso anonimo: in caso di accesso anonimo all'archiviazione BLOB, non viene passata alcuna versione. Le euristiche per determinare la versione da usare per la richiesta sono descritte nelle sezioni successive.

Autorizzare le richieste usando Microsoft Entra ID, chiave condivisa o Chiave condivisa Lite

Per autorizzare una richiesta con Microsoft Entra ID, chiave condivisa o Chiave condivisa 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. Ad esempio:

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

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

  • Se una richiesta presenta un'intestazione x-ms-version valida, il servizio di archiviazione utilizza 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 ha un'intestazione x-ms-version , ma il proprietario dell'account ha impostato una versione predefinita usando l'operazione Imposta proprietà 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 api-version parametro di query definisce la versione del protocollo REST da usare per l'elaborazione di una richiesta effettuata tramite la firma di accesso condiviso.

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

Il SignedVersion parametro di query viene usato per l'autorizzazione quando un client effettua una richiesta usando la firma di accesso condiviso. I parametri di autorizzazione, siad esempio , sr, sigsp, st, tnsrkspkse, epk, e erk vengono interpretati usando la versione specificata.

I parametri del protocollo REST, ad esempio rscc, rscdrsce, rscl, e rsct vengono applicati usando la versione fornita nell'intestazione del api-version parametro. Se l'intestazione api-version non è specificata, viene usata la versione del servizio fornita per SignedVersion .

Il api-version parametro 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 SignedVersion parametro è impostato sulla versione 2014-02-14 o successiva.

Valore del parametro api-version Versione usata per l'autorizzazione Versione utilizzata 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 elencare i BLOB con sv=2015-04-05e senza il api-version parametro .

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 BLOBs con sv=2015-04-05 e con il api-version parametro .

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 api-version protocollo REST (nel parametro ) 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 a 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 tramite Imposta proprietà servizio BLOB, il servizio usa la versione meno recente possibile per elaborare la richiesta. Tuttavia, se il contenitore è stato reso pubblico con un'operazione 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 tramite Imposta proprietà 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 illustra i problemi noti relativi alle API REST di Archiviazione di Azure.

InvalidHeaderValue messaggio di errore

In rari scenari, le applicazioni che effettuano chiamate API REST dirette possono ricevere un InvalidHeaderValue messaggio di errore. 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.

Vedi anche