本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# DynamoDB 資料表匯出輸出格式
DynamoDB 資料表匯出內容除了包含資料表資料的檔案之外，還包括資訊清單檔案。這些檔案全都儲存於您在[匯出請求](S3DataExport_Requesting.md)中指定的 Amazon S3 儲存貯體。以下各節說明每個輸出物件的格式和內容。
**Topics**
## 完整匯出輸出
### 資訊清單檔案
DynamoDB 會針對每次匯出請求，在指定的 S3 儲存貯體中建立資訊清單檔案及其檢查總和檔案。
```
export-prefix/AWSDynamoDB/ExportId/manifest-summary.json
export-prefix/AWSDynamoDB/ExportId/manifest-summary.checksum
export-prefix/AWSDynamoDB/ExportId/manifest-files.json
export-prefix/AWSDynamoDB/ExportId/manifest-files.checksum
```
在請求資料表匯出時，您可以選擇 **export-prefix**。其有助於您在目的地 S3 儲存貯體中整理檔案。**ExportId** 是由服務產生的唯一權杖，可確保匯出至相同 S3 儲存貯體和 `export-prefix` 的多筆資料不會相互覆寫。
此匯出功能會為每個分割區建立至少 1 個檔案。對於空白的分割區，您的匯出請求將會建立空白檔案。每個檔案的所有項目都來自該特定分割區的雜湊金鑰空間。
**注意**
DynamoDB 也會在資訊清單檔案所在的相同目錄中建立名為 `_started` 的空白檔案。此檔案驗證目的地儲存貯體可寫入並已開始進行匯出。您可以安全地刪除此檔案。
#### 摘要資訊清單
`manifest-summary.json` 檔案包含匯出任務的摘要資訊。這可讓您知道共用資料資料夾中的哪些資料檔案與此匯出相關聯。其格式如下：
```
{
"version": "2020-06-30",
"exportArn": "arn:aws:dynamodb:us-east-1:123456789012:table/ProductCatalog/export/01234567890123-a1b2c3d4",
"startTime": "2020-11-04T07:28:34.028Z",
"endTime": "2020-11-04T07:33:43.897Z",
"tableArn": "arn:aws:dynamodb:us-east-1:123456789012:table/ProductCatalog",
"tableId": "12345a12-abcd-123a-ab12-1234abc12345",
"exportTime": "2020-11-04T07:28:34.028Z",
"s3Bucket": "ddb-productcatalog-export",
"s3Prefix": "2020-Nov",
"s3SseAlgorithm": "AES256",
"s3SseKmsKeyId": null,
"manifestFilesS3Key": "AWSDynamoDB/01693685827463-2d8752fd/manifest-files.json",
"billedSizeBytes": 0,
"itemCount": 8,
"outputFormat": "DYNAMODB_JSON",
"exportType": "FULL_EXPORT"
}
```
#### 檔案資訊清單
`manifest-files.json` 檔案包含內含匯出資料表資料的檔案資訊。檔案採用 [JSON Lines](https://jsonlines.org/) 格式，因此新行將作為項目分隔符號使用。在下列範例中，為了便於閱讀，檔案資訊清單的資料檔案詳細資訊會採用多行格式。
```
{
"itemCount": 8,
"md5Checksum": "sQMSpEILNgoQmarvDFonGQ==",
"etag": "af83d6f217c19b8b0fff8023d8ca4716-1",
"dataFileS3Key": "AWSDynamoDB/01693685827463-2d8752fd/data/asdl123dasas.json.gz"
}
```
### 資料檔案
DynamoDB 會以兩種格式匯出資料表資料：DynamoDB JSON 和 Amazon Ion。無論選擇哪種格式，您的資料都會寫入多個以金鑰命名的壓縮檔案。這些檔案也會在 `manifest-files.json` 檔案中列出。
完整匯出後，Amazon S3 儲存貯體的目錄結構將包含匯出 ID 資料夾下的所有資訊清單檔案和資料檔案。
```
amzn-s3-demo-bucket/DestinationPrefix
.
└── AWSDynamoDB
├── 01693685827463-2d8752fd // the single full export
│ ├── manifest-files.json // manifest points to files under 'data' subfolder
│ ├── manifest-files.checksum
│ ├── manifest-summary.json // stores metadata about request
│ ├── manifest-summary.md5
│ ├── data // The data exported by full export
│ │ ├── asdl123dasas.json.gz
│ │ ...
│ └── _started // empty file for permission check
```
#### DynamoDB JSON
以 DynamoDB JSON 格式匯出的資料表由多個 `Item` 物件組成。每個個別物件均採用 DynamoDB 的標準封送處理 JSON 格式。
建立 DynamoDB JSON 匯出資料的自訂剖析器時，格式為 [JSON Lines](https://jsonlines.org/)。這表示將新行用作項目分隔符號。Athena 和 等許多 AWS 服務 AWS Glue會自動剖析此格式。
在下列範例中，為了便於閱讀，DynamoDB JSON 匯出資料的單一項目採用多行格式。
```
{
"Item":{
"Authors":{
"SS":[
"Author1",
"Author2"
]
},
"Dimensions":{
"S":"8.5 x 11.0 x 1.5"
},
"ISBN":{
"S":"333-3333333333"
},
"Id":{
"N":"103"
},
"InPublication":{
"BOOL":false
},
"PageCount":{
"N":"600"
},
"Price":{
"N":"2000"
},
"ProductCategory":{
"S":"Book"
},
"Title":{
"S":"Book 103 Title"
}
}
}
```
#### Amazon Ion
[Amazon Ion](http://amzn.github.io/ion-docs/) 是輸入豐富、自行描述、階層資料序列化格式，旨在處理快速開發、解耦及日常遇到的效率挑戰等問題，同時設計大規模的服務導向架構。DynamoDB 支援匯出 Ion [文字格式](http://amzn.github.io/ion-docs/docs/spec.html)的資料表資料，亦即 JSON 的超集。
將資料表匯出成 Ion 格式時，資料表中使用的 DynamoDB 資料類型會映射至 [Ion 資料類型](http://amzn.github.io/ion-docs/docs/spec.html)。DynamoDB 設定使用 [Ion 類型註釋](http://amzn.github.io/ion-docs/docs/spec.html#annot)，以釐清在來源資料表中使用的資料類型。
下表列出 DynamoDB 資料類型與離子資料類型的映射：
| DynamoDB 資料類型 | Ion 表示法 |
| --- | --- |
| String (S) | string |
| Boolean (BOOL) | bool |
| Number (N) | decimal |
| Binary (B) | blob |
| Set (SS、NS、BS) | list (包含類型註解 \$1dynamodb\$1SS、\$1dynamodb\$1NS 或 \$1dynamodb\$1BS) |
| 清單 | list |
| Map | struct |
Ion 匯出中的項目以新行分隔。每行都以 Ion 版本標記開頭，後面接著 Ion 格式的項目。在下列範例中，為了便於閱讀，Ion 匯出的項目採用多行格式。
```
$ion_1_0 {
Item:{
Authors:$dynamodb_SS::["Author1","Author2"],
Dimensions:"8.5 x 11.0 x 1.5",
ISBN:"333-3333333333",
Id:103.,
InPublication:false,
PageCount:6d2,
Price:2d3,
ProductCategory:"Book",
Title:"Book 103 Title"
}
}
```
## 增量匯出輸出
### 資訊清單檔案
DynamoDB 會針對每次匯出請求，在指定的 S3 儲存貯體中建立資訊清單檔案及其檢查總和檔案。
```
export-prefix/AWSDynamoDB/ExportId/manifest-summary.json
export-prefix/AWSDynamoDB/ExportId/manifest-summary.checksum
export-prefix/AWSDynamoDB/ExportId/manifest-files.json
export-prefix/AWSDynamoDB/ExportId/manifest-files.checksum
```
在請求資料表匯出時，您可以選擇 **export-prefix**。其有助於您在目的地 S3 儲存貯體中整理檔案。**ExportId** 是由服務產生的唯一權杖，可確保匯出至相同 S3 儲存貯體和 `export-prefix` 的多筆資料不會相互覆寫。
此匯出功能會為每個分割區建立至少 1 個檔案。對於空白的分割區，您的匯出請求將會建立空白檔案。每個檔案的所有項目都來自該特定分割區的雜湊金鑰空間。
**注意**
DynamoDB 也會在資訊清單檔案所在的相同目錄中建立名為 `_started` 的空白檔案。此檔案驗證目的地儲存貯體可寫入並已開始進行匯出。您可以安全地刪除此檔案。
#### 摘要資訊清單
`manifest-summary.json` 檔案包含匯出任務的摘要資訊。這可讓您知道共用資料資料夾中的哪些資料檔案與此匯出相關聯。其格式如下：
```
{
"version": "2023-08-01",
"exportArn": "arn:aws:dynamodb:us-east-1:599882009758:table/export-test/export/01695097218000-d6299cbd",
"startTime": "2023-09-19T04:20:18.000Z",
"endTime": "2023-09-19T04:40:24.780Z",
"tableArn": "arn:aws:dynamodb:us-east-1:599882009758:table/export-test",
"tableId": "b116b490-6460-4d4a-9a6b-5d360abf4fb3",
"exportFromTime": "2023-09-18T17:00:00.000Z",
"exportToTime": "2023-09-19T04:00:00.000Z",
"s3Bucket": "jason-exports",
"s3Prefix": "20230919-prefix",
"s3SseAlgorithm": "AES256",
"s3SseKmsKeyId": null,
"manifestFilesS3Key": "20230919-prefix/AWSDynamoDB/01693685934212-ac809da5/manifest-files.json",
"billedSizeBytes": 20901239349,
"itemCount": 169928274,
"outputFormat": "DYNAMODB_JSON",
"outputView": "NEW_AND_OLD_IMAGES",
"exportType": "INCREMENTAL_EXPORT"
}
```
#### 檔案資訊清單
`manifest-files.json` 檔案包含內含匯出資料表資料的檔案資訊。檔案採用 [JSON Lines](https://jsonlines.org/) 格式，因此新行將作為項目分隔符號使用。在下列範例中，為了便於閱讀，檔案資訊清單的資料檔案詳細資訊會採用多行格式。
```
{
"itemCount": 8,
"md5Checksum": "sQMSpEILNgoQmarvDFonGQ==",
"etag": "af83d6f217c19b8b0fff8023d8ca4716-1",
"dataFileS3Key": "AWSDynamoDB/data/sgad6417s6vss4p7owp0471bcq.json.gz"
}
```
### 資料檔案
DynamoDB 會以兩種格式匯出資料表資料：DynamoDB JSON 和 Amazon Ion。無論選擇哪種格式，您的資料都會寫入多個以金鑰命名的壓縮檔案。這些檔案也會在 `manifest-files.json` 檔案中列出。
增量匯出的資料檔案全部包含在 S3 儲存貯體的常用資料資料夾中。您的資訊清單檔案會在匯出 ID 資料夾下。
```
amzn-s3-demo-bucket/DestinationPrefix
.
└── AWSDynamoDB
├── 01693685934212-ac809da5 // an incremental export ID
│ ├── manifest-files.json // manifest points to files under 'data' folder
│ ├── manifest-files.checksum
│ ├── manifest-summary.json // stores metadata about request
│ ├── manifest-summary.md5
│ └── _started // empty file for permission check
├── 01693686034521-ac809da5
│ ├── manifest-files.json
│ ├── manifest-files.checksum
│ ├── manifest-summary.json
│ ├── manifest-summary.md5
│ └── _started
├── data // stores all the data files for incremental exports
│ ├── sgad6417s6vss4p7owp0471bcq.json.gz
│ ...
```
在匯出檔案中，每個項目的輸出都包含時間戳記，代表該項目在您的資料表中更新的時間，還有指出該項目是 `insert`、`update` 或 `delete` 操作的資料結構。時間戳記是以內部系統時鐘為基礎，且可能因應用程式時脈而有所不同。對於增量匯出，您可以為輸出結構選擇兩種匯出檢視類型：**新舊映像**或**僅限新映像**。
+ **新映像**提供項目的最新狀態
+ **舊映像**提供項目在指定的**開始日期和時間**之前的狀態
如果您想要查看項目在匯出期間內的變更情形，檢視類型會很有幫助。它對於有效率地更新下游系統來說也很實用，特別是在這些下游系統的分割區索引鍵與 DynamoDB 分割區索引鍵不同的情況下。
您可以藉由查看輸出的結構，推斷增量匯出輸出中的項目是 `insert`、`update` 或 `delete`。下表針對兩種匯出檢視類型摘要說明增量匯出結構及其對應操作。
| 作業 | 僅限新映像 | 新舊映像 |
| --- | --- | --- |
| Insert | 按鍵 \$1 新映像 | 按鍵 \$1 新映像 |
| 更新 | 按鍵 \$1 新映像 | 鍵 \$1 新映像 \$1 舊映像 |
| 刪除 | 金鑰 | 按鍵 \$1 舊映像 |
| Insert \$1 delete | 無輸出 | 無輸出 |
#### DynamoDB JSON
DynamoDB JSON 格式的資料表匯出包含中繼資料時間戳記，該時間戳記指出項目的寫入時間，後面接著項目的索引鍵和值。以下顯示使用**新舊映像**作為匯出檢視類型的 DynamoDB JSON 輸出範例。
```
// Ex 1: Insert
// An insert means the item did not exist before the incremental export window
// and was added during the incremental export window
{
"Metadata": {
"WriteTimestampMicros": "1680109764000000"
},
"Keys": {
"PK": {
"S": "CUST#100"
}
},
"NewImage": {
"PK": {
"S": "CUST#100"
},
"FirstName": {
"S": "John"
},
"LastName": {
"S": "Don"
}
}
}
// Ex 2: Update
// An update means the item existed before the incremental export window
// and was updated during the incremental export window.
// The OldImage would not be present if choosing "New images only".
{
"Metadata": {
"WriteTimestampMicros": "1680109764000000"
},
"Keys": {
"PK": {
"S": "CUST#200"
}
},
"OldImage": {
"PK": {
"S": "CUST#200"
},
"FirstName": {
"S": "Mary"
},
"LastName": {
"S": "Grace"
}
},
"NewImage": {
"PK": {
"S": "CUST#200"
},
"FirstName": {
"S": "Mary"
},
"LastName": {
"S": "Smith"
}
}
}
// Ex 3: Delete
// A delete means the item existed before the incremental export window
// and was deleted during the incremental export window
// The OldImage would not be present if choosing "New images only".
{
"Metadata": {
"WriteTimestampMicros": "1680109764000000"
},
"Keys": {
"PK": {
"S": "CUST#300"
}
},
"OldImage": {
"PK": {
"S": "CUST#300"
},
"FirstName": {
"S": "Jose"
},
"LastName": {
"S": "Hernandez"
}
}
}
// Ex 4: Insert + Delete
// Nothing is exported if an item is inserted and deleted within the
// incremental export window.
```
#### Amazon Ion
[Amazon Ion](http://amzn.github.io/ion-docs/) 是輸入豐富、自行描述、階層資料序列化格式，旨在處理快速開發、解耦及日常遇到的效率挑戰等問題，同時設計大規模的服務導向架構。DynamoDB 支援匯出 Ion [文字格式](http://amzn.github.io/ion-docs/docs/spec.html)的資料表資料，亦即 JSON 的超集。
將資料表匯出成 Ion 格式時，資料表中使用的 DynamoDB 資料類型會映射至 [Ion 資料類型](http://amzn.github.io/ion-docs/docs/spec.html)。DynamoDB 設定使用 [Ion 類型註釋](http://amzn.github.io/ion-docs/docs/spec.html#annot)，以釐清在來源資料表中使用的資料類型。
下表列出 DynamoDB 資料類型與離子資料類型的映射：
| DynamoDB 資料類型 | Ion 表示法 |
| --- | --- |
| String (S) | string |
| Boolean (BOOL) | bool |
| Number (N) | decimal |
| Binary (B) | blob |
| Set (SS、NS、BS) | list (包含類型註解 \$1dynamodb\$1SS、\$1dynamodb\$1NS 或 \$1dynamodb\$1BS) |
| 清單 | list |
| Map | struct |
Ion 匯出中的項目以新行分隔。每行都以 Ion 版本標記開頭，後面接著 Ion 格式的項目。在下列範例中，為了便於閱讀，Ion 匯出的項目採用多行格式。
```
$ion_1_0 {
Record:{
Keys:{
ISBN:"333-3333333333"
},
Metadata:{
WriteTimestampMicros:1684374845117899.
},
OldImage:{
Authors:$dynamodb_SS::["Author1","Author2"],
ISBN:"333-3333333333",
Id:103.,
InPublication:false,
ProductCategory:"Book",
Title:"Book 103 Title"
},
NewImage:{
Authors:$dynamodb_SS::["Author1","Author2"],
Dimensions:"8.5 x 11.0 x 1.5",
ISBN:"333-3333333333",
Id:103.,
InPublication:true,
PageCount:6d2,
Price:2d3,
ProductCategory:"Book",
Title:"Book 103 Title"
}
}
}
```