Przechowywanie wersji dla usługi Azure Storage

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

Na dzień 5 stycznia 2026 roku najnowsza w pełni wdrożona wersja usługi Azure Storage to , która jest 2026-02-06wspierana przez najnowsze pakiety beta i GA Azure Storage SDK.

Jeśli tabela wskazuje, że w regionie jest włączona, x-ms-version wszystkie poprzednie x-ms-versions są również włączone. Próba użycia wersji usługi, która nie jest w pełni wdrożona w regionie konta magazynu, może wygenerować błąd niezgodności x-ms-version.

Wartość domyślną x-ms-version używaną przez zestawy SDK płaszczyzny danych usługi Azure Storage można znaleźć w dziennikach zmian w poniższej tabeli:

Zestawy SDK magazynu płaszczyzny danych nie wykonują wydań ogólnie dostępnych do innych oficjalnych kanałów informacyjnych pakietów, dopóki ustawienie domyślne x-ms-version danej wersji nie zostanie w pełni wdrożone we wszystkich regionach. W związku z tym najnowsza wersja GA SDK z oficjalnych menedżerów pakietów może być bezpiecznie używana w dowolnym regionie.

Najnowsza wersja usług przechowywania danych Azure to 2026-02-06 i zalecamy korzystanie z niej, gdzie to możliwe. Aby uzyskać listę wszystkich innych obsługiwanych wersji oraz informacje na temat korzystania z każdej wersji, zobacz Poprzednie wersje usługi Azure Storage.

Wersja serwisowa z 2026-02-06 zawiera następujące funkcje:

• Dodano wsparcie dla <EncryptionInTransit> właściwości usługi plików oraz ustaw właściwości usługi plików.

Określanie wersji usługi w żądaniach

Sposób określania wersji usług magazynu, które mają być używane 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 używające tokenu OAuth 2.0 z witryny Microsoft Entra: Aby autoryzować żądanie za pomocą identyfikatora Entra firmy Microsoft, przekaż nagłówek x-ms-version na żądanie przy użyciu wersji usługi 2017-11-09 lub nowszej. Aby uzyskać więcej informacji, zobacz Call storage operations with OAuth tokens in Authorize with Microsoft Entra ID.

• żądania używające klucza współużytkowanego lub klucza współużytkowanego: Aby autoryzować żądanie za pomocą klucza współużytkowanego lub klucza współużytkowanego Lite, przekaż nagłówek x-ms-version na żądanie. W przypadku korzystania z Azure Blob Storage można określić domyślną wersję dla wszystkich żądań, wywołując polecenie Set Blob Service Properties.

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

• Żądania korzystające z dostępu anonimowego: w przypadku korzystania z dostępu anonimowego do usługi Blob Storage nie jest przekazywana żadna wersja. Heurystyka określania wersji, która ma być używana 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ółużytkowanego lub klucza wspólnego Lite, określ nagłówek x-ms-version żądania. Wartość nagłówka żądania x-ms-version musi być określona w formacie RRRR-MM-DD. Przykład:

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

Poniższe reguły opisują 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 nagłówek x-ms-version, usługa magazynu używa określonej wersji. Wszystkie żądania usług Azure Table Storage i Azure Queue Storage, które nie używają sygnatury dostępu współdzielonego, muszą określać nagłówek x-ms-version. Wszystkie żądania do usługi Blob Storage, które nie używają sygnatury dostępu współdzielonego x-ms-version , muszą określać nagłówek, chyba że ustawiono wersję domyślną, zgodnie z opisem w następnym akapicie.

• Jeśli żądanie do usługi Blob Storage nie zawiera nagłówka x-ms-version , ale właściciel konta ustawia wersję domyślną 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 zapytania api-version definiuje wersję protokołu REST do użycia do przetwarzania żądania, które jest wykonywane przy użyciu sygnatury dostępu współdzielonego.

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

Parametr zapytania SignedVersion jest używany do autoryzacji, gdy klient wysyła żądanie przy użyciu sygnatury dostępu współdzielonego. Parametry autoryzacji, takie jak si, sr, sp, sig, st, se, tn, spk, srk, epki erk są interpretowane przy użyciu określonej wersji.

Parametry protokołu REST, takie jak , , , , i rscc są wymuszane przy użyciu wersji podanej w nagłówku parametrurscd. rscersclrsctapi-version api-version Jeśli nagłówek nie zostanie określony, zostanie użyta wersja SignedVersion usługi.

Parametr api-version nie jest częścią nagłówka autoryzacji typu ciąg-logowanie, zgodnie z opisem w 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 parametr SignedVersion jest ustawiony na wersję 2014-02-14 lub nowszą.

Przykład 1

Poniższe przykładowe żądanie wywołuje List Blobs z parametrem sv=2015-04-05i bez api-version parametru.

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

Poniższe przykładowe żądanie wywołuje List Blobs 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.

Żą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.

Konta magazynu ogólnego przeznaczenia

Jeśli anonimowe żądanie do konta magazynu ogólnego przeznaczenia nie określa nagłówka x-ms-version , a domyślna wersja usługi nie jest ustawiona przy użyciu polecenia Ustaw właściwości usługi Blob Service, usługa używa najwcześniejszej możliwej wersji do przetworzenia żądania. Jeśli kontener został upubliczniony przy użyciu operacji Ustaw listę ACL kontenera 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 jest ustawiona przy użyciu polecenia 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 z interfejsami API REST usługi Azure Storage.

komunikat o błędzie InvalidHeaderValue

W rzadkich scenariuszach aplikacje wykonujące bezpośrednie wywołania interfejsu API REST mogą odbierać komunikat o błędzie InvalidHeaderValue. 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 w celu rozwiązania problemu. Jeśli problem się utrzymuje lub jeśli rekomendacja nie jest wykonalna, otwórz zgłoszenie do wsparcia , aby omówić dalsze opcje.

Zobacz także

• Usługi pamięci masowej REST
• najlepsze rozwiązania dotyczące przechowywania wersji
• obsługa wersji protokołu dla wersji bibliotek klienta platformy .NET