構造化ボディフォーマット

イントロダクション

本ドキュメントは、Azure Storage Blob、File、DFS APIで使用される構造化ボディ形式を説明し、リクエスト内容に対する効率的なチェックサム計算をサポートします。これはカスタムバイナリ形式で、データ(例 :ブロブやファイル内容)をチェックサムベースで後続のチェックサムでエンコードします。この形式にエンコードされているのはリクエストボディ自体であることに注意してください。

このドキュメントは主にAzure Storage REST APIを直接利用する顧客を対象としています。サポートされているAzure Storage SDKを使用している顧客は、自動的にリクエストがこの形式でエンコードされます。

現在、Azure Storageはこのフォーマットのv1のみをサポートしており、v1はcrc64チェックサムのみをサポートしています。構造化メッセージ形式の使用は任意です。

仕様

セクション

エンコードされたメッセージは3つのセクションから成り立っています。

セクション	Description
Header	ヘッダーにはスキーマバージョン(1)、メッセージ長、オプション、セグメント数が含まれます。
セグメント	各メッセージは1つ以上のセグメントを持ち、各セグメントにはセグメント#、データ、およびオプションのトレーリングメタデータが含まれています。 v1でサポートされているトレーラーはCRC64のチェックサムだけです。
トレーラー	各メッセージにはオプションのトレーリングメタデータがあります。 v1でサポートされているトレーラーは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

すべての整数データ型はリトルエンドアンとしてエンコードされます。

フィールドリファレンス

フィールド	タイプ	Description
`message-version`	`uint8`	メッセージのスキーマ版です。これが`1`でなければなりません。
`message-length`	`uint64`	全文メッセージの長さ。 HTTPメッセージでは、これは `Content-Length` ヘッダーと一致しなければなりません。
`message-flags`	`uint16`	このメッセージにはフラグ(オプション)が有効になっています。バージョン `1` では、 `crc64` チェックサムに対して単一のフラグのみをサポートしています。「旗」を参照してください。
`num-segments`	`uint16`	メッセージに含まれるセグメントの数。これは少なくとも1 `1`に違いない。セグメントを参照

`segment-num`	`uint16`	現在のセグメント#。最初のセグメントは `1` であり、次のセグメントごとに増量しなければなりません。
`segment-data-length (dl)`	`uint64`	セグメントのブロブ/ファイルデータの長さ(バイト単位)。
`segment-data`	`byte[dl]`	Blob/ファイルデータバイトです。
`segment-data-crc64`[^1]	`byte[8]`	セグメントの `data`に対してcrc64チェックサムを計算しました。

`message-data-crc64`[^1]	`byte[8]`	メッセージデータ(すべてのセグメントの `data`)に対してcrc64チェックサムを計算しました。

[^1]: include-crc64 オプションが指定されるとCRC64チェックサムが存在します。「旗」を参照してください。

Flags

message-flagsフィールドは符号化されたメッセージのオプションを指定するために使用されます。バージョン1は include-crc64の単一のオプションのみをサポートしていますが、残りのビットは他のチェックサムアルゴリズムやその他のメタデータなど将来のオプションのために予約されています。

価値	名前	Description
`0x0001`	`include-crc64`	crc64のチェックサムをセグメントやメッセージトレーラーに含めてください。
`0x0002-0x8000`		将来のバージョン用に予約しています。

セグメント

符号化されたメッセージは1つ以上のセグメントに分割されます。各セグメントにはセグメント#、セグメントデータ、チェックサム[^1]が含まれています。この設計により、大規模なリクエストに対する漸量的整合性検証が可能であり、部分的なダウンロードの再開にも有用です。

注

区間は 1から始まる番号が付けられています。最大セグメント数は 65535です。

空のセグメント

セグメントは空の segment-data フィールドを持つことがあります。例の空の塊は、単一の空のセグメントを持つ。空のセグメントは segment-data-length が 0 でなければならず、 include-crc64 有効であれば有効なチェックサムを含める必要があります。

セグメントサイズ

GetBlobやReadFileリクエストに対して、HTTPリクエストに適切なセットが x-ms-structured-body ついた場合、サービスはBlobやファイルデータをエンコードされたレスポンスで4MiBセグメントにチャンクします。メッセージが最大セグメント数を超える場合は、セグメントサイズが増加します。

クライアントからアップロードされたblobやファイルデータの場合、サービスは任意のサイズまたはさまざまなサイズのセグメントを受け入れます。推奨されているのは、4MiB以上のセグメントサイズを使用することです。 SDKはデフォルトで4MiBセグメントサイズを使用しています。

CRC64コンテンツ検証

CRC64コンテンツ検証は、Azure Storage REST APIの機能で、サポートAPIのチェックサム検証を可能にします。 CRC64アルゴリズムには多くのバリエーションがあります。 CRC64のチェックサムは CRC64-NVME(別名 CRC64-Rocksoft)を用いて計算されます。この機能は、転送されたコンテンツの整合性を検証するためにカスタムCRC64多項式を使用します。このチェックサムは2つの形態で利用可能です。

構造化ボディ: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

例 - 2セグメントと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 2026-01-22