Vložit stránku z adresy URL

Operace Put Page From URL zapíše rozsah stránek do objektu blob stránky, kde se obsah čte z adresy URL. Toto rozhraní API je k dispozici od verze 2018-11-09.

Žádost

Požadavek Put Page From URL lze vytvořit následujícím způsobem. Doporučuje se https. Nahraďte myaccount názvem vašeho účtu úložiště:

IDENTIFIKÁTOR URI požadavku metody PUT Verze PROTOKOLU HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1

Emulovaný identifikátor URI služby Storage

Při vytváření požadavku na emulovanou službu úložiště zadejte název hostitele emulátoru a port služby Blob Service, 127.0.0.1:10000za kterým následuje název emulovaného účtu úložiště:

IDENTIFIKÁTOR URI požadavku metody PUT Verze PROTOKOLU HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=page HTTP/1.1

Další informace najdete v tématu Použití Azure Storage Emulator pro vývoj a testování.

Parametry identifikátoru URI

V identifikátoru URI požadavku je možné zadat následující další parametry.

Parametr Popis
timeout Nepovinný parametr. Parametr timeout se vyjadřuje v sekundách. Další informace najdete v tématu Nastavení časových limitů pro operace služby Blob Service.

Hlavičky požadavku

Následující tabulka popisuje povinné a volitelné hlavičky požadavku.

Hlavička požadavku Description
Authorization Povinná hodnota. Určuje schéma autorizace, název účtu a podpis. Další informace najdete v tématu Autorizace žádostí o Azure Storage.
Date nebo x-ms-date Povinná hodnota. Určuje formát UTC (Coordinated Universal Time). Další informace najdete v tématu Autorizace žádostí o Azure Storage.
x-ms-version Vyžaduje se pro všechny autorizované žádosti. Určuje verzi operace, která se má pro tento požadavek použít. Další informace najdete v tématu Správa verzí služby Azure Storage Services.
Range Buď Range nebo x-ms-range je to povinné.

Určuje rozsah bajtů, který se má zapsat jako stránka. Je nutné zadat začátek i konec rozsahu. Tato hlavička je definována specifikací protokolu HTTP/1.1.

V případě operace aktualizace stránky může mít rozsah stránek velikost až 4 MiB.

Vzhledem k tomu, že stránky musí být zarovnané s hranicemi 512 bajtů, počáteční posun musí být modul 512 a koncový posun musí být modul 512 – 1. Příklady platných rozsahů bajtů jsou 0–511, 512-1023 atd.

Služba Blob Service přijímá pro hlavičku pouze jeden bajtový rozsah Range a rozsah bajtů musí být zadán v následujícím formátu: bytes=startByte-endByte.

Pokud jsou zadány obě Range a x-ms-range jsou zadány, služba používá hodnotu x-ms-range. Další informace najdete v tématu Určení hlavičky rozsahu pro operace služby Blob Service .
x-ms-range Buď Range nebo x-ms-range je to povinné.

Určuje rozsah bajtů, který se má zapsat jako stránka. Je nutné zadat začátek i konec rozsahu. Tato hlavička je definována specifikací protokolu HTTP/1.1.

Rozsah stránek může mít velikost až 4 MiB.

Vzhledem k tomu, že stránky musí být zarovnané s hranicemi 512 bajtů, počáteční posun musí být modul 512 a koncový posun musí být modul 512 – 1. Příklady platných rozsahů bajtů jsou 0–511, 512-1023 atd.

Služba Blob Service přijímá pro hlavičku pouze jeden bajtový rozsah x-ms-range a rozsah bajtů musí být zadán v následujícím formátu: bytes=startByte-endByte.

Pokud jsou zadány obě Range a x-ms-range jsou zadány, služba používá hodnotu x-ms-range. Další informace najdete v tématu Určení hlavičky rozsahu pro operace služby Blob Service .
Content-Length Povinná hodnota. Určuje počet bajtů přenášených v textu požadavku. Hodnota této hlavičky musí být nastavená na nulu. Pokud délka není nula, operace selže se stavovým kódem 400 (chybný požadavek).
x-ms-copy-source:name Povinná hodnota. Určuje adresu URL zdrojového objektu blob. Hodnota může být adresa URL až 2 KiB, která určuje objekt blob. Hodnota by měla být kódovaná adresou URL, protože by se zobrazovala v identifikátoru URI požadavku. Zdrojový objekt blob musí být veřejný nebo musí být autorizovaný prostřednictvím sdíleného přístupového podpisu. Pokud je zdrojový objekt blob veřejný, k provedení operace se nevyžaduje žádná autorizace. Tady je několik příkladů adres URL zdrojového objektu:

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-copy-source-authorization: <scheme> <signature> Nepovinný parametr. Určuje autorizační schéma a podpis pro zdroj kopírování. Další informace najdete v tématu Autorizace žádostí o Azure Storage.
Pro Azure Active Directory se podporuje pouze nosný schéma.
Tato hlavička je podporována ve verzích 2020-10-02 a novějších.
x-ms-source-range Nahraje bajty objektu blob ve zdrojové adrese URL v zadaném rozsahu. Je nutné zadat začátek i konec rozsahu. Tato hlavička je definována specifikací protokolu HTTP/1.1.

