Strukturiertes Körperformat

Einleitung

Dieses Dokument beschreibt das Structured Body-Format, das von den Azure Storage Blob-, Datei- und DFS-APIs verwendet wird, um eine effiziente Kontrollsummenberechnung über Anfrageinhalte zu unterstützen. Dies ist ein benutzerdefiniertes Binärformat, das Daten (z. B. Blob- oder Dateiinhalte) mit nachlaufenden Prüfsummen auf Prüfsummenbasis kodiert. Beachten Sie, dass der Anforderungskörper selbst in dieses Format kodiert ist.

Diese Dokumentation richtet sich hauptsächlich an Kunden, die die Azure Storage REST APIs direkt nutzen. Kunden, die ein unterstütztes Azure Storage SDK verwenden, werden ihre Anfragen automatisch in diesem Format kodiert.

Derzeit unterstützt Azure Storage nur Version 1 dieses Formats, die nur crc64-Prüfsummen unterstützt. Die Verwendung des strukturierten Nachrichtenformats ist optional.

Specification

Abschnitte

Eine codierte Nachricht besteht aus drei Abschnitten.

Binärformat, v1

Das Binärformat Structured Body v1 ist definiert 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 ganzzahligen Datentypen werden als Little-Endian codiert.

Feldreferenz

[^1]: CRC64-Prüfsummen sind vorhanden, wenn die include-crc64 Option angegeben wird. Siehe Flags.

Flags

Das Feld message-flags wird verwendet, um Optionen für die codierte Nachricht anzugeben. Version 1 unterstützt nur eine einzige Option, include-crc64, aber die übrigen Bits sind für zukünftige Optionen wie andere Prüfsummenalgorithmen und andere Metadaten reserviert.

Segmente

Codierte Nachrichten werden in ein oder mehrere Segmente aufgeteilt. Jedes Segment enthält sein Segment #, Segmentdaten und eine Prüfsumme[^1]. Dieses Design ermöglicht eine inkrementelle Integritätsverifikation für große Anfragen und ist nützlich, um teilweise Downloads fortzusetzen.

Leere Segmente

Beachte, dass Segmente ein leeres segment-data Feld haben können. Siehe das Beispiel für einen leeren Blob, der ein einzelnes, leeres Segment hat. Leere Segmente müssen ein segment-data-length von 0 haben, und wenn include-crc64 aktiviert ist, müssen sie die gültige Prüfsumme enthalten.

Segmentgröße

Bei einer GetBlob- oder ReadFile-Anfrage mit x-ms-structured-body entsprechender Einstellung in der HTTP-Anfrage segmentiert der Dienst die Blob- oder Dateidaten in 4MiB-Segmente in der codierten Antwort. Wenn die Nachricht die maximale Anzahl an Segmenten überschreitet, wird die Segmentgröße erhöht.

Für hochgeladene Blob- oder Dateidaten von einem Client akzeptiert der Dienst Segmente beliebiger Größe oder unterschiedlicher Größe. Die Empfehlung ist, 4 MiB oder größere Segmentgrößen zu verwenden. Die SDKs verwenden standardmäßig 4MiB-Segmentgrößen.

CRC64-Inhaltsvalidierung

Die CRC64-Inhaltsvalidierung ist eine Funktion in der Azure Storage REST API, die die Prüfsummenvalidierung für unterstützte APIs ermöglicht. Es gibt viele Varianten der CRC64-Algorithmen. CRC64-Prüfsummen werden mit CRC64-NVME berechnet (auch bekannt als CRC64-Rocksoft). Die Funktion verwendet ein benutzerdefiniertes CRC64-Polynom, um die Integrität der übertragenen Inhalte zu validieren. Es gibt zwei Formen, in denen diese Prüfsumme verwendet werden kann:

• Strukturierter Körper: Die CRC64-Prüfsummen sind in den Kern der API-Anfrage eingebettet, was es ermöglicht, Prüfsummen zu validieren, während Daten gestreamt werden.
• Transaktionale CRC64-Prüfsummen (nur bei Uploads unterstützt): Für jede einzelne API-Anfrage berechnet der Client die CRC64-Prüfsumme und setzt den Wert auf den Header, x-ms-content-crc64. Der Speicherdienst prüft, dass die Kontrollsumme der empfangenen Bytes mit der im Header angegebenen Kontrollsumme übereinstimmt.

Polynom

Diese CRC64-Variante ist bit-reflektiert (basierend auf dem nicht bit-reflektierten Polynom 0xad93d23594c93659) und invertiert die CRC-Ein- und Ausgabebits.

Examples

Beispiel – leere codierte Nachricht

Dieses Beispiel zeigt eine Nachricht, die mit dem strukturierten Body-Format ohne Daten codiert ist. Beachten Sie, dass die Nachricht ein leeres Segment enthalten muss.

// 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

Beispiel – leere codierte Nachricht ohne crc64

Dieses Beispiel zeigt eine codierte Nachricht ohne Daten und ohne aktivierte Option include-crc64 .

// 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

Beispiel – codierte Nachricht mit zwei Segmenten und crc64-Prüfsumme

// 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