Sdílet prostřednictvím

Vložit stránku z adresy URL

  • Článek

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

Žádost

Požadavek můžete vytvořit Put Page From URL následujícím způsobem. Doporučujeme použít 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

Identifikátor URI služby emulovaného úložiště

Když vytváříte požadavek na službu emulovaného úložiště, zadejte název hostitele emulátoru a port služby Blob Service jako 127.0.0.1:10000a pak 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í emulátoru Azurite pro místní vývoj služby Azure Storage.

Parametry identifikátoru URI

V identifikátoru URI požadavku můžete zadat následující další parametry:

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

Hlavičky požadavku

Požadované a volitelné hlavičky požadavků jsou popsané v následující tabulce:

Hlavička požadavku Popis
Authorization Povinná hodnota. Určuje schéma autorizace, název účtu a podpis. Další informace najdete v tématu Autorizace požadavků do služby Azure Storage.
Date nebo x-ms-date Povinná hodnota. Určuje formát UTC (Coordinated Universal Time). Další informace najdete v tématu Autorizace požadavků do služby Azure Storage.
x-ms-version Povinné pro všechny autorizované žádosti. Určuje verzi operace, která se má použít pro tento požadavek. Další informace najdete v tématu Správa verzí pro služby Azure Storage.
Range Je vyžadováno buď nebo Rangex-ms-range .

Určuje rozsah bajtů, které se mají zapsat jako stránka. Musí být zadán 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á pouze jeden rozsah bajtů pro hlavičku Range a oblast bajtů musí být zadána v následujícím formátu: bytes=startByte-endByte.

Pokud jsou zadány obě Rangex-ms-range a, služba použije hodnotu x-ms-range. Další informace najdete v tématu Určení hlavičky rozsahu pro operace služby Blob Service.
x-ms-range Je vyžadováno buď nebo Rangex-ms-range .

Určuje rozsah bajtů, které se mají zapsat jako stránka. Musí být zadán 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á pouze jeden rozsah bajtů pro hlavičku x-ms-range a oblast bajtů musí být zadána v následujícím formátu: bytes=startByte-endByte.

Pokud jsou zadány obě Rangex-ms-range a, služba použije 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 o délce až 2 KiB, která určuje objekt blob. Hodnota by měla být zakódovaná jako v identifikátoru URI požadavku. Zdrojový objekt blob musí být buď veřejný, nebo musí být autorizovaný prostřednictvím sdíleného přístupového podpisu. Pokud je zdrojový objekt blob veřejný, nevyžaduje se k provedení operace žádná autorizace. Tady je několik příkladů adres URL zdrojových objektů:

- 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 schéma autorizace a podpis pro zdroj kopírování. Další informace najdete v tématu Autorizace požadavků do služby Azure Storage.
Pro Microsoft Entra je podporován pouze nosič schématu.
Tato hlavička je podporovaná ve verzi 2020-10-02 a novější.
x-ms-source-range Nahraje bajty objektu blob do zdrojové adresy URL v zadaném rozsahu. Musí být zadán 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á pouze jeden rozsah bajtů pro hlavičku x-ms-source-range a oblast bajtů musí být zadána 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 se používá k ověření integrity stránky během přenosu dat z identifikátoru URI. Když je tato hlavička zadána, služba úložiště porovná hodnotu hash obsahu, který přišel z copy-source, s touto hodnotou hlavičky.

Poznámka: Tato hodnota hash MD5 se s objektem blob neukládá.

Pokud se tyto dvě hodnoty hash neshodnou, 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 se používá k ověření integrity stránky během přenosu dat z identifikátoru URI. Když je tato hlavička zadána, služba úložiště porovná hodnotu hash obsahu, který přišel z copy-source, s touto hodnotou hlavičky.

Poznámka: Tato hodnota hash CRC64 se s objektem blob neukládá.

Pokud se tyto dvě hodnoty hash neshodnou, operace selže s kódem chyby 400 (Chybný požadavek).

Pokud jsou k dispozici hlavičky i x-ms-source-content-md5x-ms-source-content-crc64 , požadavek selže s chybou 400 (chybný požadavek).

Tato hlavička je podporovaná ve verzi 2019-02-02 a novější.
x-ms-lease-id:<ID> Vyžaduje se, pokud má objekt blob aktivní zapůjčení. Pokud chcete tuto operaci provést s objektem 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. V opačném případě selže s chybou SequenceNumberConditionNotMet (stavový kód HTTP 412 – Předběžná podmínka selhala).
x-ms-if-sequence-number-lt: <num> Nepovinný parametr. Pokud je pořadové číslo objektu blob menší než zadaná hodnota, požadavek bude pokračovat. V opačném případě 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. V opačném případě 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 . Tuto podmíněnou hlavičku zadejte, pokud chcete stránku zapsat jenom v případě, že se objekt blob od zadaného data a času změnil. Pokud se objekt blob neupravil, vrátí služba Blob service stavový kód 412 (Předběžná podmínka selhala).
If-Unmodified-Since Nepovinný parametr. Hodnota DateTime . Tuto podmíněnou hlavičku zadejte, pokud chcete stránku zapsat jenom v případě, že se objekt blob od zadaného data a času nezměnil. Pokud se objekt blob změnil, vrátí služba Blob service stavový kód 412 (Předběžná podmínka se nezdařila).
If-Match Nepovinný parametr. Hodnota ETag. Zadáním hodnoty ETag pro tuto podmíněnou hlavičku zapište stránku pouze v případě, že hodnota značky ETag objektu blob odpovídá zadané hodnotě. Pokud se hodnoty neshoduje, 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.