Rozsah stránek může mít velikost až 4 MiB.

Služba Blob Service přijímá pro hlavičku pouze jeden bajtový rozsah x-ms-source-range a rozsah bajtů musí být zadán v následujícím formátu: bytes=startByte-endByte.

Další informace najdete v tématu Určení hlavičky rozsahu pro operace služby Blob Service .
x-ms-source-content-md5 Nepovinný parametr. Hodnota hash MD5 obsahu stránky z identifikátoru URI. Tato hodnota hash slouží k ověření integrity stránky během přenosu dat z identifikátoru URI. Pokud je tato hlavička zadaná, služba úložiště porovná hodnotu hash obsahu, který přišel ze zdroje kopírování, s touto hodnotou hlavičky.

Všimněte si, že tato hodnota hash md5 není uložena s objektem blob.

Pokud se dva hodnoty hash neshodují, operace selže s kódem chyby 400 (chybný požadavek).
x-ms-source-content-crc64 Nepovinný parametr. Hodnota hash CRC64 obsahu stránky z identifikátoru URI Tato hodnota hash slouží k ověření integrity stránky během přenosu dat z identifikátoru URI. Pokud je tato hlavička zadaná, služba úložiště porovná hodnotu hash obsahu, který přišel ze zdroje kopírování, s touto hodnotou hlavičky.

Všimněte si, že tato hodnota hash CRC64 není uložena s objektem blob.

Pokud se dva hodnoty hash neshodují, operace selže s kódem chyby 400 (chybný požadavek).

Pokud jsou k dispozici obě x-ms-source-content-md5 hlavičky x-ms-source-content-crc64 , požadavek selže s chybou 400 (Chybný požadavek).

Tato hlavička je podporována ve verzích 2019-02-02 nebo novějších.
x-ms-lease-id:<ID> Vyžaduje se, pokud má objekt blob aktivní zapůjčení. Chcete-li provést tuto operaci u objektu blob s aktivním zapůjčením, zadejte platné ID zapůjčení pro tuto hlavičku.
x-ms-if-sequence-number-le: <num> Nepovinný parametr. Pokud je pořadové číslo objektu blob menší nebo rovno zadané hodnotě, požadavek pokračuje; jinak selže s chybou SequenceNumberConditionNotMet (stavový kód HTTP 412 – Předběžná podmínka se nezdařila).
x-ms-if-sequence-number-lt: <num> Nepovinný parametr. Pokud je pořadové číslo objektu blob menší než zadaná hodnota, požadavek pokračuje; jinak selže s chybou SequenceNumberConditionNotMet (stavový kód HTTP 412 – Předběžná podmínka se nezdařila).
x-ms-if-sequence-number-eq: <num> Nepovinný parametr. Pokud se pořadové číslo objektu blob rovná zadané hodnotě, požadavek pokračuje; jinak selže s chybou SequenceNumberConditionNotMet (stavový kód HTTP 412 – Předběžná podmínka se nezdařila).
If-Modified-Since Nepovinný parametr. Hodnota DateTime . Zadejte toto podmíněné záhlaví pro zápis stránky pouze v případě, že byl objekt blob změněn od zadaného data a času. Pokud objekt blob nebyl změněn, vrátí služba Blob Service stavový kód 412 (předběžná podmínka se nezdařila).
If-Unmodified-Since Nepovinný parametr. Hodnota DateTime . Zadejte toto podmíněné záhlaví pro zápis stránky pouze v případě, že se objekt blob od zadaného data a času nezměnil. Pokud byl objekt blob změněn, vrátí služba Blob Service stavový kód 412 (předběžná podmínka se nezdařila).
If-Match Nepovinný parametr. Hodnota ETag. Zadejte hodnotu značky ETag pro toto podmíněné záhlaví pro zápis stránky pouze v případě, že hodnota značky ETag objektu blob odpovídá zadané hodnotě. Pokud se hodnoty neshodují, vrátí služba Blob Service stavový kód 412 (Předběžná podmínka se nezdařila).
If-None-Match Nepovinný parametr. Hodnota ETag.

