Format structuré du corps

Présentation

Ce document décrit le format Structured Body utilisé par les API Azure Storage Blob, Fichier et DFS pour soutenir le calcul efficace de la somme de contrôle sur le contenu des requêtes. Il s’agit d’un format binaire personnalisé qui encode les données (par exemple, le contenu de blob ou de fichier) avec des sommes de contrôle de suivi sur une base de somme de contrôle. Notez que le corps de la requête lui-même est ce qui est encodé dans ce format.

Cette documentation s’adresse principalement aux clients utilisant directement les API REST d’Azure Storage. Les clients utilisant un SDK de stockage Azure pris en charge verront automatiquement leurs requêtes encodées dans ce format.

Actuellement, Azure Storage ne prend en charge que la version 1 de ce format, qui ne prend en charge que les sommes de contrôle CRC64. L’utilisation du format de message structuré est optionnelle.

Specification

Rubriques

Un message codé comporte trois sections.

Section	Descriptif
Header	L’en-tête contient la version du schéma (1), la longueur du message, les options et le nombre de segments.
Segment(s)	Chaque message comporte un ou plusieurs segments, et chaque segment contient le segment #, les données et des métadonnées optionnelles de suite. Pour la v1, la seule bande-annonce prise en charge est un checksum CRC64.
Remorque	Chaque message comporte des métadonnées de fin optionnelles. Pour la v1, la seule bande-annonce prise en charge est un checksum CRC64.

Format binaire, v1

Le format binaire Structured Body v1 est défini comme suit :

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

Tous les types de données entières sont codés en little-endian.

Référence de terrain

Terrain	Type	Descriptif
`message-version`	`uint8`	Version schéma du message. Cela doit être `1`.
`message-length`	`uint64`	Longueur du message complet. Dans un message HTTP, cela doit correspondre à l’en-tête `Content-Length` .
`message-flags`	`uint16`	Drapeaux (options) activés pour ce message. La version `1` ne prend en charge qu’un seul drapeau pour `crc64` les sommes de contrôle. Voir Drapeaux.
`num-segments`	`uint16`	Nombre de segments contenus dans le message. Cela doit être au `1`moins . Voir les segments

`segment-num`	`uint16`	Le segment actuel #. Le premier segment est `1` et doit incrémenter pour chaque segment suivant.
`segment-data-length (dl)`	`uint64`	Longueur des données blob/fichier du segment, en octets.
`segment-data`	`byte[dl]`	Octets de données blob/fichier.
`segment-data-crc64`[^1]	`byte[8]`	Calcul de la somme de contrôle crc64 pour le `data`segment .

`message-data-crc64`[^1]	`byte[8]`	Calcul de la somme de contrôle crc64 pour les données du message (tous les segments `data`.)

[^1] : Les sommes de contrôle CRC64 sont présentes lorsque l’option include-crc64 est spécifiée. Voir Drapeaux.

Flags

Le message-flags champ sert à spécifier les options pour le message encodé. La version 1 ne prend en charge qu’une seule option, include-crc64, mais les bits restants sont réservés à de futures options telles que d’autres algorithmes de somme de contrôle et d’autres métadonnées.

Valeur	Nom	Descriptif
`0x0001`	`include-crc64`	Inclure les sommes de contrôle crc64 dans les segments et la bande-annonce du message.
`0x0002-0x8000`		Réservé aux versions futures.

Segments

Les messages encodés sont divisés en un ou plusieurs segments. Chaque segment contient son segment #, ses données de segment et une somme de contrôle[^1]. Cette conception permet une vérification incrémentale de l’intégrité pour les grandes requêtes, et est utile pour reprendre les téléchargements partiels.

Note

Les segments sont numérotés à partir de 1. Le nombre maximal de segments est 65535.

Segments vides

Notez que les segments peuvent avoir un champ vide segment-data . Voir l’exemple de blob vide, qui possède un seul segment vide. Les segments vides doivent avoir un segment-data-length de 0 et si include-crc64 activé est activé, doivent inclure la somme de contrôle valide.

Taille du segment

Sur une requête GetBlob ou ReadFile avec x-ms-structured-body un défini approprié dans la requête HTTP, le service fragmente les données du blob ou du fichier en segments de 4 Mo dans la réponse encodée. Si le message dépasse le nombre maximal de segments, la taille du segment sera augmentée.

Pour les données de blob ou de fichiers téléchargées depuis un client, le service acceptera des segments de n’importe quelle taille ou de tailles variées. La recommandation est d’utiliser des segments de 4MiO ou plus. Les SDK utilisent par défaut des tailles de segment de 4MiB.

Validation de contenu CRC64

La validation de contenu CRC64 est une fonctionnalité de l’API REST Azure Storage qui permet la validation de la somme de contrôle pour les API prises en charge. Il existe de nombreuses variantes des algorithmes CRC64. Les sommes de contrôle CRC64 sont calculées en utilisant CRC64-NVME (également appelé CRC64-Rocksoft). La fonctionnalité utilise un polynôme CRC64 personnalisé pour valider l’intégrité du contenu transféré. Il existe deux formes sous lesquelles cette somme de contrôle peut être utilisée :

Corps structuré : Les sommes de contrôle CRC64 sont intégrées dans le corps de la requête API, ce qui permet de valider les sommes de contrôle au fur et à mesure de l’envoi des données.
Sommes de contrôle CRC64 transactionnelles (prises en charge uniquement dans les téléchargements) : Pour chaque requête API individuelle, le client calcule la somme de contrôle CRC64 et fixe la valeur à l’en-tête, x-ms-content-crc64. Le service de stockage valide que la somme de contrôle des octets reçus correspond à celle fournie dans l’en-tête.

Polynôme

Cette variante CRC64 est réfléchie en bits (basée sur le polynôme non réfléchi en bits) 0xad93d23594c93659) et inverse les bits d’entrée et de sortie du CRC.

Examples

Exemple - Message encodé vide

Cet exemple montre un message encodé avec le format structuré du corps sans données. Notez que le message doit contenir un segment vide.

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

Exemple - Message encodé vide sans crc64

Cet exemple montre un message codé sans données et sans l’option include-crc64 activée.

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

Exemple - Message encodé avec deux segments et somme de contrôle 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

Last updated on 2026-01-22