結構化正文格式

簡介

本文件說明 Azure Storage Blob、File 及 DFS API 所使用的結構化正體格式，以支援對請求內容的有效校驗碼計算。這是一種自訂的二進位格式，以校驗和方式編碼資料（例如，blob 或檔案內容）並附有尾隨校驗和。請注意，這個格式中編碼的請求本體本身就是這樣。

本文件主要針對直接使用 Azure Storage REST API 的客戶。使用支援的 Azure Storage SDK 的客戶，其請求會自動以此格式編碼。

目前 Azure Storage 只支援此格式的 v1，而 v1 只支援 crc64 校驗和。結構化訊息格式的使用是可選的。

Specification

章節

編碼訊息包含三個區段。

章節	Description
Header	標頭包含結構版本（1）、訊息長度、選項及區段數。
單元	每個訊息包含一個或多個區段，每個區段包含區段 #、資料及可選的尾隨中繼資料。 v1 唯一支援的拖車是 crc64 校驗和。
拖車	每則訊息都有可選的尾隨元資料。 v1 唯一支援的拖車是 crc64 校驗和。

二進位格式，v1

結構化身體 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`要是。參見分段

`segment-num`	`uint16`	目前的單元 #。第一個段是 `1` 且必須隨著每個段遞增。
`segment-data-length (dl)`	`uint64`	區段的 blob/檔案資料長度，以位元組為單位。
`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。最大區段數為 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 多項式來驗證傳輸內容的完整性。此校驗碼可有兩種形式使用：

結構化正文：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

Last updated on 2026-01-22