Zadejte hodnotu značky ETag pro toto podmíněné záhlaví pro zápis stránky pouze v případě, že hodnota značky ETag objektu blob neodpovídá zadané hodnotě. Pokud jsou hodnoty stejné, vrátí služba Blob Service stavový kód 412 (předběžná podmínka se nezdařila).
x-ms-encryption-scope Nepovinný parametr. Označuje obor šifrování, který se má použít k šifrování zdrojového obsahu. Tato hlavička je podporována ve verzích 2019-02-02 nebo novějších.
x-ms-client-request-id Nepovinný parametr. Poskytuje hodnotu vygenerovanou klientem s 1 limitem znaků KiB, který se zaznamenává v analytických protokolech při povolení protokolování analýzy úložiště. Použití této hlavičky se důrazně doporučuje pro korelaci aktivit na straně klienta s požadavky přijatými serverem. Další informace najdete v tématu o protokolování Analýza úložiště a protokolování Azure: Sledování požadavků Storage pomocí protokolů.

Tato operace také podporuje použití podmíněných hlaviček k provedení operace pouze v případě, že je splněna zadaná podmínka. Další informace naleznete v tématu Určení podmíněných hlaviček pro operace služby Blob Service.

Hlavičky požadavku (šifrovací klíče poskytované zákazníkem)

Počínaje verzí 2019-02-02 je možné v požadavku zadat následující hlavičky pro šifrování objektu blob šifrovaného pomocí klíče poskytnutého zákazníkem. Šifrování pomocí klíče poskytnutého zákazníkem (a odpovídající sady hlaviček) je volitelné.

Hlavička požadavku Popis
x-ms-encryption-key Povinná hodnota. Šifrovací klíč AES-256 s kódováním Base64
x-ms-encryption-key-sha256 Povinná hodnota. Hodnota hash SHA256 zakódovaná pomocí base64 šifrovacího klíče.
x-ms-encryption-algorithm: AES256 Povinná hodnota. Určuje algoritmus, který se má použít k šifrování. Hodnota této hlavičky musí být AES256.

Text požadavku

Text požadavku obsahuje obsah stránky.

Ukázkový požadavek

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:   
x-ms-date: Fri, 16 Sep 2011 22:15:50 GMT  
x-ms-version: 2018-11-09  
x-ms-range: bytes=0-65535  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 0  
  

Odpověď

Odpověď obsahuje stavový kód HTTP a sadu hlaviček odpovědi.

Stavový kód

Úspěšná operace vrátí stavový kód 201 (vytvořeno).

Informace o stavových kódech naleznete v tématu Stavové a chybové kódy.

Hlavičky odpovědi

Odpověď pro tuto operaci obsahuje následující hlavičky. Odpověď může obsahovat také další standardní hlavičky HTTP. Všechny standardní hlavičky odpovídají specifikaci protokolu HTTP/1.1.

Syntax Description
ETag Značky ETag objektu blob. Pokud je verze požadavku 2011-08-18 nebo novější, bude hodnota ETag v uvozovkách. Značku ETag lze použít k provedení podmíněné Put Page From URL operace zadáním jeho hodnoty pro hlavičku požadavku nebo If-None-Match hlavičku If-Match požadavku.
Last-Modified Datum a čas poslední změny objektu blob. Formát data se řídí dokumentem RFC 1123. Další informace naleznete v tématu Reprezentace hodnot Date-Time v záhlavích.

Jakákoli operace zápisu objektu blob, včetně aktualizací metadat nebo vlastností objektu blob, změní čas poslední změny objektu blob.
Content-MD5 Tato hlavička se vrátí, aby klient mohl zkontrolovat integritu obsahu zpráv. Hodnota této hlavičky je vypočítán službou Blob Service; nemusí být nutně stejná hodnota zadaná v hlavičce požadavku. U verzí 2019-02-02 nebo novějších se tato hlavička vrátí pouze v případě, že požadavek obsahuje tuto hlavičku.
x-ms-content-crc64 U verzí 2019-02-02 nebo novějších se tato hlavička vrátí, aby klient mohl zkontrolovat integritu obsahu zprávy. Hodnota této hlavičky je vypočítán službou Blob Service; nemusí být nutně stejná hodnota zadaná v hlavičce požadavku.

