Formato de cuerpo estructurado

Introducción

Este documento describe el formato de Cuerpo Estructurado utilizado por las APIs de Blob, Archivo y DFS de Azure Storage para soportar el cálculo eficiente de suma de comprobación sobre el contenido de las solicitudes. Este es un formato binario personalizado que codifica datos (por ejemplo, contenido de blob o archivo) con sumas de comprobación posteriores en base a suma de comprobación. Ten en cuenta que el cuerpo de la solicitud es lo que se codifica en este formato.

Esta documentación está dirigida principalmente a clientes que utilizan directamente las APIs REST de Azure Storage. Los clientes que usen un SDK de almacenamiento de Azure compatible tendrán automáticamente sus solicitudes codificadas en este formato.

Actualmente, Azure Storage solo soporta la versión 1 de este formato, que solo soporta sumas de comprobación crc64. El uso del formato de mensaje estructurado es opcional.

Specification

Secciones

Un mensaje codificado tiene tres secciones.

Section Description
Header El encabezado contiene la versión del esquema (1), la longitud del mensaje, las opciones y el número de segmentos.
Segmento(s) Cada mensaje tiene uno o más segmentos, y cada segmento contiene el segmento #, los datos y metadatos opcionales de final. Para la v1, el único tráiler compatible es una suma de comprobación CRC64.
Remolque Cada mensaje tiene metadatos opcionales de final. Para la v1, el único tráiler compatible es una suma de comprobación CRC64.

Formato binario, v1

El formato binario Structured Body v1 se define como:

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

Todos los tipos de datos enteros se codifican como little-endian.

Referencia de campo

Campo Tipo Description
message-version uint8 Versión esquemática del mensaje. Debe ser 1.
message-length uint64 Longitud del mensaje completo. En un mensaje HTTP, esto debe coincidir con la Content-Length cabecera.
message-flags uint16 Banderas (opciones) activadas para este mensaje. La versión 1 solo soporta una única bandera para crc64 las sumas de comprobación. Ver Banderas.
num-segments uint16 Número de segmentos contenidos en el mensaje. Esto debe ser al 1menos . Ver Segmentos
segment-num uint16 El segmento actual #. El primer segmento es 1 y debe incrementarse para cada segmento siguiente.
segment-data-length (dl) uint64 Longitud de los datos de blob/archivo del segmento, en bytes.
segment-data byte[dl] Bytes de datos de blob/archivo.
segment-data-crc64[^1] byte[8] Calculé la suma de comprobación crc64 para el datasegmento .
message-data-crc64[^1] byte[8] Calculé la suma de comprobación de crc64 para los datos del mensaje (todos los segmentos data.)

[^1]: Las sumas de comprobación CRC64 están presentes cuando se especifica la include-crc64 opción. Ver Banderas.

Flags

El message-flags campo se utiliza para especificar opciones para el mensaje codificado. La versión 1 solo admite una única opción, include-crc64, pero los bits restantes están reservados para opciones futuras como otros algoritmos de suma de comprobación y otros metadatos.

Importancia Nombre Description
0x0001 include-crc64 Incluye sumas de verificación crc64 en los segmentos y el tráiler de mensajes.
0x0002-0x8000 Reservado para futuras versiones.

Segmentos

Los mensajes codificados se dividen en uno o más segmentos. Cada segmento contiene su segmento #, datos del segmento y una suma de comprobación[^1]. Este diseño permite una verificación incremental de integridad para solicitudes grandes y es útil para reanudar descargas parciales.

Nota:

Los segmentos se numeran comenzando por 1. El número máximo de segmentos es 65535.

Segmentos vacíos

Ten en cuenta que los segmentos pueden tener un campo vacío segment-data . Véase el ejemplo del blob vacío, que tiene un solo segmento vacío. Los segmentos vacíos deben tener un segment-data-length de 0 y, si include-crc64 está habilitado, deben incluir la suma de comprobación válida.

Tamaño del segmento

En una solicitud GetBlob o ReadFile con x-ms-structured-body el conjunto adecuado en la petición HTTP, el servicio fragmentará los datos del blob o archivo en segmentos de 4MiB en la respuesta codificada. Si el mensaje supera el número máximo de segmentos, el tamaño del segmento aumentará.

Para datos de blob o archivo subidos desde un cliente, el servicio aceptará segmentos de cualquier tamaño o de diferentes tamaños. La recomendación es usar segmentos de 4 MiB o mayores. Los SDKs usan tamaños de segmento de 4MiB por defecto.

Validación de contenido CRC64

La validación de contenido CRC64 es una función de la API REST de Azure Storage que permite la validación de sumas de comprobación para las APIs soportadas. Existen muchas variantes de los algoritmos CRC64. Las sumas de comprobación CRC64 se calculan usando CRC64-NVME (también conocido como CRC64-Rocksoft). La función utiliza un polinomio CRC64 personalizado para validar la integridad del contenido transferido. Existen dos formas en las que se puede utilizar esta suma de control:

  • Cuerpo estructurado: Las sumas de comprobación CRC64 están integradas en el cuerpo de la solicitud API, lo que permite validar las sumas de comprobación a medida que se transmiten datos.
  • Sumas de comprobación transaccionales CRC64 (soportadas solo en subidas): Para cada solicitud individual de API, el cliente calcula la suma de comprobación CRC64 y establece el valor en la cabecera, x-ms-content-crc64. El servicio de almacenamiento valida que la suma de comprobación de los bytes recibidos coincide con la suma de comprobación proporcionada en la cabecera.

Polinomio

Esta variante de CRC64 es reflejada en bits (basada en el polinomio no reflejado en bits 0xad93d23594c93659) e invierte los bits de entrada y salida del CRC.

Examples

Ejemplo - Mensaje codificado vacío

Este ejemplo muestra un mensaje codificado con el formato estructurado del cuerpo sin datos. Ten en cuenta que el mensaje debe contener un segmento vacío.

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

Ejemplo: mensaje codificado vacío sin crc64

Este ejemplo muestra un mensaje codificado sin datos y sin la include-crc64 opción activada.

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

Ejemplo: Mensaje codificado con dos segmentos y suma de verificación 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