本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 EBS 直接 APIs 寫入 Amazon EBS 快照
下列步驟說明如何使用 EBS 直接 API 寫入增量快照：
1. 使用 StartSnapShot 動作並指定父系快照 ID，將快照啟動為現有快照的增量快照，或省略父系快照 ID 以啟動新快照。此動作會傳回新的快照 ID，此 ID 處於待定狀態。
1. 使用 PutSnapshotBlock 動作，並指定待定快照的 ID，以個別區塊的形式新增資料。您必須為傳輸的資料區塊指定 Base64 編碼的 SHA256 檢查總和。服務會運算所接收資料的檢查總和，並使用您指定的檢查總和進行驗證。如果檢查總和不相符，該動作就會失敗。
1. 當您完成將資料新增至待定的快照時，請使用 CompleteSnapshot 動作來啟動密封快照的非同步工作流程，並將其移至完成狀態。
重複這些步驟，以使用先前建立的快照做為父系快照來建立新的增量快照。
例如，在下圖中，快照 A 是第一個啟動的新快照。系統將快照 A 作為啟動快照 B 的父系快照。將快照 B 作為啟動和建立快照的父系快照 C。快照 A、B 和 C 是增量快照。快照 A 用於建立 EBS 磁碟區 1。快照 D 是從 EBS 磁碟區 1 建立的快照。快照 D 是 A 的增量快照；它不是 B 或 C 的增量快照。
下列範例示範如何使用 EBS 直接 API 寫入快照。
**Topics**
+ [啟動快照](#start-snapshot)
+ [將資料放入快照中](#put-data)
+ [完成快照](#complete-snapshot)
## 啟動快照
------
#### [ AWS CLI ]
下列 [start-snapshot](https://docs.aws.amazon.com/cli/latest/reference/ebs/start-snapshot.html) 範例命令會啟動 `8` GiB 快照，並使用快照 `snap-123EXAMPLE1234567` 做為父系快照。新快照將是父系快照的增量快照。如果在指定的 `60` 分鐘逾時期間內沒有對快照提出放置或完成請求，則快照會移至錯誤狀態。`550e8400-e29b-41d4-a716-446655440000` 用戶端字符會確保請求的冪等性。如果省略用戶端字符，軟體 AWS 開發套件會自動為您產生一個字符。如需取得冪等性的詳細資訊，請參閱 [確保 StartSnapshot API 請求中的冪等性](ebs-direct-api-idempotency.md)。
```
aws ebs start-snapshot --volume-size {{8}} --parent-snapshot {{snap-123EXAMPLE1234567}} --timeout {{60}} --client-token {{550e8400-e29b-41d4-a716-446655440000}}
```
下列針對先前命令的回應範例顯示快照 ID、 AWS 帳戶 ID、狀態、以 GiB 為單位的磁碟區大小，以及快照中區塊的大小。快照會以 `pending` 狀態啟動。在後續 `put-snapshot-block` 命令中指定快照 ID，將資料寫入快照，然後使用 `complete-snapshot` 命令完成快照並將其狀態變更為 `completed`。
```
{
"SnapshotId": "snap-0aaEXAMPLEe306d62",
"OwnerId": "111122223333",
"Status": "pending",
"VolumeSize": 8,
"BlockSize": 524288
}
```
------
#### [ AWS API ]
下列 [StartSnapShot](https://docs.aws.amazon.com/ebs/latest/APIReference/API_StartSnapshot.html) 範例請求會使用快照 `8` 做為父系快照來啟動 `snap-123EXAMPLE1234567` GiB 快照。新快照將是父系快照的增量快照。如果在指定的 `60` 分鐘逾時期間內沒有對快照提出放置或完成請求，則快照會移至錯誤狀態。`550e8400-e29b-41d4-a716-446655440000` 用戶端字符會確保請求的冪等性。如果省略用戶端字符，軟體 AWS 開發套件會自動為您產生一個字符。如需取得冪等性的詳細資訊，請參閱 [確保 StartSnapshot API 請求中的冪等性](ebs-direct-api-idempotency.md)。
```
POST /snapshots HTTP/1.1
Host: ebs.us-east-2.amazonaws.com
Accept-Encoding: identity
User-Agent: {{}}
X-Amz-Date: 20200618T040724Z
Authorization: {{}}
{
"VolumeSize": {{8}},
"ParentSnapshot": {{snap-123EXAMPLE1234567}},
"ClientToken": "{{550e8400-e29b-41d4-a716-446655440000}}",
"Timeout": {{60}}
}
```
以下針對先前請求的範例回應顯示快照 ID、 AWS 帳戶 ID、狀態、以 GiB 為單位的磁碟區大小，以及快照中的區塊大小。快照會以待定狀態啟動。在後續 `PutSnapshotBlocks` 請求中指定快照 ID，以便將資料寫入快照。
```
HTTP/1.1 201 Created
x-amzn-RequestId: 929e6eb9-7183-405a-9502-5b7da37c1b18
Content-Type: application/json
Content-Length: 181
Date: Thu, 18 Jun 2020 04:07:29 GMT
Connection: keep-alive
{
"BlockSize": 524288,
"Description": null,
"OwnerId": "138695307491",
"Progress": null,
"SnapshotId": "snap-052EXAMPLEc85d8dd",
"StartTime": null,
"Status": "pending",
"Tags": null,
"VolumeSize": 8
}
```
------
## 將資料放入快照中
------
#### [ AWS CLI ]
下列 [put-snapshot-block](https://docs.aws.amazon.com/cli/latest/reference/ebs/put-snapshot-block.html) 範例命令會寫入資料`524288`位元組，以封鎖快照 `1000`上的索引`snap-0aaEXAMPLEe306d62`。Base64 編碼的 `QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM=` 檢查總和是使用 `SHA256` 演算法產生的。傳輸的資料位於 `/tmp/data` 檔案中。
```
aws ebs put-snapshot-block --snapshot-id {{snap-0aaEXAMPLEe306d62}} --block-index {{1000}} --data-length {{524288}} --block-data {{/tmp/data}} --checksum {{QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM=}} --checksum-algorithm {{SHA256}}
```
前一個命令的下列範例回應會針對服務接收的資料，確認資料長度、檢查總和演算法。
```
{
"DataLength": "524288",
"Checksum": "QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM=",
"ChecksumAlgorithm": "SHA256"
}
```
------
#### [ AWS API ]
下面的 [putSnapShot](https://docs.aws.amazon.com/ebs/latest/APIReference/API_PutSnapshotBlock.html) 範例請求會寫入資料 `524288` 位元組來阻止快照 `1000` 上的索引 `snap-052EXAMPLEc85d8dd`。Base64 編碼的 `QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM=` 檢查總和是使用 `SHA256` 演算法產生的。該資料在請求的主體中傳輸，並在下面的例子中表示為 {{BlockData}} 。
```
PUT /snapshots/{{snap-052EXAMPLEc85d8dd}}/{{blocks}}/1000 HTTP/1.1
Host: ebs.us-east-2.amazonaws.com
Accept-Encoding: identity
x-amz-Data-Length: {{524288}}
x-amz-Checksum: {{QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM=}}
x-amz-Checksum-Algorithm: {{SHA256}}
User-Agent: {{}}
X-Amz-Date: 20200618T042215Z
X-Amz-Content-SHA256: UNSIGNED-PAYLOAD
Authorization: {{}}
{{BlockData}}
```
以下是先前請求的範例回應，可確認服務所接收之資料的資料長度、檢查總和以及檢查總和演算法。
```
HTTP/1.1 201 Created
x-amzn-RequestId: 643ac797-7e0c-4ad0-8417-97b77b43c57b
x-amz-Checksum: QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM=
x-amz-Checksum-Algorithm: SHA256
Content-Type: application/json
Content-Length: 2
Date: Thu, 18 Jun 2020 04:22:12 GMT
Connection: keep-alive
{}
```
------
## 完成快照
------
#### [ AWS CLI ]
下列 [complete-snapshot](https://docs.aws.amazon.com/cli/latest/reference/ebs/complete-snapshot.html) 範例命令會完成快照 `snap-0aaEXAMPLEe306d62`。該命令會指定 `5` 區塊已寫入快照。`6D3nmwi5f2F0wlh7xX8QprrJBFzDX8aacdOcA3KCM3c=` 檢查總和代表寫入快照的完整資料集的檢查總和。如需有關檢查總和的詳細資訊，請參閱本指南前述的 [使用 EBS 直接 APIs 檢查總和來驗證快照資料](ebsapis-using-checksums.md)。
```
aws ebs complete-snapshot --snapshot-id {{snap-0aaEXAMPLEe306d62}} --changed-blocks-count {{5}} --checksum {{6D3nmwi5f2F0wlh7xX8QprrJBFzDX8aacdOcA3KCM3c=}} --checksum-algorithm {{SHA256}} --checksum-aggregation-method {{LINEAR}}
```
以下是前一個命令的範例回應。
```
{
"Status": "pending"
}
```
------
#### [ AWS API ]
下列 [CompleteSnapshot](https://docs.aws.amazon.com/ebs/latest/APIReference/API_CompleteSnapshot.html) 範例請求會完成快照 `snap-052EXAMPLEc85d8dd`。該命令會指定 `5` 區塊已寫入快照。`6D3nmwi5f2F0wlh7xX8QprrJBFzDX8aacdOcA3KCM3c=` 檢查總和代表寫入快照的完整資料集的檢查總和。
```
POST /snapshots/completion/{{snap-052EXAMPLEc85d8dd}} HTTP/1.1
Host: ebs.us-east-2.amazonaws.com
Accept-Encoding: identity
x-amz-ChangedBlocksCount: 5
x-amz-Checksum: {{6D3nmwi5f2F0wlh7xX8QprrJBFzDX8aacdOcA3KCM3c=}}
x-amz-Checksum-Algorithm: {{SHA256}}
x-amz-Checksum-Aggregation-Method: {{LINEAR}}
User-Agent: {{}}
X-Amz-Date: 20200618T043158Z
Authorization: {{}}
```
以下是先前請求的範例回應。
```
HTTP/1.1 202 Accepted
x-amzn-RequestId: 06cba5b5-b731-49de-af40-80333ac3a117
Content-Type: application/json
Content-Length: 20
Date: Thu, 18 Jun 2020 04:31:50 GMT
Connection: keep-alive
{"Status":"pending"}
```
------