Připojit blok

  • Článek

Operace Append Block potvrdí nový blok dat na konec existujícího doplňovacího objektu blob.

Operace Append Block je povolená pouze v případě, že byl objekt blob vytvořen s x-ms-blob-type nastavenou na AppendBlobhodnotu . Append Block je podporován pouze ve verzi 2015-02-21 nebo novější.

Žádost

Požadavek můžete sestavit Append Block 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=appendblock HTTP/1.1

Když vytváříte požadavek na službu emulovaného úložiště, zadejte název hostitele emulátoru a port Azure Blob Storage jako 127.0.0.1:10000a 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=appendblock HTTP/1.1

Další informace najdete v tématu Použití emulátoru Azurite pro vývoj v místním úložišti Azure Storage.

Parametry identifikátoru URI

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

Hlavičky požadavku

Následující tabulka popisuje požadované a volitelné hlavičky požadavků.

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 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í pro služby Azure Storage.
Content-Length Povinná hodnota. Délka obsahu bloku v bajtech. Velikost bloku musí být menší nebo rovna 100 MiB (Preview) pro verzi 2022-11-02 a novější. Limity ve starších verzích najdete v části Poznámky .

Pokud není délka zadána, operace selže se stavovým kódem 411 (délka požadovaná).
Content-MD5 Nepovinný parametr. Hodnota hash MD5 obsahu bloku. Tato hodnota hash se používá k ověření integrity bloku během přenosu. Po zadání této hlavičky služba úložiště porovná hodnotu hash obsahu, který byl doručen, s touto hodnotou hlavičky.

Všimněte si, že tato hodnota hash MD5 se neukládá s objektem blob.

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 přidávaného bloku. Tato hodnota hash se používá k ověření integrity bloku připojení během přenosu. Po zadání této hlavičky služba úložiště porovná hodnotu hash obsahu, který byl doručen, s touto hodnotou hlavičky.

Všimněte si, že tato hodnota hash CRC64 se neukládá s objektem blob.

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 kódem chyby 400.

Tato hlavička je podporovaná ve verzích 2019-02-02 nebo novějších.
x-ms-encryption-scope Nepovinný parametr. Určuje obor šifrování, který se má použít k zašifrování obsahu požadavku. Tato hlavička je podporovaná 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í. Pokud chcete tuto operaci provést s objektem blob s aktivním zapůjčením, zadejte platné ID zapůjčení této hlavičky.
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.
x-ms-blob-condition-maxsize Volitelná podmíněná hlavička. Určuje maximální délku v bajtech povolenou pro doplňovací objekt blob. Append Block Pokud operace způsobí, že objekt blob překročí tento limit nebo pokud je velikost objektu blob už větší než hodnota zadaná v této hlavičce, požadavek selže s kódem chyby 412 (Předběžná podmínka se nezdařila).
x-ms-blob-condition-appendpos Volitelná podmíněná hlavička, která se používá pouze pro operaci Append Block . Číslo označuje posun bajtů, který se má porovnat. Append Block úspěch pouze v případě, že pozice připojení je rovna tomuto číslu. Pokud není, požadavek selže s kódem chyby 412 (Předběžná podmínka selhala).

Tato operace podporuje použití dalších podmíněných hlaviček, aby se zajistilo, že rozhraní API bude úspěšné 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 Azure Blob Storage.

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

Ukázkový požadavek

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048  
If-Match: "0x8CB172A360EC34B"

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 najdete v tématu Stavové kódy a kódy 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.

Hlavička odpovědi Description
ETag Obsahuje ETag hodnotu v uvozovkách. Klient může hodnotu použít k provádění podmíněných PUT operací pomocí hlavičky If-Match požadavku.
Last-Modified Datum a čas poslední změny objektu blob. Formát data odpovídá dokumentu RFC 1123. Další informace najdete v tématu Znázornění 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í se nutně jednat o stejnou hodnotu zadanou v hlavičce požadavku. Pro verze 2019-02-02 nebo novější se tato hlavička vrátí pouze v případě, že požadavek má tuto hlavičku.
x-ms-content-crc64 Ve verzích 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 Storage. Nemusí se nutně jednat o stejnou hodnotu zadanou v hlavičce požadavku.

Tato hlavička se vrátí, Content-md5 když v požadavku není.
x-ms-request-id Tato hlavička jednoznačně identifikuje požadavek, který byl proveden, a lze ji použít k řešení potíží s požadavkem.
x-ms-version Označuje verzi služby Blob Storage použitou ke spuštění požadavku. Tato hlavička se vrátí pro požadavky provedené proti verzi 2009-09-19 a novější.
Date Hodnota data a času UTC, která označuje čas, kdy byla odpověď zahájena. Tato služba vygeneruje tuto hodnotu.
x-ms-blob-append-offset Tato hlavička odpovědi je vrácena pouze pro operace připojení. Vrátí posun, při kterém byl blok potvrzen, v bajtech.
x-ms-blob-committed-block-count Počet potvrzených bloků v objektu blob. Můžete ho použít k určení, kolik dalších připojení lze provést.
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. V opačném případě je hodnota nastavená na false.
x-ms-encryption-key-sha256 Verze 2019-02-02 nebo novější. Tato hlavička se vrátí, pokud požadavek k šifrování použil klíč poskytnutý zákazníkem. Klient pak může zajistit úspěšné zašifrování obsahu požadavku pomocí poskytnutého klíče.
x-ms-encryption-scope Verze 2019-02-02 nebo novější. Tato hlavička se vrátí, pokud požadavek používá obor šifrování. Klient pak může zajistit úspěšné zašifrování obsahu požadavku pomocí oboru šifrování.
x-ms-client-request-id Tuto hlavičku můžete 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. Hodnota je maximálně 1024 viditelných znaků ASCII. Pokud se hlavička x-ms-client-request-id v požadavku nenachází, v odpovědi se tato hlavička nenachází.

