Przechowywanie wersji dla usługi Azure Storage

  • Artykuł

Usługa Azure Storage obsługuje wiele wersji. Aby utworzyć żądanie względem usług magazynu, musisz określić wersję, której chcesz użyć dla tej operacji, chyba że żądanie jest anonimowe.

Bieżąca wersja usług Azure Storage to 2023-11-03 i zalecamy użycie jej tam, gdzie to możliwe. Aby uzyskać listę wszystkich innych obsługiwanych wersji oraz informacje o korzystaniu z każdej wersji, zobacz Poprzednie wersje usługi Azure Storage.

Wersja usługi 2023-11-03 obejmuje następujące funkcje:

  • Brak.

Określanie wersji usługi w żądaniach

Sposób określania wersji usług magazynu do użycia dla żądania odnosi się do sposobu autoryzacji tego żądania. W poniższych sekcjach opisano opcje autoryzacji i sposób określenia wersji usługi dla każdego z nich.

  • Żądania używające tokenu OAuth 2.0 z Microsoft Entra: aby autoryzować żądanie przy użyciu Tożsamość Microsoft Entra, przekaż x-ms-version nagłówek na żądanie z usługą w wersji 2017-11-09 lub nowszej. Aby uzyskać więcej informacji, zobacz Wywoływanie operacji magazynowania przy użyciu tokenów OAuth w temacie Autoryzowanie przy użyciu Tożsamość Microsoft Entra.

  • Żądania używające klucza współdzielonego lub klucza współdzielonego Lite: aby autoryzować żądanie z kluczem udostępnionym lub kluczem udostępnionym Lite, przekaż x-ms-version nagłówek na żądanie. W przypadku Azure Blob Storage można określić domyślną wersję dla wszystkich żądań, wywołując polecenie Ustaw właściwości usługi Blob Service.

  • Żądania korzystające z sygnatury dostępu współdzielonego (SAS): można określić dwie opcje przechowywania wersji w sygnaturze dostępu współdzielonego. Opcjonalny api-version nagłówek wskazuje, która wersja usługi ma być używana do wykonania operacji interfejsu API. Wymagany SignedVersion (sv) parametr określa wersję usługi do użycia w celu autoryzowania żądania wykonanego z sygnaturą dostępu współdzielonego. api-version Jeśli nagłówek nie zostanie określony, wartość parametru SignedVersion (sv) wskazuje również wersję używaną do wykonania operacji interfejsu API.

  • Żądania korzystające z dostępu anonimowego: w przypadku dostępu anonimowego do usługi Blob Storage nie jest przekazywana żadna wersja. Heurystyka określania, która wersja do użycia dla żądania jest opisana w następnych sekcjach.

Autoryzowanie żądań przy użyciu Tożsamość Microsoft Entra, klucza wspólnego lub klucza wspólnego Lite

Aby autoryzować żądanie za pomocą Tożsamość Microsoft Entra, klucza wspólnego lub klucza współdzielonego Lite, określ x-ms-version nagłówek żądania. Wartość nagłówka x-ms-version żądania musi być określona w formacie RRRR-MM-DD. Na przykład:

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

W poniższych regułach opisano sposób oceniania tych żądań w celu określenia, która wersja ma być używana do przetwarzania żądania.

  • Jeśli żądanie ma prawidłowy x-ms-version nagłówek, usługa magazynu używa określonej wersji. Wszystkie żądania usługi Azure Table Storage i Azure Queue Storage, które nie używają sygnatury dostępu współdzielonego, muszą określać x-ms-version nagłówek. Wszystkie żądania do usługi Blob Storage, które nie używają sygnatury dostępu współdzielonego, muszą określić nagłówek, chyba że została ustawiona domyślna wersja, zgodnie z opisem x-ms-version w następnym akapicie.

  • Jeśli żądanie do usługi Blob Storage nie ma x-ms-version nagłówka, ale właściciel konta ustawił domyślną wersję przy użyciu operacji Ustaw właściwości usługi Blob Service , określona wersja domyślna jest używana jako wersja żądania.

Autoryzowanie żądań przy użyciu sygnatury dostępu współdzielonego

Sygnatura dostępu współdzielonego (SAS) wygenerowana przy użyciu wersji 2014-02-14 lub nowszej obsługuje dwie opcje przechowywania wersji:

  • Parametr api-version zapytania definiuje wersję protokołu REST do użycia do przetwarzania żądania wykonanego przy użyciu sygnatury dostępu współdzielonego.

  • Parametr SignedVersion (sv) zapytania definiuje wersję sygnatury dostępu współdzielonego do użycia na potrzeby autoryzacji.

