Структурированный формат кузова

Введение

В этом документе описывается формат структурированного тела, используемый Azure Storage Blob, File и DFS API для эффективного вычисления контрольной суммы по содержимому запроса. Это пользовательский двоичный формат, который кодирует данные (например, blob или содержимое файла) с выпадающими контрольными суммами на основе контрольных сумм. Обратите внимание, что именно тело запроса — это то, что кодируется в этом формате.

Эта документация в первую очередь ориентирована на клиентов, использующих Azure Storage REST API напрямую. Клиенты, использующие поддерживаемый Azure Storage SDK, автоматически получают свои запросы в этом формате.

В настоящее время Azure Storage поддерживает только v1 этого формата, который поддерживает только контрольные суммы crc64. Использование формата структурированного сообщения является необязательным.

Specification

Разделы

Закодированное сообщение состоит из трёх частей.

Секция	Description
Header	Заголовок содержит версию схемы (1), длину сообщения, опции и количество сегментов.
Сегмент(ы)	Каждое сообщение содержит один или несколько сегментов, и каждый сегмент содержит сегмент #, данные и опциональные сложные метаданные. Для версии 1 единственным поддерживаемым трейлером является контрольная сумма crc64.
Прицеп	Каждое сообщение содержит опциональные сложные метаданные. Для версии 1 единственным поддерживаемым трейлером является контрольная сумма crc64.

Бинарный формат, v1

Бинарный формат Structured Body v1 определяется как:

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

Все целочисленные типы данных кодируются как little-endian.

Полевы справочник

Поле	Тип	Description
message-version	uint8	Схема сообщения. Это должно быть 1.
message-length	uint64	Длина полного сообщения. В HTTP-сообщении это должно совпадать с Content-Length заголовком.
message-flags	uint16	Флаги (параметры) включены для этого сообщения. Версия 1 поддерживает только один флаг для crc64 контрольных сумм. См. Флаги.
num-segments	uint16	Количество сегментов, содержащихся в сообщении. Это, должно быть, как минимум 1. См. сегменты
segment-num	uint16	Текущий сегмент #. Первый сегмент является 1 и должен увеличиваться для каждого следующего.
segment-data-length (dl)	uint64	Длина данных blob/файла сегмента, в байтах.
segment-data	byte[dl]	Байты данных blob/файл.
segment-data-crc64[^1]	byte[8]	Вычислен контрольная сумма crc64 для сегмента data.
message-data-crc64[^1]	byte[8]	Вычислен контрольная сумма crc64 для данных сообщения (всех сегментов data.)

[^1]: При задании include-crc64 опции присутствуют контрольные суммы CRC64. См. Флаги.

Flags

Это message-flags поле используется для указания опций для закодированного сообщения. Версия 1 поддерживает только один вариант include-crc64, а оставшиеся биты зарезервированы для будущих вариантов, таких как другие алгоритмы контрольной суммы и другие метаданные.

Ценность	Имя	Description
0x0001	include-crc64	Включайте контрольные суммы crc64 в сегменты и трейлер сообщений.
0x0002-0x8000		Зарезервировано для будущих версий.

Сегменты

Закодированные сообщения делятся на один или несколько сегментов. Каждый сегмент содержит свой сегмент #, данные сегмента и контрольную сумму[^1]. Такая конструкция позволяет проводить постепенную проверку целостности крупных запросов и полезна для возобновления частичных загрузок.

Замечание

Сегменты нумеруются, начиная с .1 Максимальное количество сегментов — 65535.

Пустые сегменты

Обратите внимание, что сегменты могут иметь пустое segment-data поле. Посмотрите пример пустого blob, который имеет один пустой сегмент. Пустые сегменты должны иметь segment-data-length , 0 и если include-crc64 включено, должны включать допустимую контрольную сумму.

Размер сегмента

При запросе GetBlob или ReadFile с x-ms-structured-body соответствующим набором в HTTP-запросе сервис разбивает blob или данные файла на сегменты по 4 МиБ в закодированном ответе. Если сообщение превысит максимальное количество сегментов, размер сегмента увеличивается.

Для загруженных blob или файловых данных от клиента сервис принимает сегменты любого размера или разного размера. Рекомендуется использовать сегменты размером 4 МиБ или больше. SDK по умолчанию используют размеры сегментов 4MiB.

Валидация содержимого CRC64

Проверка содержимого CRC64 — это функция в API Azure Storage REST, которая позволяет проверять контрольную сумму для поддерживаемых API. Существует множество вариантов алгоритмов CRC64. Контрольные суммы CRC64 рассчитываются с помощью CRC64-NVME (также известного как CRC64-Rocksoft). Функция использует пользовательский многочлен CRC64 для проверки целостности передаваемого контента. Существует две формы, в которых эта контрольная сумма может использоваться:

• Структурированное тело: контрольные суммы CRC64 встроены в тело запроса API, что позволяет проверять контрольные суммы по мере потоковой передачи данных.
• Транзакционные контрольные суммы CRC64 (поддерживаются только при загрузке): для каждого отдельного запроса API клиент вычисляет контрольную сумму CRC64 и устанавливает значение в заголовке, x-ms-content-crc64. Сервис хранения проверяет, что контрольная сумма полученных байт совпадает с контрольной суммой, указанной в заголовке.

Полином

Этот вариант CRC64 отражается по битам (на основе небитового отражённого полиномиального 0xad93d23594c93659) и инвертует входные и выходные биты CRC.

Примеры

Пример — пустое закодированное сообщение

В этом примере показано сообщение, закодированное в формате структурированного тела без данных. Обратите внимание, что сообщение должно содержать пустой сегмент.

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

Пример — пустое закодированное сообщение без crc64

В этом примере показано закодированное сообщение без данных и без включенной include-crc64 опции.

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

Пример — закодированное сообщение с двумя сегментами и контрольной суммой 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