Udostępnij za pośrednictwem

Przechowywanie wersji dla usługi Azure Storage

  • Artykuł

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.

Bieżąca wersja usług Azure Storage to 2024-11-04 i zalecamy, aby używać jej tam, 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 usługi 2024-11-04 obejmuje następujące funkcje:

  • Obsługa uwierzytelniania opartego na tokenach dla wszystkich interfejsów API płaszczyzny danych w usłudze plików. Aby uzyskać więcej informacji, zobacz Authorize with Microsoft Entra ID.
  • Obsługa płatnych wzrostów liczby kont udziałów plików w warstwie Premium. Tę funkcję można włączyć za pomocą interfejsów API Create Share i Set Share Properties API.
  • Obsługa formatu binarnego podczas pobierania i ustawiania uprawnień do pliku w usłudze plików. Aby uzyskać więcej informacji, zobacz Tworzenie uprawnień i Uzyskiwanie uprawnień

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 usługi Azure Blob Storage można określić domyślną wersję dla wszystkich żądań, wywołując Ustaw właściwości usługi Blob Service.

  • Żą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 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. Na 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, muszą określić nagłówek x-ms-version, chyba że została ustawiona domyślna wersja, 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 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 rscc, rscd, rsce, rscli rsct, są wymuszane przy użyciu wersji podanej w nagłówku parametru api-version. Jeśli nagłówek api-version nie jest określony, używana jest wersja usługi podana dla SignedVersion.

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

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 List Blobs z 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 List Blobs z sv=2015-04-05 i 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.

Nuta

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, 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 nagłówka x-ms-version, a domyślna wersja usługi nie została ustawiona przy użyciu 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 przy użyciu Set Container ACL operacji, 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 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, aby sprawdzić, czy problem zostanie rozwiązany. Jeśli problem będzie się powtarzać lub jeśli zalecenie nie jest możliwe, otworzyć bilet pomocy technicznej w celu omówienia dalszych opcji.

Zobacz też