Formato strutturato del corpo

Introduzione

Questo documento descrive il formato Structured Body utilizzato dalle API Azure Storage Blob, File e DFS per supportare un calcolo efficiente del checksum sui contenuti delle richieste. Si tratta di un formato binario personalizzato che codifica dati (ad esempio, contenuto di blob o file) con checksums finali su base di checksum. Si noti che il corpo della richiesta stesso è quello codificato in questo formato.

Questa documentazione è principalmente rivolta ai clienti che utilizzano direttamente le API REST di Azure Storage. I clienti che utilizzano un Azure Storage SDK supportato vedranno automaticamente le loro richieste codificate in questo formato.

Attualmente, Azure Storage supporta solo la versione 1 di questo formato, che supporta solo i checksum crc64. L'uso del formato del messaggio strutturato è opzionale.

Specification

Sezioni

Un messaggio codificato ha tre sezioni.

Sezione Description
Header L'intestazione contiene la versione dello schema (1), la lunghezza del messaggio, le opzioni e il numero di segmenti.
Segmento/i Ogni messaggio ha uno o più segmenti, e ogni segmento contiene il segmento #, i dati e metadati opzionali di seguimento. Per la v1, l'unico trailer supportato è un checksum CRC64.
Rimorchio Ogni messaggio ha metadati finali opzionali. Per la v1, l'unico trailer supportato è un checksum CRC64.

Formato binario, v1

Il formato binario Structured Body v1 è definito come:

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

Tutti i tipi di dati interi sono codificati come little-endian.

Riferimento sul campo

Campo TIPO Description
message-version uint8 Versione schema del messaggio. Deve essere 1.
message-length uint64 Lunghezza del messaggio completo. In un messaggio HTTP, questo deve corrispondere all'intestazione Content-Length (header).
message-flags uint16 Flag (opzioni) attivati per questo messaggio. La versione 1 supporta solo un singolo indicatore per crc64 le checksum. Vedi Flag.
num-segments uint16 Numero di segmenti contenuti nel messaggio. Questo deve essere almeno 1. Vedi Segmenti
segment-num uint16 Il segmento attuale #. Il primo segmento è 1 e deve incrementarsi per ogni segmento successivo.
segment-data-length (dl) uint64 Lunghezza dei dati del blob/file del segmento, in byte.
segment-data byte[dl] Byte dati blob/file.
segment-data-crc64[^1] byte[8] Calcolò il checksum crc64 per il datasegmento .
message-data-crc64[^1] byte[8] Calcolato il checksum crc64 per i dati del messaggio (tutti i datasegmenti .)

[^1]: I checksum CRC64 sono presenti quando l'opzione include-crc64 viene specificata. Vedi Flag.

Flags

Il message-flags campo viene utilizzato per specificare le opzioni per il messaggio codificato. La versione 1 supporta solo un'opzione, include-crc64, ma i bit rimanenti sono riservati a opzioni future come altri algoritmi di checksum e altri metadati.

Value Nome Description
0x0001 include-crc64 Includere checksum crc64 nei segmenti e nel trailer dei messaggi.
0x0002-0x8000 Riservato alle versioni future.

Segmenti

I messaggi codificati sono suddivisi in uno o più segmenti. Ogni segmento contiene il proprio segmento #, i dati del segmento e un checksum[^1]. Questo design consente una verifica incrementale dell'integrità per richieste di grandi dimensioni ed è utile per la ripresa di download parziali.

Annotazioni

I segmenti sono numerati a partire da 1. Il numero massimo di segmenti è 65535.

Segmenti vuoti

Si noti che i segmenti possono avere un campo vuoto segment-data . Vedi l'esempio del blob vuoto, che ha un singolo segmento vuoto. I segmenti vuoti devono avere un segment-data-length di 0 e se include-crc64 è abilitato, devono includere il checksum valido.

Dimensione del segmento

Su una richiesta GetBlob o ReadFile con x-ms-structured-body l'impostazione appropriata nella richiesta HTTP, il servizio suddivide i dati del blob o del file in segmenti da 4MiB nella risposta codificata. Se il messaggio supera il numero massimo di segmenti, la dimensione del segmento aumenterà.

Per i dati di blob o file caricati da un client, il servizio accetterà segmenti di qualsiasi dimensione o dimensioni variabili. La raccomandazione è di utilizzare segmenti di 4MiB o più grandi. Gli SDK utilizzano di default dimensioni di segmento da 4MiB.

Validazione dei contenuti CRC64

La validazione dei contenuti CRC64 è una funzionalità dell'API REST di Azure Storage che consente la validazione dei checksum per le API supportate. Esistono molte varianti degli algoritmi CRC64. I checksum CRC64 vengono calcolati usando CRC64-NVME (noto anche come CRC64-Rocksoft). La caratteristica utilizza un polinomio CRC64 personalizzato per validare l'integrità dei contenuti trasferiti. Esistono due forme in cui questo checksum può essere utilizzato:

  • Corpo strutturato: I checksum CRC64 sono incorporati nel corpo della richiesta API, il che consente di validare i checksum man mano che i dati vengono trasmessi in streaming.
  • Checksum transazionali CRC64 (supportati solo nei caricamenti): Per ogni singola richiesta API, il client calcola il checksum CRC64 e imposta il valore all'intestazione . x-ms-content-crc64 Il servizio di archiviazione verifica che il checksum dei byte ricevuti corrisponda al checksum fornito nell'intestazione del test.

Polinomio

Questa variante CRC64 è riflessa su bit (basata sul polinomio non riflesso su bit 0xad93d23594c93659) e inverte i bit di ingresso e uscita del CRC.

Esempi

Esempio - Messaggio codificato vuoto

Questo esempio mostra un messaggio codificato con il formato strutturato del corpo senza dati. Si noti che il messaggio deve contenere un segmento vuoto.

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

Esempio - Messaggio codificato vuoto senza crc64

Questo esempio mostra un messaggio codificato senza dati e senza l'opzione include-crc64 attivata.

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

Esempio - Messaggio codificato con due segmenti e checksum 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