Správa verzí pro Azure Storage
Azure Storage podporuje více verzí. Pokud chcete provést požadavek na služby Storage a tento požadavek není anonymní, musíte zadat verzi, kterou pro danou operaci chcete použít.
Aktuální verze služeb Azure Storage je 2023-11-03 a doporučujeme ji používat tam, kde je to možné. Seznam všech ostatních podporovaných verzí a informace o používání jednotlivých verzí najdete v tématu Předchozí verze služby Azure Storage.
Verze služby z 3. 11. 2023 obsahuje následující funkce:
- Žádné
Určení verzí služby v požadavcích
Způsob, jakým určíte verzi služeb úložiště, které se mají použít pro požadavek, souvisí s tím, jak je daný požadavek autorizován. Následující části popisují možnosti autorizace a způsob určení verze služby pro každou z nich.
Požadavky, které používají token OAuth 2.0 z Microsoft Entra: Pokud chcete autorizovat požadavek s Microsoft Entra ID, předejte
x-ms-versionhlavičku žádosti s verzí služby z 9. 11. 2017 nebo vyšší. Další informace najdete v tématu Volání operací úložiště s tokeny OAuth v tématu Autorizace s Microsoft Entra ID.Požadavky, které používají sdílený klíč nebo sdílený klíč Lite: Pokud chcete žádost autorizovat pomocí sdíleného klíče nebo sdíleného klíče Lite, předejte hlavičku
x-ms-versionpožadavku. V případě Azure Blob Storage můžete určit výchozí verzi pro všechny požadavky voláním nastavení vlastností služby Blob Service.Žádosti, které používají sdílený přístupový podpis (SAS): U sdíleného přístupového podpisu můžete zadat dvě možnosti správy verzí. Volitelná
api-versionhlavička označuje verzi služby, která se má použít ke spuštění operace rozhraní API. PožadovanýSignedVersion (sv)parametr určuje verzi služby, která se má použít k autorizaci požadavku vytvořeného pomocí SAS. Pokud není hlavičkaapi-versionzadaná, hodnota parametruSignedVersion (sv)také označuje verzi, která se má použít k provedení operace rozhraní API.Požadavky, které používají anonymní přístup: V případě anonymního přístupu ke službě Blob Storage se nepředá žádná verze. Heuristika pro určení verze, která se má použít pro požadavek, jsou popsány v dalších částech.
Autorizace požadavků pomocí Microsoft Entra ID, sdíleného klíče nebo sdíleného klíče Lite
Pokud chcete žádost autorizovat pomocí Microsoft Entra ID, sdíleného klíče nebo sdíleného klíče Lite, zadejte hlavičku x-ms-version požadavku. Hodnota x-ms-version hlavičky požadavku musí být zadána ve formátu RRRR-MM-DD. Příklad:
Request Headers:
x-ms-version: 2020-04-08
Následující pravidla popisují, jak se tyto požadavky vyhodnocují, aby bylo možné určit, která verze se má použít ke zpracování požadavku.
Pokud má požadavek platnou
x-ms-versionhlavičku, služba úložiště použije zadanou verzi. Všechny požadavky na služby Azure Table Storage a Azure Queue Storage, které nepoužívají sdílený přístupový podpis, musí obsahovat hlavičkux-ms-version. Všechny požadavky na službu Blob Storage, které nepoužívají sdílený přístupový podpis, musí obsahovat hlavičkux-ms-version, pokud není nastavená výchozí verze, jak je popsáno v následujícím odstavci.Pokud požadavek na službu Blob Storage nemá hlavičku
x-ms-version, ale vlastník účtu nastavil výchozí verzi pomocí operace Set Blob Service Properties (Nastavit vlastnosti služby Blob Service ), použije se jako verze žádosti zadaná výchozí verze.
Autorizace požadavků pomocí sdíleného přístupového podpisu
Sdílený přístupový podpis (SAS) vygenerovaný pomocí verze 2014-02-14 nebo novější podporuje dvě možnosti správy verzí:
Parametr
api-versiondotazu definuje verzi protokolu REST, která se má použít ke zpracování požadavku vytvořeného pomocí SAS.Parametr
SignedVersion (sv)dotazu definuje verzi SAS, která se má použít k autorizaci.
Parametr SignedVersion dotazu se používá k autorizaci, když klient odešle požadavek pomocí SAS. Autorizační parametry, jako sijsou , sr, , sp, tnspksigsesrkstepkaerk, se interpretují pomocí zadané verze.
Parametry protokolu REST, jako rsccjsou , rscd, rsclrsce, a, se rsct vynucují pomocí verze uvedené v hlavičce parametruapi-version. Pokud hlavičku api-version nezadáte, použije se verze služby, která je k dispozici SignedVersion .
Parametr api-version není součástí hlavičky autorizace typu string-to-sign, jak je popsáno v tématu Vytvoření SAS služby.
Následující tabulka vysvětluje schéma správy verzí, které služba používá k autorizaci a volání protokolu REST, pokud SignedVersion je parametr nastaven na verzi 2014-02-14 nebo novější.
| Hodnota parametru api-version | Verze používaná k autorizaci | Verze používaná pro chování protokolu |
|---|---|---|
| Neurčené | Verze zadaná v parametru sv |
Verze zadaná v parametru sv |
Jakákoli platná verze služeb úložiště ve formátu XXXX-XX-XX |
Verze zadaná v parametru sv |
Platná verze služeb úložiště XXXX-XX-XX |
Příklad 1
Následující ukázkový požadavek volá objekty blob seznamu s sv=2015-04-05a 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
V takovém případě služba ověří a autorizuje požadavek pomocí verze 2015-04-05 a spustí operaci ve verzi 2015-04-05.
Příklad 2
Následující ukázkový požadavek volá výpis objektů blob s parametrem sv=2015-04-05api-version a .
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
Tady služba autorizuje požadavek pomocí verze 2015-04-05 a spustí operaci ve verzi 2012-02-12.
Poznámka
Klientská knihovna .NET Storage vždy nastaví verzi protokolu REST (v parametru api-version ) na verzi, na které je založená.
Žádosti prostřednictvím anonymního přístupu
Žádosti vytvořené prostřednictvím anonymního přístupu se zpracovávají odlišně v závislosti na typu účtu úložiště, pro který se provádějí.
Účty úložiště pro obecné účely
Pokud anonymní požadavek na účet úložiště pro obecné účely neurčuje hlavičku x-ms-version a výchozí verze služby nebyla nastavena pomocí možnosti Nastavit vlastnosti služby Blob Service, služba ke zpracování žádosti použije nejstarší možnou verzi. Pokud se ale kontejner zveřejní pomocí operace nastavit seznam ACL kontejneru , která se provedla pomocí verze 2009-09-19 nebo novější, požadavek se zpracuje pomocí verze 2009-09-19.
Účty Blob Storage
Pokud anonymní požadavek na účet služby Blob Storage neurčuje hlavičku x-ms-version a pomocí příkazu Nastavit vlastnosti služby Blob Service nebyla nastavena výchozí verze služby, služba ke zpracování žádosti použije nejnovější možnou verzi. Pro účet Blob Storage je nejstarší možná verze 2014-02-14.
Známé problémy
Tato část podrobně popisuje známé problémy s rozhraními REST API služby Azure Storage.
InvalidHeaderValue chybová zpráva
Ve výjimečných scénářích můžou aplikace provádějící přímá volání rozhraní REST API obdržet chybovou InvalidHeaderValue zprávu. Chyba vypadá podobně jako v následujícím příkladu:
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>
Pokud chcete zjistit, jestli se problém vyřeší, doporučujeme použít starší verzi rozhraní REST API. Pokud problém přetrvává nebo pokud doporučení není možné, otevřete lístek podpory a prodiskutujte další možnosti.