Parametr SignedVersion zapytania jest używany do autoryzacji, gdy klient wysyła żądanie przy użyciu sygnatury dostępu współdzielonego. Parametry autoryzacji, takie jak si, sigstsespsrspksrktnepki erk są interpretowane przy użyciu określonej wersji.

Parametry protokołu REST, takie jak rscc, , rsclrscdrsce, i rsct są wymuszane przy użyciu wersji podanej w nagłówku parametruapi-version. api-version Jeśli nagłówek nie jest określony, używana jest wersja usługi podana dlaSignedVersion.

Parametr api-version nie jest częścią nagłówka autoryzacji ciągu do logowania, zgodnie z opisem w temacie Tworzenie sygnatury dostępu współdzielonego usługi.

W poniższej tabeli wyjaśniono schemat przechowywania wersji używany przez usługę do autoryzacji i wywoływania protokołu REST, gdy SignedVersion parametr jest ustawiony na wersję 2014-02-14 lub nowszą.

Wartość parametru api-version Wersja używana do autoryzacji Wersja używana do zachowania protokołu
Nie określono Wersja określona w parametrze sv Wersja określona w parametrze sv
Dowolna prawidłowa wersja usług magazynu w formacie XXXX-XX-XX Wersja określona w parametrze sv Prawidłowa wersja usług magazynu XXXX-XX-XX

Przykład 1

Następujące przykładowe żądanie wywołuje wywołania listy obiektów blob z parametrem sv=2015-04-05i bez parametru api-version .

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

W takim przypadku usługa uwierzytelnia i autoryzuje żądanie przy użyciu wersji 2015-04-05 i uruchamia operację przy użyciu wersji 2015-04-05.

Przykład 2

Następujące przykładowe żądanie wywołuje wywołania listy obiektów blob z parametrem sv=2015-04-05 i z parametrem 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

W tym miejscu usługa autoryzuje żądanie przy użyciu wersji 2015-04-05 i uruchamia operację przy użyciu wersji 2012-02-12.

Uwaga

Biblioteka klienta usługi .NET Storage zawsze ustawia wersję protokołu REST (w parametrze api-version ) na wersję, na podstawie którego jest oparta.

Żądania za pośrednictwem dostępu anonimowego

Żądania wykonywane za pośrednictwem dostępu anonimowego są obsługiwane inaczej, w zależności od typu konta magazynu, względem którego są wykonywane.

W przypadku kont magazynu ogólnego przeznaczenia

Jeśli anonimowe żądanie do konta magazynu ogólnego przeznaczenia nie określa x-ms-version nagłówka, a domyślna wersja usługi nie została ustawiona przy użyciu opcji Ustaw właściwości usługi Blob Service, usługa używa najwcześniejszej możliwej wersji do przetworzenia żądania. Jeśli jednak kontener został upubliczniony za pomocą operacji Set Container ACL , która została wykonana przy użyciu wersji 2009-09-19 lub nowszej, żądanie jest przetwarzane przy użyciu wersji 2009-09-19.

W przypadku kont usługi Blob Storage

Jeśli anonimowe żądanie do konta usługi Blob Storage nie określi x-ms-version nagłówka, a domyślna wersja usługi nie została ustawiona przy użyciu opcji Ustaw właściwości usługi Blob Service, usługa używa najwcześniejszej możliwej wersji do przetworzenia żądania. W przypadku konta usługi Blob Storage najwcześniejsza możliwa wersja to 2014-02-14.

Znane problemy

Ta sekcja zawiera szczegółowe informacje o znanych problemach dotyczących interfejsów API REST usługi Azure Storage.

InvalidHeaderValue Komunikat o błędzie

W rzadkich scenariuszach aplikacje wykonujące bezpośrednie wywołania interfejsu API REST mogą otrzymywać InvalidHeaderValue komunikat o błędzie. Błąd wygląda podobnie do następującego przykładu:

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>

Zaleca się użycie starszej wersji interfejsu API REST, aby sprawdzić, czy problem zostanie rozwiązany. Jeśli problem będzie się powtarzać lub jeśli zalecenie nie jest możliwe, otwórz bilet pomocy technicznej , aby omówić dalsze opcje.

Zobacz też