Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Pendahuluan
Dokumen ini menjelaskan format Isi Terstruktur yang digunakan oleh API Azure Storage Blob, File, dan DFS untuk mendukung perhitungan checksum yang efisien atas konten permintaan. Ini adalah format biner kustom yang mengkodekan data (misalnya, blob atau konten file) dengan checksum trailing berdasarkan checksum. Perhatikan bahwa isi permintaan itu sendiri adalah apa yang dikodekan ke dalam format ini.
Dokumentasi ini terutama ditargetkan pada pelanggan yang menggunakan Azure Storage REST API secara langsung. Pelanggan yang menggunakan Azure Storage SDK yang didukung akan secara otomatis meminta mereka dikodekan dalam format ini.
Saat ini, Azure Storage hanya mendukung v1 dari format ini, yang hanya mendukung checksum crc64. Penggunaan format pesan terstruktur bersifat opsional.
Specification
Bagian-bagian
Pesan yang dikodekan memiliki tiga bagian.
| Section | Description |
|---|---|
| Header | Header berisi versi skema (1), panjang pesan, opsi, dan jumlah segmen. |
| Segmen | Setiap pesan memiliki satu atau beberapa segmen, dan setiap segmen berisi segmen #, data, dan metadata akhir opsional. Untuk v1, satu-satunya trailer yang didukung adalah checksum crc64. |
| Cuplikan | Setiap pesan memiliki metadata trailing opsional. Untuk v1, satu-satunya trailer yang didukung adalah checksum crc64. |
Format Biner, v1
Format biner Structured Body v1 didefinisikan sebagai:
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
Semua tipe data bilangan bulat dikodekan sebagai little-endian.
Referensi Bidang
| Bidang | Tipe | Description |
|---|---|---|
message-version |
uint8 |
Versi skema pesan. Ini harus 1. |
message-length |
uint64 |
Panjang pesan lengkap. Dalam pesan HTTP, ini harus cocok dengan Content-Length header. |
message-flags |
uint16 |
Bendera (opsi) diaktifkan untuk pesan ini. Versi 1 hanya mendukung satu bendera untuk crc64 checksum. Lihat Bendera. |
num-segments |
uint16 |
Jumlah segmen yang terkandung dalam pesan. Ini harus setidaknya 1. Lihat Segmen |
segment-num |
uint16 |
Segmen saat ini #. Segmen pertama adalah 1 dan harus bertambah untuk setiap segmen berikutnya. |
segment-data-length (dl) |
uint64 |
Panjang data blob/file segmen, dalam byte. |
segment-data |
byte[dl] |
Byte data blob/file. |
segment-data-crc64[^ 1] |
byte[8] |
Checksum crc64 yang dihitung untuk segmen data. |
message-data-crc64[^ 1] |
byte[8] |
Checksum crc64 yang dihitung untuk data pesan (semua segmen' data.) |
[^1]: Checksum CRC64 hadir saat include-crc64 opsi ditentukan. Lihat Bendera.
Flags
Bidang ini message-flags digunakan untuk menentukan opsi untuk pesan yang dikodekan. Versi 1 hanya mendukung satu opsi, include-crc64, tetapi bit yang tersisa dicadangkan untuk opsi mendatang seperti algoritme checksum lainnya dan metadata lainnya.
| Nilai | Nama | Description |
|---|---|---|
0x0001 |
include-crc64 |
Sertakan checksum crc64 dalam segmen dan cuplikan pesan. |
0x0002-0x8000 |
Dicadangkan untuk versi mendatang. |
Segmen
Pesan yang dikodekan dibagi menjadi satu atau beberapa segmen. Setiap segmen berisi segmen #, data segmen, dan checksum[^1]. Desain ini memungkinkan verifikasi integritas inkremental untuk permintaan besar, dan berguna untuk melanjutkan unduhan parsial.
Nota
Segmen diberi nomor dimulai dengan 1. Jumlah maksimum segmen adalah 65535.
Segmen Kosong
Perhatikan bahwa segmen dapat memiliki bidang kosong segment-data . Lihat contoh blob kosong, yang memiliki segmen kosong tunggal. Segmen kosong harus memiliki of segment-data-length0 dan jika include-crc64 diaktifkan, harus menyertakan checksum yang valid.
Ukuran Segmen
Pada permintaan GetBlob atau ReadFile dengan x-ms-structured-body set yang sesuai dalam permintaan HTTP, layanan akan memotong blob atau data file menjadi segmen 4MiB dalam respons yang dikodekan. Jika pesan akan melebihi jumlah maksimum segmen, ukuran segmen akan ditingkatkan.
Untuk data blob atau file yang diunggah dari klien, layanan akan menerima segmen dengan ukuran apa pun atau berbagai ukuran. Rekomendasinya adalah menggunakan ukuran segmen 4MiB atau lebih besar. SDK menggunakan ukuran segmen 4MiB secara default.
Validasi konten CRC64
Validasi konten CRC64 adalah fitur di Azure Storage REST API yang memungkinkan validasi checksum untuk API yang didukung. Ada banyak varian algoritma CRC64. Checksum CRC64 dihitung menggunakan CRC64-NVME (alias CRC64-Rocksoft). Fitur ini menggunakan polinomial CRC64 kustom untuk memvalidasi integritas konten yang ditransfer. Ada dua bentuk di mana checksum ini dapat digunakan:
- Isi terstruktur: Checksum CRC64 disematkan ke dalam isi permintaan API, yang memungkinkan checksum divalidasi saat data dialirkan.
- Checksum CRC64 transaksional (hanya didukung dalam upload): Untuk setiap permintaan API individual, klien menghitung checksum CRC64 dan mengatur nilai ke header,
x-ms-content-crc64. Layanan Storage memvalidasi bahwa checksum byte yang diterima cocok dengan checksum yang disediakan di header.
Polinomial
Varian CRC64 ini dipantulkan bit (berdasarkan 0xad93d23594c93659 polinomial yang tidak dipantulkan bit) dan membalikkan bit input dan output CRC.
Examples
Contoh - Pesan Kosong yang Dikodekan
Contoh ini menunjukkan pesan yang dikodekan dengan format isi terstruktur tanpa data. Perhatikan bahwa pesan harus berisi segmen kosong.
// 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
Contoh - Pesan Kosong yang Dikodekan tanpa crc64
Contoh ini menunjukkan pesan yang dikodekan tanpa data dan tanpa opsi diaktifkan 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
Contoh - Pesan yang Dikodekan dengan Dua Segmen dan 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