소개
이 문서는 Azure Storage Blob, File, DFS API에서 요청 콘텐츠에 대한 효율적인 체크섬 계산을 지원하기 위해 사용하는 구조화된 바디 형식을 설명합니다. 이는 데이터(예: 블롭이나 파일 내용)를 체크섬 기반으로 후행 체크섬으로 인코딩하는 맞춤형 이진 형식입니다. 요청 본체 자체가 이 형식에 인코딩된다는 점에 유의하세요.
이 문서는 주로 Azure Storage REST API를 직접 사용하는 고객을 대상으로 합니다. 지원되는 Azure Storage SDK를 사용하는 고객은 자동으로 이 형식으로 요청이 인코딩됩니다.
현재 Azure Storage는 이 형식의 v1만 지원하며, v1은 crc64 체크섬만 지원합니다. 구조화된 메시지 형식의 사용은 선택 사항입니다.
규격
Sections
인코딩된 메시지는 세 개의 섹션으로 구성됩니다.
| 섹션 | 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 |
세그먼트의 블롭/파일 데이터의 길이(바이트 단위). |
segment-data |
byte[dl] |
블롭/파일 데이터 바이트. |
segment-data-crc64[^1] |
byte[8] |
세그먼트의 datacrc64 체크섬을 계산했습니다. |
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 필드를 가질 수 있다는 점에 유의하세요. 빈 블롭 예시를 참고하라. 이 글자는 단일 빈 세그먼트를 가진다. 빈 세그먼트는 반드시 a segment-data-length0 의 a를 가져야 하며, 만약 활성화된 경우 include-crc64 , 유효한 체크섬을 포함해야 합니다.
구간 크기
GetBlob 또는 ReadFile 요청 x-ms-structured-body 에 적절한 설정이 설정된 경우, 서비스는 인코딩된 응답에서 블롭이나 파일 데이터를 4MiB 단위로 청크합니다. 메시지가 최대 세그먼트 수를 초과하면 세그먼트 크기가 증가합니다.
클라이언트에서 업로드된 블롭 또는 파일 데이터의 경우, 서비스는 크기에 상관없거나 다양한 크기의 세그먼트를 수용합니다. 권장되는 것은 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