Zadáním hodnoty ETag pro tuto podmíněnou hlavičku zapište stránku jenom v případě, že hodnota ETag objektu blob neodpovídá zadané hodnotě. Pokud jsou hodnoty identické, vrátí služba Blob Service stavový kód 412 (Předběžná podmínka se nezdařila).
x-ms-encryption-scope Nepovinný parametr. Určuje obor šifrování, který se má použít k šifrování zdrojového obsahu. Tato hlavička je podporovaná ve verzi 2019-02-02 a novějších.
x-ms-client-request-id Nepovinný parametr. Poskytuje klientem vygenerovanou neprůselnou hodnotu s limitem počtu znaků 1 kibibajt (KiB), který je zaznamenán v protokolech při konfiguraci protokolování. Důrazně doporučujeme použít tuto hlavičku ke korelaci aktivit na straně klienta s požadavky, které server přijímá. Další informace najdete v tématu Monitorování Azure Blob Storage.

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 najdete v tématu Určení podmíněných hlaviček pro operace služby Blob Service.

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

Od verze 2019-02-02 je možné v požadavku na šifrování objektu blob šifrovaného pomocí klíče poskytnutého zákazníkem zadat následující hlavičky. Š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 s kódováním 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).

Další informace o stavových kódech najdete v tématu Kódy stavu a chyb.

Hlavičky odpovědi

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

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

Každá operace zápisu do objektu blob, včetně aktualizací metadat nebo vlastností objektu blob, změní čas poslední změny objektu blob.
Content-MD5 Vráceno, aby klient mohl zkontrolovat integritu obsahu zprávy. Hodnotu této hlavičky vypočítá služba Blob Service. Nemusí být nutně stejná jako hodnota zadaná v hlavičce požadavku. Pro verzi 2019-02-02 nebo novější se tato hlavička vrátí jenom v případě, že požadavek tuto hlavičku má.
x-ms-content-crc64 Pro verzi 2019-02-02 nebo novější. Vráceno, aby klient mohl zkontrolovat integritu obsahu zprávy. Hodnotu této hlavičky vypočítá služba Blob Service. Nemusí být nutně stejná jako hodnota zadaná v hlavičce požadavku.

Tato hlavička se vrátí, když x-ms-source-content-md5 v požadavku není.
x-ms-blob-sequence-number Aktuální pořadové číslo objektu blob stránky.
x-ms-request-id 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, která se použila ke spuštění požadavku. Tato hlavička se vrátí pro požadavky, které byly provedeny proti verzi 2009-09-19 a novější.
Date Hodnota data a času UTC vygenerovaná službou, která označuje čas, kdy byla odpověď inicializována.
x-ms-request-server-encrypted: true/false Verze 2015-12-11 a 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 v opačném případě.
x-ms-encryption-key-sha256 Verze 2019-02-02 a novější. Vráceno, pokud požadavek použil k šifrování klíč poskytnutý zákazníkem, aby klient mohl zajistit, že se obsah požadavku úspěšně zašifruje pomocí poskytnutého klíče.
x-ms-encryption-scope Verze 2019-02-02 a novější. Vráceno, pokud požadavek používal obor šifrování, aby klient mohl zajistit, že obsah požadavku je úspěšně zašifrován pomocí oboru šifrování.
x-ms-client-request-id Dá se použít k řešení potíží s požadavky a odpovídajícími odpověďmi. Hodnota této hlavičky se rovná hodnotě x-ms-client-request-id hlavičky, pokud se nachází v požadavku, a hodnota obsahuje maximálně 1 024 viditelných znaků ASCII. Pokud se hlavička x-ms-client-request-id v požadavku nenachází, v odpovědi se nezobrazí.

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

Autorizace se vyžaduje při volání jakékoli operace přístupu k datům ve službě Azure Storage. Operaci můžete autorizovat Put Page From URL , jak je popsáno níže.

Důležité

Microsoft doporučuje používat Microsoft Entra ID se spravovanými identitami k autorizaci požadavků do služby Azure Storage. Microsoft Entra ID poskytuje v porovnání s autorizací pomocí sdíleného klíče vynikající zabezpečení a snadné použití.

Azure Storage podporuje autorizaci požadavků na data objektů blob pomocí Microsoft Entra ID. S Microsoft Entra ID můžete pomocí řízení přístupu na základě role v Azure (Azure RBAC) udělit oprávnění k objektu zabezpečení. Objektem zabezpečení může být uživatel, skupina, instanční objekt aplikace nebo spravovaná identita Azure. Objekt zabezpečení je ověřen Microsoft Entra ID, aby vrátil token OAuth 2.0. Token se pak dá použít k autorizaci požadavku na službu Blob Service.

