Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Úvod
Tento dokument popisuje formát Structured Body používaný API Azure Storage Blob, File a DFS pro podporu efektivního výpočtu kontrolního součtu nad obsahem požadavků. Jedná se o vlastní binární formát, který kóduje data (např. blob nebo obsah souboru) s kontrolními součty na základě kontrolního součtu. Všimněte si, že samotné tělo požadavku je zakódováno v tomto formátu.
Tato dokumentace je primárně určena zákazníkům, kteří přímo používají Azure Storage REST API. Zákazníci používající podporované Azure Storage SDK budou mít své požadavky automaticky zakódované v tomto formátu.
V současnosti Azure Storage podporuje pouze verzi 1 tohoto formátu, která podporuje pouze kontrolní součty crc64. Použití formátu strukturované zprávy je volitelné.
Specification
Oddíly
Zakódovaná zpráva má tři části.
| Oddíl | Description |
|---|---|
| Header | Hlavička obsahuje verzi schématu (1), délku zprávy, možnosti a počet segmentů. |
| Segment(y) | Každá zpráva má jeden nebo více segmentů a každý segment obsahuje segment #, data a volitelná metadata s dohledem. Pro verzi 1 je jediným podporovaným trailerem kontrolní součet crc64. |
| Přívěs | Každá zpráva má volitelná metadata na konci. Pro verzi 1 je jediným podporovaným trailerem kontrolní součet crc64. |
Binární formát, v1
Binární formát Structured Body v1 je definován jako:
Header:
uint8 message-version
uint64 message-length
uint16 message-flags
uint16 num-segments
Segment(s):
uint16 segment-num
uint64 segment-data-length (dl)
byte[dl] segment-data
byte[8] [optional] segment-data-crc64
Trailer:
byte[8] [optional] message-data-crc64
Všechny celočíselné datové typy jsou kódovány jako little-endian.
Terénní reference
| Obor | Typ | Description |
|---|---|---|
message-version |
uint8 |
Schéma verze zprávy. To musí být 1. |
message-length |
uint64 |
Délka celé zprávy. V HTTP zprávě musí toto odpovídat hlavičce Content-Length . |
message-flags |
uint16 |
Příznaky (možnosti) jsou pro tuto zprávu povoleny. Verze 1 podporuje pouze jeden příznak pro crc64 kontrolní součty. Viz Vlajky. |
num-segments |
uint16 |
Počet segmentů obsažených ve zprávě. To musí být alespoň 1. Viz segmenty |
segment-num |
uint16 |
Aktuální segment #. První segment je a 1 musí se zvyšovat pro každý následující segment. |
segment-data-length (dl) |
uint64 |
Délka blob/souborů segmentu v bajtech. |
segment-data |
byte[dl] |
Blob/databajty souboru. |
segment-data-crc64[^1] |
byte[8] |
Vypočítaný kontrolní součet crc64 pro segment data. |
message-data-crc64[^1] |
byte[8] |
Vypočítaný kontrolní součet crc64 pro data zprávy (všechny segmenty .) data |
[^1]: kontrolní součty CRC64 jsou přítomny, když je tato možnost specifikována include-crc64 . Viz Vlajky.
Flags
Toto message-flags pole slouží k určení možností pro zakódovanou zprávu. Verze 1 podporuje pouze jednu možnost, , ale zbývající bity jsou vyhrazeny pro budoucí možnosti, include-crc64jako jsou jiné algoritmy kontrolních součtů a další metadata.
| Hodnota | Název | Description |
|---|---|---|
0x0001 |
include-crc64 |
Zahrňte kontrolní součty crc64 do segmentů a trailer zpráv. |
0x0002-0x8000 |
Vyhrazeno pro budoucí verze. |
Segments
Zakódované zprávy jsou rozděleny do jednoho nebo více segmentů. Každý segment obsahuje svůj segment #, data segmentu a kontrolní součet[^1]. Tento design umožňuje inkrementální ověřování integrity u velkých požadavků a je užitečný pro obnovení částečných stahování.
Poznámka:
Segmenty jsou číslovány začínajícím na 1. Maximální počet segmentů je .65535
Prázdné segmenty
Všimněte si, že segmenty mohou mít prázdné segment-data pole. Viz příklad prázdné skvrny, která má jediný prázdný segment. Prázdné segmenty musí mít hodnotu segment-data-length a 0 pokud include-crc64 je povoleno, musí obsahovat platný kontrolní součet.
Velikost segmentu
Na požadavek GetBlob nebo ReadFile s x-ms-structured-body příslušným nastavením v HTTP požadavku služba rozdělí blob nebo data souboru do segmentů 4MiB v zakódované odpovědi. Pokud zpráva překročí maximální počet segmentů, velikost segmentu se zvýší.
Pro nahraná data blobu nebo souboru z klienta služba přijímá segmenty libovolné velikosti nebo různých velikostí. Doporučuje se používat segmenty o velikosti 4MiB nebo větší. SDK používají standardně velikost segmentů 4MiB.
Validace obsahu CRC64
Validace obsahu CRC64 je funkce v Azure Storage REST API, která umožňuje validaci kontrolního součtu podporovaných API. Existuje mnoho variant algoritmů CRC64. Kontrolní součty CRC64 se počítají pomocí CRC64-NVME (tzv. CRC64-Rocksoft). Tato funkce využívá vlastní polynom CRC64 k ověření integrity přenášeného obsahu. Existují dvě formy, ve kterých lze tento kontrolní součet využít:
- Strukturované tělo: Kontrolní součty CRC64 jsou vloženy do těla API požadavku, což umožňuje validaci kontrolních součtů při streamování dat.
- Transakční kontrolní součty CRC64 (podporované pouze při nahrávání): Pro každý jednotlivý požadavek API klient vypočítá kontrolní součet CRC64 a nastaví hodnotu do hlavičky,
x-ms-content-crc64. Služba Storage ověřuje, že kontrolní součet přijatých bajtů odpovídá kontrolnímu součtu uvedenému v hlavičce.
Polynom
Tato varianta CRC64 je bitově reflektovaná (založená na nebitově odraženém polynomiálním 0xad93d23594c93659) a invertuje vstupní a výstupní bity CRC.
Examples
Příklad - Prázdná kódovaná zpráva
Tento příklad ukazuje zprávu zakódovanou strukturovaným tělem bez dat. Všimněte si, že zpráva musí obsahovat prázdný segment.
// header: 13 bytes
0x01, // message-version: 1
0x27, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // message-length: 39
0x01, 0x00, // message-flags: 1 (include-crc64)
0x01, 0x00, // num-segments: 1
// segment 1: 18 bytes
0x01, 0x00, // segment-num: 1
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // segment-data-length: 0
// segment-data: empty
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // segment-data-crc64: 0
// trailer: 8 bytes
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 // message-data-crc64: 0
Příklad - Prázdná zakódovaná zpráva bez crc64
Tento příklad ukazuje zakódovanou zprávu bez dat a bez povolené include-crc64 volby.
// header: 13 bytes
0x01, // message-version: 1
0x17, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // message-length: 23
0x00, 0x00, // message-flags: 0 (none)
0x01, 0x00, // num-segments: 1
// segment 1: 10 bytes
0x01, 0x00, // segment-num: 1
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // segment-data-length: 0
// segment-data: empty
// trailer: empty
Příklad – zakódovaná zpráva se dvěma segmenty a kontrolním součtem crc64
// header: 13 bytes
0x01, // message-version: 1
0x3b, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // message-length: 59
0x01, 0x00, // message-flags: 1 (include-crc64)
0x02, 0x00, // num-segments: 2
// segment 1: 19 bytes
0x01, 0x00, // segment-num: 1
0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // segment-data-length: 1
0x11, // segment-data
0xd0, 0x61, 0x67, 0x57, 0xb4, 0x5f, 0x54, 0xd2, // segment-data-crc64
// segment 2: 19 bytes
0x02, 0x00, // segment-num: 2
0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // segment-data-length: 1
0x22, // segment-data
0xd8, 0x4a, 0xfb, 0x9e, 0xa0, 0x4f, 0xc6, 0xda, // segment-data-crc64
// trailer: 8 bytes
0xe2, 0xa6, 0x37, 0x74, 0x50, 0xad, 0xc2, 0xef // message-data-crc64