Sdílet prostřednictvím

Vložit stránku

  • Článek

Operace Put Page zapíše do objektu blob stránky rozsah stránek.

Žádost

Požadavek můžete vytvořit Put Page 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

Žádost o službu 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.

Pro operaci aktualizace stránky může být rozsah stránek až 4 MiB. V případě operace vymazání stránky může být rozsah stránek stejně velký jako hodnota plné velikosti objektu blob.

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.

Blob Storage 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.

V případě operace aktualizace stránky může mít rozsah stránek velikost až 4 MiB. V případě operace vymazání stránky může být rozsah stránek až do hodnoty plné velikosti objektu blob.

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.

Blob Storage 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. Pokud je hlavička x-ms-page-write nastavená na clear, musí být hodnota této hlavičky nastavena na 0hodnotu .
Content-MD5 Nepovinný parametr. Hodnota hash MD5 obsahu stránky. Tato hodnota hash se používá k ověření integrity stránky během přenosu. Když je tato hlavička zadána, služba úložiště porovná hodnotu hash obsahu, který byl doručen, s touto hodnotou hlavičky.
<br / >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-content-crc64 Nepovinný parametr. Hodnota hash CRC64 obsahu stránky. Tato hodnota hash se používá k ověření integrity stránky během přenosu. Když je tato hlavička zadána, služba úložiště porovná hodnotu hash obsahu, který byl doručen, 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 Content-MD5x-ms-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-page-write: {update ¦ clear} Povinná hodnota. Můžete zadat jednu z následujících možností:

- Update: Zapíše bajty určené tělem požadavku do zadaného rozsahu. Hlavičky Range a Content-Length se musí shodovat, aby se aktualizace provedla.
- Clear: Vymaže zadanou oblast a uvolní místo, které se v úložišti pro daný rozsah používá. Pokud chcete oblast vymazat, nastavte Content-Length záhlaví na 0a nastavte Range záhlaví na hodnotu, která označuje rozsah, který se má vymazat, až do maximální velikosti objektu blob.
x-ms-encryption-scope Nepovinný parametr. Označuje rozsah šifrování, který se má použít k šifrování obsahu požadavku. 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 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-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 selhala).
If-Modified-Since Nepovinný parametr. Hodnota DateTime . Zadáním tohoto podmíněného záhlaví zapište stránku jenom v případě, že se objekt blob od zadaného data a času změnil. Pokud se objekt blob nezměnil, vrátí blob Storage stavový kód 412 (Předběžná podmínka se nezdařila).
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í Blob Storage 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 neshodovaly, vrátí Blob Storage 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é, blob Storage vrátí stavový kód 412 (Předběžná podmínka se nezdařila).
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 můžete v požadavku na šifrování objektu blob 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: Aktualizace rozsahu bajtů

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

Ukázkový požadavek: Vymazání rozsahu bajtů

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:  
Range: bytes=1024-2048  
x-ms-page-write: clear  
x-ms-date: Sun, 25 Sep 2011 23:37:35 GMT  
x-ms-version: 2011-08-18  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=

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 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 Tato hlavička se vrátí, aby klient mohl zkontrolovat integritu obsahu zprávy. Hodnota této hlavičky je vypočítáná službou Blob Storage. Nemusí být nutně stejná jako hodnota zadaná v hlavičce požadavku. Pro verzi 2019-02-02 a novější se tato hlavička vrátí jenom v případě, že požadavek má tuto hlavičku.
x-ms-content-crc64 Pro verzi 2019-02-02 nebo novější 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 Storage. Nemusí být nutně stejná jako hodnota zadaná v hlavičce požadavku.

Tato hlavička se vrátí, když 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. V opačném případě je hodnota nastavená na false.
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:  
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 , 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í ověří 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 nezbytné k volání Put Page operace Microsoft Entra uživatelem, skupinou, spravovanou identitou nebo instančním objektem a předdefinovanou rolí Azure RBAC s nejnižšími oprávněními, 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 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 s názvem objektu blob, který aktuálně neexistuje, vrátí stavový kód HTTP 404 (Nenalezeno).

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 s Update možností 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 během operace dojde k vypršení časového limitu serveru nebo dojde k ukončení Put Page připojení, stránka se mohla nebo neaktualizovala. Proto byste měli pokračovat v opakování aktualizace, dokud neobdržíte odpověď, která značí úspěch.

Každá oblast stránek odeslaná Put Page 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).

Operace vymazání stránky

Volání Put Page s možností Clear uvolní prostor úložiště, který je používán zadanou stránkou. Stránky, které byly vymazány, se už nesledují jako součást objektu blob stránky.

Odstraněné stránky už nebudou účtovat poplatky za účet úložiště, protože se uvolnily jejich prostředky úložiště. Jedinou výjimkou je, pokud existují snímky objektu blob stránky. Stránky ve snímcích se účtují poplatky, pokud stejné stránky už neexistují jako součást zdrojového objektu blob.

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

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

  • Pro každé úspěšné volání můžete zkontrolovat hodnotu Last-Modified hlavičky Put Pageodpovědi . Pořadí odpovědí vrácených ze služby Blob Storage 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. To je podrobně popsáno 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 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é, že původní požadavek může být zpracován po úspěšném opakovaném pokusu. Zpožděný původní požadavek může přepsat další aktualizace a získat neočekávaný výsledek. Následující posloupnost ukazuje, jak k tomu může dojít:

  1. Požadavek Put Page 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 od 100 do 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 ú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 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á Set Blob Properties 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 selhala).

  7. Čtení stránky 0 vrátí očekávanou hodnotu "Y".

Viz také

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