Tato hlavička se vrátí, když x-ms-source-content-md5 v požadavku není k dispozici hlavička.
x-ms-blob-sequence-number Aktuální pořadové číslo objektu blob stránky.
x-ms-request-id Tato hlavička jednoznačně identifikuje požadavek, který byl proveden, a lze ho použít k řešení potíží s požadavkem. Další informace najdete v tématu Řešení potíží s operacemi rozhraní API.
x-ms-version Označuje verzi služby Blob Service použitou k provedení požadavku. Tato hlavička se vrátí pro požadavky provedené ve verzi 2009-09-19 a novější.
Date Hodnota data a času UTC vygenerovaná službou, která označuje čas, kdy byla odpověď zahájena.
x-ms-request-server-encrypted: true/false Verze 2015-12-11 nebo novější. Hodnota této hlavičky je nastavena na true , pokud je obsah požadavku úspěšně zašifrován pomocí zadaného algoritmu a false jinak.
x-ms-encryption-key-sha256 Verze 2019-02-02 nebo novější. Tato hlavička se vrátí, pokud požadavek použil k šifrování klíč poskytnutý zákazníkem, takže klient může zajistit, aby byl obsah požadavku úspěšně zašifrován pomocí zadaného klíče.
x-ms-encryption-scope Verze 2019-02-02 nebo novější. Tato hlavička se vrátí, pokud požadavek použil obor šifrování, takže klient může zajistit, aby byl obsah požadavku úspěšně zašifrován pomocí oboru šifrování.
x-ms-client-request-id Tato hlavička se dá použít k řešení potíží s požadavky a odpovídajícími odpověďmi. Hodnota této hlavičky se rovná hodnotě hlavičky, pokud se nachází v požadavku a hodnota je maximálně 1024 viditelných x-ms-client-request-id znaků ASCII. Pokud v požadavku není hlavička x-ms-client-request-id , nebude tato hlavička v odpovědi k dispozici.

Text odpovědi

Žádné

Ukázková odpověď

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 22:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Sun, 25 Sep 2011 12:13:31 GMT  
x-ms-version: 2011-08-18  
x-ms-blob-sequence-number: 0  
Content-Length: 0  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
  

Autorizace

Tuto operaci může volat vlastník účtu a kdokoli se sdíleným přístupovým podpisem, který má oprávnění k zápisu do tohoto objektu blob nebo jeho kontejneru.

Poznámky

Operace Put Page From URL zapíše rozsah stránek do objektu blob stránky. Tuto operaci lze volat pouze u existujícího objektu blob stránky. Nelze volat, aby se vytvořil nový objekt blob stránky, ani ho nelze volat v objektu blob bloku. Volání Put Page From URL s názvem objektu blob, který aktuálně neexistuje, vrátí chybu BlobNotFound (stavový kód HTTP 404 – Nenalezeno).

Ve verzi 2020-10-02 a novější se pro zdroj operace kopírování podporuje autorizace Azure Active Directory.

Pokud chcete vytvořit nový objekt blob stránky, zavolejte Objekt blob Put a zadejte typ objektu blob, který chcete vytvořit jako objekt blob stránky. Objekt blob stránky může mít velikost až 8 TiB.

Pokud má objekt blob aktivní zapůjčení, musí klient zadat platné ID zapůjčení v požadavku, aby mohl napsat stránku.

Operace aktualizace stránky

Volání Put Page From URL provádí místní zápis do zadaného objektu blob stránky. Veškerý obsah na zadané stránce se přepíše aktualizací.

Důležité

Pokud dojde k vypršení časového limitu serveru nebo ukončení připojení během nějakého Put Page From URLserveru, může nebo nemusí být stránka aktualizována. Proto byste měli aktualizaci opakovat, dokud neobdržíte odpověď, která značí úspěch.

Každý rozsah stránek odeslaných Put Page From URL pro operaci aktualizace může mít velikost až 4 MiB. Počáteční a koncový rozsah stránky musí být zarovnaný s hranicemi 512 bajtů. Pokud se pokusíte nahrát rozsah stránek, které jsou větší než 4 MB, vrátí služba stavový kód 413 (příliš velká entita požadavku).

Správa problémů s souběžností

