Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Introdução
Este documento descreve o formato Structured Body utilizado pelas APIs Azure Storage Blob, Ficheiro e DFS para suportar o cálculo eficiente da soma de verificação sobre o conteúdo dos pedidos. Este é um formato binário personalizado que codifica dados (por exemplo, conteúdo de blob ou ficheiro) com somas de verificação finais numa base de soma de verificação. Note que o próprio corpo do pedido é o que está codificado neste formato.
Esta documentação destina-se principalmente a clientes que utilizam diretamente as APIs REST do Azure Storage. Os clientes que utilizam um Azure Storage SDK suportado terão automaticamente os seus pedidos codificados neste formato.
Atualmente, o Azure Storage só suporta a versão 1 deste formato, que apenas suporta checksums crc64. A utilização do formato de mensagem estruturada é opcional.
Specification
Secções
Uma mensagem codificada tem três secçõ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 tem um ou mais segmentos, e cada segmento contém o segmento #, os dados e metadados opcionais de final. Para a v1, o único trailer suportado é um checksum CRC64. |
| Reboque | Cada mensagem tem 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. Tem de ser 1. |
message-length |
uint64 |
Comprimento da mensagem completa. Numa mensagem HTTP, isto deve corresponder ao Content-Length cabeçalho. |
message-flags |
uint16 |
Flags (opções) ativadas para esta mensagem. A versão 1 só suporta um único flag para crc64 os checksums. Ver Bandeiras. |
num-segments |
uint16 |
Número de segmentos contidos na mensagem. Isto deve ser pelo 1menos .
Ver 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/ficheiro do segmento, em bytes. |
segment-data |
byte[dl] |
Bytes de dados de blob/ficheiro. |
segment-data-crc64[^1] |
byte[8] |
Calculou a soma de verificação crc64 para o datasegmento . |
message-data-crc64[^1] |
byte[8] |
Calculei o checksum crc64 para os dados da mensagem (todos os datasegmentos). |
[^1]: As somas de verificação CRC64 estão presentes quando a include-crc64 opção é especificada. Ver Bandeiras.
Flags
O message-flags campo é usado para especificar opções para a mensagem codificada. A versão 1 suporta apenas uma única opção, include-crc64, mas os bits restantes são reservados para opções futuras, como outros algoritmos de soma de verificação e outros metadados.
| Valor | Nome | Description |
|---|---|---|
0x0001 |
include-crc64 |
Incluir somas de verificação crc64 nos segmentos e no trailer de mensagens. |
0x0002-0x8000 |
Reservado para versões futuras. |
Segmentos
As mensagens codificadas são divididas em um ou mais segmentos. Cada segmento contém o seu segmento #, dados do segmento e uma soma de verificação[^1]. Este design permite uma verificação incremental de integridade para pedidos grandes 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 os 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
Num pedido GetBlob ou ReadFile com x-ms-structured-body a configuração apropriada no pedido HTTP, o serviço divide os dados do blob ou ficheiro 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 ficheiros carregados 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 defeito.
Validação de conteúdo CRC64
A validação de conteúdo CRC64 é uma funcionalidade 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). A funcionalidade utiliza um polinómio CRC64 personalizado para validar a integridade do conteúdo transferido. Existem duas formas em que esta soma de verificação pode ser utilizada:
- Corpo estruturado: Os checksums CRC64 estão incorporados no corpo do pedido da API, o que permite validar checksum à medida que os dados são transmitidos.
- Somas de verificação transacionais CRC64 (suportadas apenas em carregamentos): Para cada pedido 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.
Polinómio
Esta variante do CRC64 é refletida em bits (baseada no polinómio não refletido em bits 0xad93d23594c93659) e inverte os bits de entrada e saída do CRC.
Examples
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 Soma de Verificação 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