Další informace o autorizaci pomocí Microsoft Entra ID najdete v tématu Autorizace přístupu k objektům blob pomocí Microsoft Entra ID.

Oprávnění

Níže jsou uvedené akce RBAC potřebné k volání operace Microsoft Entra uživatele, skupiny, spravované identity nebo instančního objektu Put Page From URL a nejméně privilegované integrované role Azure RBAC, která zahrnuje tuto akci:

Další informace o přiřazování rolí pomocí Azure RBAC najdete v tématu Přiřazení role Azure pro přístup k datům objektů blob.

Poznámky

Operace Put Page From URL zapíše do objektu blob stránky rozsah stránek. Tuto operaci je možné volat pouze u existujícího objektu blob stránky. Nelze ho volat za účelem vytvoření nového objektu blob stránky ani 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 Microsoft Entra.

Pokud chcete vytvořit nový objekt blob stránky, zavolejte Put Blob a zadejte typ objektu blob, který se má 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 na zápis stránky.

Operace aktualizace stránky

Volání Put Page From URL provede místní zápis do zadaného objektu blob stránky. Veškerý obsah na zadané stránce je přepsán aktualizací.

Důležité

Pokud dojde k vypršení časového limitu serveru nebo dojde k ukončení připojení během Put Page From URL, stránka se může nebo nemusí aktualizovat. Proto byste měli pokračovat v opakování aktualizace, dokud neobdržíte odpověď označující úspěch.

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

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

Služba Blob Service zpracovává souběžné zápisy na překrývající se stránky postupně. To znamená, že poslední stránka, kterou služba zpracuje, 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ů:

  • Pro každé úspěšné volání můžete zkontrolovat hodnotu Last-Modified hlavičky Put Page From URLodpovědi . Pořadí odpovědí vrácených službou Blob Service nemusí nutně odpovídat pořadí, ve kterém je 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 s využitím optimistické souběžnosti. Tento přístup funguje dobře, pokud je počet souběžných zápisů relativně nízký. K tomuto účelu použijte hlavičky If-Matchpodmíněného požadavku , If-None-Match, If-Modified-Sincea If-Unmodified-Since .

  • Pokud chcete objekt blob zapůjčení uzamknout proti jiným zápisům, můžete volat objekt blob zapůjčení po dobu jedné minuty nebo déle, pokud se zapůjčení prodlouží.

  • Pomocí pořadového čísla objektu blob můžete zajistit, že opakování požadavku, u kterého nebyla žádná odpověď, nezpůsobí souběžné aktualizace. Tento přístup může být nejvhodnější pro klienty, kteří vyžadují vysokou propustnost pro zápisy stránek. podrobně ji popisujeme v následující části.

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

Když vyprší časový limit volání Put Page From URL nebo nevrátí odpověď, neexistuje způsob, jak s jistotou 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é, aby se původní požadavek po úspěšném opakovaném pokusu zpracoval. Zpožděný původní požadavek může přepsat další aktualizace a získat neočekávaný výsledek. Následující sekvence ukazuje, jak k tomu může dojít:

  1. Požadavek Put Page From URL na zápis hodnoty X na stránku 0 vypršel nebo nevrací odpověď.

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

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

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

  5. Stránka 0 čtení vrátí hodnotu "X", když klient v tomto okamžiku očekával hodnotu "Y".

K tomuto typu konfliktu může dojít v případě, že původní požadavek nevrací stavový kód v rozmezí 100–499 nebo 503 (Zaneprázdněný server). Pokud se některý z těchto stavových kódů vrátí, můžete si být jistí, jestli byl požadavek úspěšný nebo neúspěšný. Pokud ale služba vrátí stavový kód mimo tento rozsah, neexistuje žádný způsob, jak zjistit stav původního požadavku.

Pokud chcete tomuto druhu konfliktu zabránit, můžete pomocí pořadového čísla objektu blob stránky zajistit, ž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. Tento přístup znázorňuje následující posloupnost:

  1. Klient vytvoří objekt blob stránky s příkazem Put Blob 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 if-sequence-number-lt nastavenou na 1 vypršení časového limitu nebo nevrací odpověď.

  3. Klient zavolá nastavit vlastnosti objektu blob a aktualizuje pořadové číslo na 1.

  4. Opakovaný požadavek na zápis hodnoty X na stránku 0 s nastavenou if-sequence-number-lt na 2 úspěch

  5. Požadavek na zápis hodnoty "Y" na stránku 0 s nastavenou if-sequence-number-lt 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 (to znamená, že 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. Čtení stránky 0 vrátí očekávanou hodnotu "Y".

Viz také

Autorizace požadavků do Služby Azure Storage
Stavové kódy a kódy chyb
Nastavení časových limitů pro operace služby Blob Service