Služba Blob Service zpracovává souběžné zápisy překrývající se stránky postupně: poslední stránka zpracovávaná službou určuje obsah objektu blob. Aby se zajistila integrita obsahu objektu blob, měl by klient zpracovávat zápisy na překrývající se stránky pomocí jednoho nebo několika následujících přístupů:

  • Můžete zkontrolovat hodnotu Last-Modified hlavičky odpovědi pro každé úspěšné volání .Put Page From URL Pořadí odpovědí vrácených ze služby Blob Service nemusí nutně odpovídat pořadí, ve kterém služba spustila. Hodnota Last-Modified vždy ale označuje pořadí, ve kterém služba zpracovávala požadavky.

  • Aktualizace můžete provádět podmíněně na základě značky ETag objektu blob nebo času poslední změny pomocí optimistické souběžnosti. Tento přístup funguje dobře, pokud je počet souběžných zápisů relativně nízký. Pro tento účel použijte hlavičky If-Matchpodmíněného požadavku , If-None-MatchIf-Modified-Since, a If-Unmodified-Since pro tento účel.

  • Objekt blob zapůjčení můžete volat k uzamčení objektu blob proti jiným zápisům po dobu jedné minuty nebo déle, pokud se zapůjčení obnoví.

  • Pořadové číslo objektu blob můžete použít k tomu, abyste se ujistili, že opakování požadavku, u kterého nedošlo k žádné odpovědi, nevyústí v souběžných aktualizacích. Tento přístup může být nejvhodnější pro klienty vyžadující vysokou propustnost pro zápisy stránek. Podrobně je popsána v následující části.

Použití pořadového čísla objektu blob stránky k opakování žádostí

Pokud vyprší časový limit volání Put Page From URL nebo nevrací odpověď, neexistuje způsob, jak zjistit, jestli požadavek proběhl úspěšně. Proto je potřeba požadavek zopakovat, ale vzhledem k distribuované povaze služeb úložiště Azure je možné, že původní požadavek může být zpracován po úspěšném pokusu. Zpožděný původní požadavek může přepsat další aktualizace a přinést neočekávaný výsledek. Následující posloupnost znázorňuje, jak k tomu může dojít:

  1. Vypršel Put Page From URL časový limit požadavku na zápis hodnoty X na stránku 0 nebo nevrací odpověď.

  2. Opakovaný požadavek na zápis hodnoty X na stránku 0 proběhne úspěšně.

  3. Požadavek na zápis hodnoty "Y" na stránku 0 bude úspěšný.

  4. Původní požadavek bude úspěšný a zapíše hodnotu "X" na stránku 0.

  5. Při čtení stránky 0 se vrátí hodnota "X", když klient v tomto okamžiku očekával hodnotu "Y".

K tomuto druhu konfliktu může dojít, když původní požadavek nevrací stavový kód mezi 100–499 nebo 503 (Server Zaneprázdněn). Pokud se vrátí některý z těchto stavových kódů, můžete si být jistí, jestli žádost proběhla úspěšně nebo selhala. Pokud ale služba vrátí stavový kód mimo tento rozsah, neexistuje způsob, jak zjistit stav původního požadavku.

Pokud chcete zabránit tomuto druhu konfliktu, můžete použít pořadové číslo objektu blob stránky, abyste zajistili, že při opakování požadavku nebude původní požadavek následně úspěšný. Uděláte to tak, že před opakováním původního požadavku zvýšíte pořadové číslo. Pak můžete použít hlavičky podmíněného pořadového čísla, abyste zajistili, že požadavek selže, pokud jeho pořadové číslo neodpovídá očekávanému pořadovém číslu. Následující posloupnost znázorňuje tento přístup:

  1. Klient vytvoří objekt blob stránky s objektem blob Put a nastaví jeho pořadové číslo na 0.

  2. Požadavek Put Page From URL na zápis hodnoty "X" na stránku 0 s hlavičkou nastavenou if-sequence-number-lt na 1 časový limit nebo nevrací odpověď.

  3. Klient volá Nastavit vlastnosti objektu blob pro aktualizaci pořadového čísla na 1.

  4. Opakovaný požadavek na zápis hodnoty "X" na stránku 0 se if-sequence-number-lt sadou úspěšných 2 .

  5. Požadavek na zápis hodnoty "Y" na stránku 0 s if-sequence-number-lt nastavenou na 2 úspěch.

  6. Původní požadavek se nakonec zpracuje, ale selže, protože určuje podmínku, že pořadové číslo musí být menší než 1 (tedy hlavička if-sequence-num-lt je nastavená na 1). Chyba je SequenceNumberConditionNotMet (stavový kód HTTP 412 – Předběžná podmínka se nezdařila).

  7. Stránka 0 pro čtení vrátí očekávanou hodnotu "Y".

Viz také

Autorizace žádostí na Azure Storage
Stavové kódy a kódy chyb
Nastavení časových limitů pro operace služby Blob Service