Kommentar
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
Introduction
Detta dokument beskriver formatet Structured Body som används av Azure Storage Blob-, File- och DFS-API:erna för att stödja effektiv kontrollsummeberäkning över begäran. Detta är ett anpassat binärt format som kodar data (t.ex. blob- eller filinnehåll) med efterföljande kontrollsummor på kontrollsumma. Observera att själva förfrågningskroppen är det som kodas i detta format.
Denna dokumentation riktar sig främst till kunder som använder Azure Storage REST API:erna direkt. Kunder som använder ett stödd Azure Storage SDK kommer automatiskt att få sina förfrågningar kodade i detta format.
För närvarande stöder Azure Storage endast v1 av detta format, som endast stöder crc64-kontrollsummor. Användning av det strukturerade meddelandeformatet är frivilligt.
Specification
Sektioner
Ett kodat meddelande har tre sektioner.
| Section | Description |
|---|---|
| Header | Headern innehåller schemaversionen (1), meddelandelängd, alternativ och antal segment. |
| Segment(er) | Varje meddelande har ett eller flera segment, och varje segment innehåller segment #, data och valfri efterföljande metadata. För v1 är den enda stödda trailern en crc64-checksum. |
| Trailer | Varje meddelande har valfri efterföljande metadata. För v1 är den enda stödda trailern en crc64-checksum. |
Binärformat, v1
Det strukturerade kroppen v1 binärformatet definieras som:
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
Alla heltalsdatatyper kodas som little-endian.
Fältreferens
| Fält | Typ | Description |
|---|---|---|
message-version |
uint8 |
Schemaversionen av meddelandet. Detta måste vara 1. |
message-length |
uint64 |
Längden på hela meddelandet. I ett HTTP-meddelande måste detta matcha Content-Length headern. |
message-flags |
uint16 |
Flaggor (alternativ) aktiverade för detta meddelande. Versionen 1 stöder endast en enda flagga för crc64 kontrollsummor. Se Flaggor. |
num-segments |
uint16 |
Antal segment som ingår i meddelandet. Det här måste vara minst 1. Se segment |
segment-num |
uint16 |
Det nuvarande segmentet #. Det första segmentet är 1 och måste öka för varje efterföljande segment. |
segment-data-length (dl) |
uint64 |
Längden på segmentets blob/fildata, i bytes. |
segment-data |
byte[dl] |
Blob/fildatabyte. |
segment-data-crc64[^1] |
byte[8] |
Beräknade crc64-kontrollsumman för segmentets data. |
message-data-crc64[^1] |
byte[8] |
Beräknad crc64-kontrollsumma för meddelandedata (alla segment' data.) |
[^1]: CRC64-kontrollsummor finns när include-crc64 alternativet specificeras. Se Flaggor.
Flags
Fältet message-flags används för att specificera alternativ för det kodade meddelandet. Version 1 stöder endast ett enda alternativ, include-crc64, men de återstående bitarna är reserverade för framtida alternativ såsom andra kontrollsummealgoritmer och annan metadata.
| Värde | Namn | Description |
|---|---|---|
0x0001 |
include-crc64 |
Inkludera crc64-kontrollsummor i segment och meddelandetrailer. |
0x0002-0x8000 |
Reserverat för framtida versioner. |
Segment
Kodade meddelanden delas upp i ett eller flera segment. Varje segment innehåller sitt segment #, segmentdata och en kontrollsumma[^1]. Denna design möjliggör inkrementell integritetsverifiering för stora förfrågningar och är användbar för att återuppta partiella nedladdningar.
Anmärkning
Segment numreras med start .1 Det maximala antalet segment är 65535.
Tomma segment
Observera att segment kan ha ett tomt segment-data fält. Se exemplet på den tomma blobben, som har ett enda, tomt segment. Tomma segment måste ha ett segment-data-length av 0 och om include-crc64 aktiverat måste det inkludera den giltiga kontrollsumman.
Segmentstorlek
Vid en GetBlob- eller ReadFile-förfrågan med x-ms-structured-body lämplig inställning i HTTP-förfrågan delar tjänsten upp blob- eller fildata i 4MiB-segment i det kodade svaret. Om meddelandet skulle överstiga det maximala antalet segment, kommer segmentstorleken att ökas.
För uppladdad blob- eller fildata från en klient accepterar tjänsten segment av valfri storlek eller varierande storlek. Rekommendationen är att använda 4 MiB eller större segmentstorlekar. SDK:erna använder 4 MiB segmentstorlekar som standard.
CRC64-innehållsvalidering
CRC64-innehållsvalidering är en funktion i Azure Storage REST API som möjliggör validering av kontrollsummor för stödda API:er. Det finns många varianter av CRC64-algoritmer. CRC64-kontrollsummor beräknas med CRC64-NVME (även kallad CRC64-Rocksoft). Funktionen använder ett anpassat CRC64-polynom för att validera integriteten hos överfört innehåll. Det finns två former av vilka denna kontrollsumma kan användas:
- Strukturerad kropp: CRC64-kontrollsummorna är inbäddade i API-förfrågan, vilket möjliggör validering av kontrollsummor när data strömmas.
- Transaktionella CRC64-kontrollsummor (stöds endast vid uppladdningar): För varje enskild API-förfrågan beräknar klienten CRC64-kontrollsumman och sätter värdet till headern,
x-ms-content-crc64. Lagringstjänsten validerar att kontrollsumman av de mottagna byten matchar kontrollsumman som anges i headern.
Polynom
Denna CRC64-variant är bitreflekterad (baserad på det icke-bitreflekterade polynomet 0xad93d23594c93659) och inverterar CRC:s in- och utgångsbitar.
Examples
Exempel – Tomt kodat meddelande
Detta exempel visar ett meddelande kodat med det strukturerade brödtextformatet utan data. Observera att meddelandet måste innehålla ett tomt 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
Exempel – Tomt kodat meddelande utan crc64
Detta exempel visar ett kodat meddelande utan data och utan include-crc64 att alternativet är aktiverat.
// 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
Exempel – Kodat meddelande med två segment och crc64-kontrollsumma
// 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