Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Introdução
Este documento descreve o formato Structured Body usado pelas APIs Azure Storage Blob, File e DFS para suportar o cálculo eficiente de checksum sobre o conteúdo das requisições. Este é um formato binário personalizado que codifica dados (por exemplo, conteúdo de blob ou arquivo) com checkamounts finais em base a um checksum. Note que o corpo da solicitação é o que está codificado nesse formato.
Esta documentação é direcionada principalmente a clientes que utilizam diretamente as APIs REST do Azure Storage. Clientes que utilizam um Azure Storage SDK suportado terão automaticamente suas requisições codificadas nesse formato.
Atualmente, o Azure Storage suporta apenas a versão 1 desse formato, que suporta apenas checksums crc64. O uso do formato de mensagem estruturada é opcional.
Specification
Seções
Uma mensagem codificada possui três seções.
| Seção | Description |
|---|---|
| Header | O cabeçalho contém a versão do esquema (1), o comprimento da mensagem, as opções e o número de segmentos. |
| Segmento(s) | Cada mensagem possui um ou mais segmentos, e cada segmento contém o segmento #, dados e metadados opcionais de final. Para a v1, o único trailer suportado é um checksum CRC64. |
| Reboque | Cada mensagem possui metadados finais opcionais. Para a v1, o único trailer suportado é um checksum CRC64. |
Formato Binário, v1
O formato binário Structured Body v1 é definido 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 os tipos de dados inteiros são codificados como little-endian.
Referência de Campo
| Campo | Tipo | Description |
|---|---|---|
message-version |
uint8 |
Versão esquemática da mensagem. Isso deve ser 1. |
message-length |
uint64 |
Extensão da mensagem completa. Em uma mensagem HTTP, isso deve corresponder ao Content-Length cabeçalho. |
message-flags |
uint16 |
Flags (opções) ativadas para esta mensagem. A versão 1 suporta apenas uma única flag para crc64 checksums. Veja Bandeiras. |
num-segments |
uint16 |
Número de segmentos contidos na mensagem. Isso deve ser pelo 1menos . Veja Segmentos |
segment-num |
uint16 |
O segmento atual #. O primeiro segmento é 1 e deve incrementar para cada segmento subsequente. |
segment-data-length (dl) |
uint64 |
Comprimento dos dados do blob/arquivo do segmento, em bytes. |
segment-data |
byte[dl] |
Bytes de dados de blob/arquivo. |
segment-data-crc64[^1] |
byte[8] |
Calculou a soma de verificação crc64 para o datasegmento . |
message-data-crc64[^1] |
byte[8] |
Calculou a soma de verificação do crc64 para os dados da mensagem (todos os segmentos data). |
[^1]: As somas de verificação CRC64 estão presentes quando a include-crc64 opção é especificada. Veja Bandeiras.
Flags
O message-flags campo é usado para especificar opções para a mensagem codificada. A versão 1 suporta apenas uma opção, include-crc64, mas os bits restantes são reservados para opções futuras, como outros algoritmos de checksum e outros metadados.
| Value | Nome | Description |
|---|---|---|
0x0001 |
include-crc64 |
Inclua as somas de verificação CRC64 nos segmentos e no trailer de mensagens. |
0x0002-0x8000 |
Reservado para versões futuras. |
Segmentos
Mensagens codificadas são divididas em um ou mais segmentos. Cada segmento contém seu segmento #, dados do segmento e uma soma de verificação[^1]. Esse design permite verificação incremental de integridade para grandes solicitações e é útil para retomar downloads parciais.
Observação
Os segmentos são numerados começando por 1. O número máximo de segmentos é 65535.
Segmentos vazios
Note que segmentos podem ter um campo vazio segment-data . Veja o exemplo do blob vazio, que tem um único segmento vazio. Segmentos vazios devem ter um segment-data-length de 0 e, se include-crc64 estiver ativado, devem incluir a soma de verificação válida.
Tamanho do segmento
Em uma requisição GetBlob ou ReadFile com x-ms-structured-body o conjunto apropriado na requisição HTTP, o serviço irá fragmentar os dados do blob ou arquivo em segmentos de 4MiB na resposta codificada. Se a mensagem exceder o número máximo de segmentos, o tamanho do segmento será aumentado.
Para dados de blobs ou arquivos enviados de um cliente, o serviço aceitará segmentos de qualquer tamanho ou tamanhos variados. A recomendação é usar segmentos de 4MiB ou maiores. Os SDKs usam tamanhos de segmento de 4MiB por padrão.
Validação de conteúdo CRC64
A validação de conteúdo CRC64 é um recurso na API REST do Azure Storage que permite a validação de soma de verificação para APIs suportadas. Existem muitas variantes dos algoritmos CRC64. As somas de verificação CRC64 são calculadas usando CRC64-NVME (também conhecido como CRC64-Rocksoft). O recurso utiliza um polinômio CRC64 personalizado para validar a integridade do conteúdo transferido. Existem duas formas em que esse checksum pode ser utilizado:
- Corpo estruturado: Os checksums CRC64 estão incorporados ao corpo da solicitação da API, o que permite validar checksum conforme os dados são transmitidos.
- Checksums transacionais CRC64 (suportados apenas em uploads): Para cada requisição individual de API, o cliente calcula a soma de verificação CRC64 e define o valor para o cabeçalho,
x-ms-content-crc64. O serviço de armazenamento valida que a soma de verificação dos bytes recebidos corresponde à soma de verificação fornecida no cabeçalho.
Polinomial
Essa variante do CRC64 é refletida em bits (baseada no polinômio não refletido por bits) 0xad93d23594c93659) e inverte os bits de entrada e saída do CRC.
Exemplos
Exemplo - Mensagem Codificada Vazia
Este exemplo mostra uma mensagem codificada com o formato estruturado do corpo, sem dados. Note que a mensagem deve conter um segmento vazio.
// 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
Exemplo - Mensagem Codificada Vazia sem CRC64
Este exemplo mostra uma mensagem codificada sem dados e sem a include-crc64 opção ativada.
// 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
Exemplo - Mensagem Codificada com Dois Segmentos 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