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 è 2024-08-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-08-04 include le funzionalità seguenti:
-
Creare condivisione e impostare le proprietà di condivisione ora supportano l'intestazione della
x-ms-enable-snapshot-virtual-directory-access
richiesta. Questa proprietà viene ora restituita come intestazione di risposta da Get Share Properties e come elementoEnableSnapshotVirtualDirectoryAccess
XML restituito da List Shares. - I corpi di risposta agli errori correlati all'autenticazione conterranno ora l'elemento
ExtendedErrorDetail
xml, fornendo più contesto per l'errore di autenticazione. Per altre informazioni, vedere Codici di stato e errore
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 l'ID Microsoft Entra, 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 l'ID Microsoft Entra.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 obbligatorioSignedVersion (sv)
specifica la versione del servizio da usare per autorizzare la richiesta effettuata con la firma di accesso condiviso. Se l'intestazioneapi-version
non è specificata, il valore delSignedVersion (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, 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. 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'intestazionex-ms-version
. Tutte le richieste all'archiviazione BLOB che non usano una firma di accesso condiviso devono specificare un'intestazionex-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, si
ad esempio , sr
, sig
sp
, st
, tn
srk
spk
se
, epk
, e erk
vengono interpretati usando la versione specificata.
I parametri del protocollo REST, ad esempio rscc
, rscd
rsce
, 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-05
e 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.