Udostępnij za pośrednictwem

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 2024-08-04 i zalecamy używanie 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 2024-08-04 obejmuje następujące funkcje:

Określanie wersji usługi w żądaniach

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

  • Żądania korzystające z tokenu OAuth 2.0 od firmy Microsoft Entra: aby autoryzować żądanie za pomocą identyfikatora Entra firmy Microsoft, przekaż x-ms-version nagłówek żądania do usługi 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 Authorize with Microsoft Entra ID (Wywoływanie operacji magazynowania przy użyciu tokenów OAuth w autoryzacji przy użyciu identyfikatora Entra firmy Microsoft).

  • Żądania używające klucza współużytkowanego lub klucza wspólnego Lite: aby autoryzować żądanie za pomocą klucza współużytkowanego lub klucza wspólnego Lite, przekaż x-ms-version nagłówek żądania. W przypadku usługi Azure Blob Storage można określić domyślną wersję dla wszystkich żądań, wywołując funkcję 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órej wersji usługi użyć do wykonania operacji interfejsu API. Wymagany SignedVersion (sv) parametr określa wersję usługi do użycia w celu autoryzowania żądania z sygnaturą dostępu współdzielonego. api-version Jeśli nagłówek nie jest 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 wersji do użycia dla żądania została opisana w następnych sekcjach.

Autoryzowanie żądań przy użyciu identyfikatora Entra firmy Microsoft, klucza wspólnego lub klucza wspólnego Lite

Aby autoryzować żądanie za pomocą identyfikatora Entra firmy Microsoft, klucza wspólnego lub klucza wspólnego Lite, określ x-ms-version nagłówek żądania. Wartość x-ms-version nagłówka żą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 do usług 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ślać nagłówek, chyba że ustawiono domyślną x-ms-version wersję, zgodnie z opisem w następnym akapicie.

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

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

Sygnatura dostępu współdzielonego 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, które jest wykonywane 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, , stsesigspsrspksrktn, epki erk są interpretowane przy użyciu określonej wersji.

Parametry protokołu REST, takie jak rscc, rscd, rsce, rscli rsct , są wymuszane przy użyciu wersji podanej w nagłówku parametru api-version . api-version Jeśli nagłówek nie zostanie określony, zostanie użyta wersja usługi podana dla SignedVersion polecenia .

Parametr api-version nie jest częścią nagłówka autoryzacji typu string-to-sign in the authorization, zgodnie z opisem w temacie Create a service SAS (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 metodę List Blobs 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 metodę List Blobs za pomocą sv=2015-04-05 parametru api-version i .

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 Storage platformy .NET 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, które są 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 ustawiania 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 ustawiania listy ACL kontenera , 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śla nagłówka x-ms-version , a domyślna wersja usługi nie została ustawiona przy użyciu ustawiania 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

W tej sekcji szczegółowo przedstawiono znane problemy dotyczące 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 wcześniejszej wersji interfejsu API REST, aby sprawdzić, czy problem został 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ż