Ukázková odpověď

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: <date>  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-blob-append-offset: 2097152  
x-ms-blob-committed–block-count: 1000

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 Append Block , jak je popsáno níže.

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í Append Block operace Microsoft Entra uživatele, skupiny nebo instančního objektu a předdefinované role Azure RBAC s nejnižšími oprávněními, která tuto akci zahrnuje:

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

Append Block nahraje blok na konec existujícího doplňovacího objektu blob. Blok dat je k dispozici okamžitě po úspěšném volání na serveru. Pro každý objekt blob připojení je povoleno maximálně 50 000 připojení. Každý blok může mít jinou velikost.

Následující tabulka popisuje maximální povolené velikosti bloku a objektů blob podle verze služby:

Verze služby Maximální velikost bloku (přes Append Block) Maximální velikost objektu blob
Verze 2022-11-02 a novější 100 MiB (Preview) Přibližně 4,75 TiB (100 MiB × 50 000 bloků)
Verze starší než 2022-11-02 4 MiB Přibližně 195 gibibajtů (GiB) (4 MiB × 50 000 bloků)

Append Block úspěch pouze v případě, že objekt blob již existuje.

Objekty blob nahrané pomocí nezpřístupňují Append Block ID bloků. Pro doplňovací objekt blob není možné volat metodu Get Block List . Pokud to uděláte, dojde k chybě.

V požadavku můžete zadat následující volitelné podmíněné hlavičky:

  • x-ms-blob-condition-appendpos: Tuto hlavičku můžete nastavit na posun bajtů, při kterém klient očekává, že připojí blok. Požadavek bude úspěšný pouze v případě, že aktuální posun odpovídá posunu zadanému klientem. V opačném případě požadavek selže s kódem chyby 412 (Předběžná podmínka se nezdařila).

    Klienti, kteří používají jeden zapisovač, můžou pomocí této hlavičky určit, jestli Append Block operace navzdory selhání sítě proběhla úspěšně.

  • x-ms-blob-condition-maxsize: Klienti můžou tuto hlavičku použít k zajištění toho, aby operace připojení nezvětšily velikost objektu blob nad rámec očekávané maximální velikosti v bajtech. Pokud podmínka selže, požadavek selže s kódem chyby 412 (Předběžná podmínka selhala).

Pokud se pokusíte nahrát blok, který je větší než povolená velikost, služba vrátí kód chyby 413 (Příliš velká entita požadavku). Služba také vrátí další informace o chybě v odpovědi, včetně maximální povolené velikosti bloku v bajtech. Pokud se pokusíte nahrát více než 50 000 bloků, vrátí služba kód chyby 409 (Konflikt).

Pokud má objekt blob aktivní zapůjčení, klient musí v požadavku zadat platné ID zapůjčení, aby mohl do objektu blob zapsat blok. Pokud klient nezadá ID zapůjčení nebo zadá neplatné ID zapůjčení, vrátí Blob Storage kód chyby 412 (Předběžná podmínka se nezdařila). Pokud klient zadá ID zapůjčení, ale objekt blob nemá aktivní zapůjčení, vrátí blob Storage také kód chyby 412.

Pokud zavoláte Append Block existující objekt blob bloku nebo objekt blob stránky, služba vrátí chybu konfliktu. Pokud zavoláte Append Block na neexistující objekt blob, služba vrátí také chybu.

Vyhněte se duplicitním nebo zpožděným připojením

Ve scénáři s jedním zápisem se klient může vyhnout duplicitním připojením nebo zpožděným zápisům pomocí *x-ms-blob-condition-appendpos podmíněné hlavičky ke kontrole aktuálního posunu. Klient se také může vyhnout duplicitám nebo zpožděním tím, že ETag podmíněně zkontroluje hodnotu pomocí příkazu If-Match.

Ve scénáři s více zapisovači může každý klient používat podmíněné hlavičky, ale to nemusí být optimální z hlediska výkonu. Pro nejvyšší propustnost souběžného připojení by aplikace měly zpracovávat redundantní připojení a zpožděná připojení v aplikační vrstvě. Aplikace může například do připojených dat přidat epochy nebo pořadová čísla.

Fakturace

Požadavky na ceny můžou pocházet od klientů, kteří používají rozhraní API služby Blob Storage, a to buď přímo prostřednictvím rozhraní REST API služby Blob Storage, nebo z klientské knihovny služby Azure Storage. Za tyto žádosti se účtují poplatky za každou transakci. Typ transakce ovlivňuje způsob účtování za účet. Například transakce čtení se načítají do jiné kategorie fakturace než transakce zápisu. Následující tabulka uvádí kategorii fakturace pro Append Block žádosti založené na typu účtu úložiště:

Operace Typ účtu úložiště Kategorie fakturace
Připojit blok Objekt blob bloku úrovně Premium
Standard pro obecné účely v2
Standard pro obecné účely v1		 Operace zápisu

Informace o cenách pro zadanou kategorii fakturace najdete v tématu Azure Blob Storage Ceny.