Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Introductie
Dit document beschrijft het Structured Body-formaat dat wordt gebruikt door de Azure Storage Blob, File en DFS API's om efficiënte checksumberekening over verzoekinhoud te ondersteunen. Dit is een aangepast binair formaat dat gegevens codeert (bijvoorbeeld blob- of bestandsinhoud) met achterlopende controlesommen op controlesombasis. Let op dat het request-lichaam zelf in dit formaat is gecodeerd.
Deze documentatie is voornamelijk gericht op klanten die direct de Azure Storage REST API's gebruiken. Klanten die een ondersteunde Azure Storage SDK gebruiken, krijgen hun verzoeken automatisch gecodeerd in dit formaat.
Momenteel ondersteunt Azure Storage alleen v1 van dit formaat, dat alleen crc64-controlesommen ondersteunt. Het gebruik van het gestructureerde berichtformaat is optioneel.
Specification
Afdelingen
Een gecodeerd bericht bestaat uit drie secties.
| Afdeling | Description |
|---|---|
| Header | De header bevat de schemaversie (1), de berichtlengte, opties en het aantal segmenten. |
| Segment(en) | Elk bericht heeft één of meer segmenten, en elk segment bevat segment #, data en optionele achterliggende metadata. Voor v1 is de enige ondersteunde trailer een crc64 checksum. |
| Aanhangwagen | Elk bericht bevat optionele trailing metadata. Voor v1 is de enige ondersteunde trailer een crc64 checksum. |
Binair Formaat, v1
Het Structured Body v1 binaire formaat wordt gedefinieerd als:
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
Alle gehele datatypen worden gecodeerd als little-endian.
Veldreferentie
| Veld | Typologie | Description |
|---|---|---|
message-version |
uint8 |
Schemaversie van het bericht. Dit moet zijn 1. |
message-length |
uint64 |
Lengte van het volledige bericht. In een HTTP-bericht moet dit overeenkomen met de Content-Length header. |
message-flags |
uint16 |
Vlaggen (opties) ingeschakeld voor dit bericht. De versie 1 ondersteunt slechts één vlag voor crc64 checksums. Zie Vlaggen. |
num-segments |
uint16 |
Aantal segmenten in het bericht. Dit moet minstens 1zo zijn. Zie segmenten |
segment-num |
uint16 |
Het huidige segment #. Het eerste segment is 1 en moet worden verhoogd voor elk volgend segment. |
segment-data-length (dl) |
uint64 |
Lengte van de blob/bestandsdata van het segment, in bytes. |
segment-data |
byte[dl] |
Blob/bestandsdatabytes. |
segment-data-crc64[^1] |
byte[8] |
Berekende de crc64-checksum voor het datasegment . |
message-data-crc64[^1] |
byte[8] |
Berekende crc64-controlesom voor de berichtgegevens (alle segmenten' data.) |
[^1]: CRC64-checksums zijn aanwezig wanneer de include-crc64 optie wordt gespecificeerd. Zie Vlaggen.
Flags
Het message-flags veld wordt gebruikt om opties voor het gecodeerde bericht aan te geven. Versie 1 ondersteunt slechts één optie, include-crc64, maar de overige bits zijn gereserveerd voor toekomstige opties zoals andere checksum-algoritmen en andere metadata.
| Waarde | Naam | Description |
|---|---|---|
0x0001 |
include-crc64 |
Voeg crc64-checksums op in segmenten en berichttrailer. |
0x0002-0x8000 |
Gereserveerd voor toekomstige versies. |
Segmenten
Gecodeerde berichten worden opgesplitst in één of meer segmenten. Elk segment bevat zijn segment #, segmentgegevens en een checksum[^1]. Dit ontwerp maakt incrementele integriteitsverificatie mogelijk voor grote verzoeken en is nuttig om gedeeltelijke downloads te hervatten.
Opmerking
Segmenten worden genummerd beginnend met 1. Het maximale aantal segmenten is 65535.
Lege segmenten
Let op dat segmenten een leeg segment-data veld kunnen hebben. Zie het voorbeeld van een lege blob, dat één enkel, leeg segment heeft. Lege segmenten moeten een segment-data-length van 0 hebben en als include-crc64 ingeschakeld is, moet de geldige checksum worden opgenomen.
Segmentgrootte
Bij een GetBlob- of ReadFile-verzoek met x-ms-structured-body de juiste ingesteldheid in het HTTP-verzoek, zal de service de blob- of bestandsgegevens in 4MiB-segmenten in het gecodeerde antwoord opsplitsen. Als het bericht het maximale aantal segmenten overschrijdt, wordt de segmentgrootte vergroot.
Voor geüploade blob- of bestandsgegevens van een client accepteert de dienst segmenten van elke grootte of verschillende groottes. De aanbeveling is om segmenten van 4 MiB of grotere te gebruiken. De SDK's gebruiken standaard 4MiB segmentgroottes.
CRC64-inhoudsvalidatie
CRC64-inhoudsvalidatie is een functie in de Azure Storage REST API die checksumvalidatie mogelijk maakt voor ondersteunde API's. Er zijn veel varianten van CRC64-algoritmen. CRC64-controlesummen worden berekend met behulp van CRC64-NVME (ook wel CRC64-Rocksoftgenoemd). De functie maakt gebruik van een aangepaste CRC64-polynoom om de integriteit van overgedragen inhoud te valideren. Er zijn twee vormen waarin deze checksum kan worden gebruikt:
- Gestructureerde body: De CRC64-checksums zijn ingebed in het body van het API-verzoek, waardoor checksums kunnen worden gevalideerd terwijl data wordt gestreamd.
- Transactionele CRC64-checksums (alleen ondersteund bij uploads): Voor elk individueel API-verzoek berekent de client de CRC64-checksum en stelt de waarde in op de header,
x-ms-content-crc64. De opslagservice valideert dat de checksum van de ontvangen bytes overeenkomt met de checksum die in de header wordt gegeven.
Polynoom
Deze CRC64-variant is bit-gereflecteerd (gebaseerd op het niet-bit-gereflecteerde polynoom 0xad93d23594c93659) en keert de CRC-invoer- en uitvoerbits om.
Voorbeelden
Voorbeeld - Leeg gecodeerd bericht
Dit voorbeeld toont een bericht dat gecodeerd is met het gestructureerde lichaamsformaat zonder data. Let op dat het bericht een leeg segment moet bevatten.
// 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
Voorbeeld - Leeg gecodeerd bericht zonder crc64
Dit voorbeeld toont een gecodeerd bericht zonder data en zonder de include-crc64 optie ingeschakeld.
// 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
Voorbeeld - Gecodeerd bericht met twee segmenten en crc64 checksum
// 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