本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# DynamoDB 資料匯出至 Amazon S3：運作方式
<a name="S3DataExport.HowItWorks"></a>

DynamoDB 匯出至 S3 是一種全受管解決方案，可將 DynamoDB 資料大規模匯出至 Amazon S3 儲存貯體。您可以使用 DynamoDB 匯出至 S3，將資料從[時間點復原 (PITR)](Point-in-time-recovery.md) 時段內任何時間點的 Amazon DynamoDB 資料表，匯出至 Amazon S3 儲存貯體。您需在資料表上啟用 PITR，才能使用匯出功能。此功能可讓您使用 Athena、Amazon SageMaker AI AWS Glue、Amazon EMR 和 等 AWS 其他服務，對資料執行分析和複雜查詢 AWS Lake Formation。

DynamoDB 匯出至 S3 可讓您從 DynamoDB 資料表匯出完整資料和增量資料。匯出是非同步的，而且不會使用任何[讀取容量單位 (RCU)](provisioned-capacity-mode.md)，也不會影響資料表效能和可用性。支援的匯出檔案格式為 DynamoDB JSON 和 Amazon Ion 格式。您也可以將資料匯出至另一個 AWS 帳戶擁有的 S3 儲存貯體，以及匯出至不同的 AWS 區域。您的資料一律會進行端對端加密。

DynamoDB 完整匯出的費用是根據匯出完成之時間點的 DynamoDB 資料表大小 (資料表資料和本機次要索引) 來計費。DynamoDB 增量匯出的費用是根據匯出期間內從連續備份處理的資料大小來計費。增量匯出的最低費用為 10 MB。其他費用包括將匯出的資料儲存在 Amazon S3 中，以及對 Amazon S3 儲存貯體發出的 `PUT` 請求。如需這些費用的詳細資訊，請參閱 [Amazon DynamoDB 定價](https://aws.amazon.com/dynamodb/pricing/)和 [Amazon S3 定價](https://aws.amazon.com/s3/pricing/)。

如需 Service Quotas 的詳細資訊，請參閱 [資料表匯出至 Amazon S3](ServiceQuotas.md#limits-table-export)。

**Topics**
+ [請求在 DynamoDB 中匯出資料表](S3DataExport_Requesting.md)
+ [DynamoDB 資料表匯出輸出格式](S3DataExport.Output.md)

# 請求在 DynamoDB 中匯出資料表
<a name="S3DataExport_Requesting"></a>

DynamoDB 資料表匯出可讓您將資料表資料匯出至 Amazon S3 儲存貯體，讓您使用 Athena、 AWS Glue、Amazon SageMaker AI、Amazon EMR 和 等 AWS 其他服務，對資料執行分析和複雜的查詢 AWS Lake Formation。您可以使用 AWS 管理主控台、 AWS CLI或 DynamoDB API 請求資料表匯出。

**注意**  
不支援申請者支付 Amazon S3 儲存貯體。

DynamoDB 同時支援完整匯出和增量匯出：
+ 使用**完整匯出**時，您可以從時間點復原 (PITR) 時段內任何時間點，將資料表的完整快照匯出至 Amazon S3 儲存貯體。
+ 使用**增量匯出**時，您可以將 PITR 時段中指定期間內變更、更新或刪除的 DynamoDB 資料表中的資料匯出至 Amazon S3 儲存貯體。

**Topics**
+ [先決條件](#S3DataExport_Requesting_Permissions)
+ [使用 請求匯出 AWS 管理主控台](#S3DataExport_Requesting_Console)
+ [取得 中過去匯出的詳細資訊 AWS 管理主控台](#S3DataExport_Requesting_Console_Details)
+ [使用 AWS CLI 和 AWS SDKs 請求匯出](#S3DataExport_Requesting_CLI)
+ [使用 AWS CLI 和 AWS SDKs 取得過去匯出的詳細資訊](#S3DataExport_Requesting_CLI_Details)

## 先決條件
<a name="S3DataExport_Requesting_Permissions"></a>

**啟用 PITR**

若要使用匯出至 S3 功能，您將需要在資料表上啟用 PITR。如需如何啟用 PITR 的詳細資訊，請參閱[時間點復原](PointInTimeRecovery_Howitworks.md)。如果您請求匯出未啟用 PITR 的資料表，您的請求將會失敗，並顯示例外狀況訊息：「呼叫 `ExportTableToPointInTime` 操作時發生錯誤 (PointInTimeRecoveryUnavailableException)：資料表 'my-dynamodb-table' 未啟用時間點復原」。您只能從設定 PITR `RecoveryPeriodInDays` 內的時間點請求和匯出。

**設定 S3 許可**

您可以將資料表資料匯出至您擁有寫入許可的任何 Amazon S3 儲存貯體。目的地儲存貯體不需要與來源資料表擁有者位於相同 AWS 區域或擁有相同的擁有者。您的 AWS Identity and Access Management (IAM) 政策需要允許您執行 S3 動作 (`s3:AbortMultipartUpload`、 `s3:PutObject`和 `s3:PutObjectAcl`) 和 DynamoDB 匯出動作 (`dynamodb:ExportTableToPointInTime`)。以下範例政策將授予您的使用者執行匯出至 S3 儲存貯體的許可。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowDynamoDBExportAction",
            "Effect": "Allow",
            "Action": "dynamodb:ExportTableToPointInTime",
            "Resource": "arn:aws:dynamodb:us-east-1:111122223333:table/my-table"
        },
        {
            "Sid": "AllowS3BucketWrites",
            "Effect": "Allow",
            "Action": [
                "s3:AbortMultipartUpload",
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
        }
    ]
}
```

------

如果您需要寫入另一個帳戶中的 S3 儲存貯體，或者您沒有寫入其中的許可，則 S3 儲存貯體擁有者將需要新增儲存貯體政策，以允許您從 DynamoDB 匯出至該儲存貯體。以下是目標 S3 儲存貯體的範例政策。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "ExampleStatement",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:user/Dave"
            },
            "Action": [
                "s3:AbortMultipartUpload",
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
        }
    ]
}
```

------

在匯出過程中撤銷這些許可會產生部分檔案。

**注意**  
如果您要匯出的目標資料表或儲存貯體使用客戶自管金鑰加密，該 KMS 金鑰的政策必須允許 DynamoDB 使用該金鑰。此許可是透過觸發匯出任務的 IAM 使用者/角色授予。如需有關加密及其最佳實務的詳細資訊，請參閱 [DynamoDB 如何使用 AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/services-dynamodb.html) 以及[使用自訂 KMS 金鑰](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-key-customer-managed)。

## 使用 請求匯出 AWS 管理主控台
<a name="S3DataExport_Requesting_Console"></a>

以下範例示範如何使用 DynamoDB 主控台匯出名為 `MusicCollection` 的現有資料表。

**注意**  
此程序假設您已經啟用時間點復原。若要為 `MusicCollection` 資料表啟用該功能，進入資料表 **Overview** (概觀) 索引標籤的 **Table details** (資料表詳細資訊) 部分，然後為 **Point-in-time recovery** (時間點復原) 選擇 **Enable** (啟用)。

**請求資料表匯出**

1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) 開啟 DynamoDB 主控台。

1. 在主控台左側的導覽窗格中，選擇 **Exports to S3** (匯出至 S3)。

1. 選取**匯出至 S3** 按鈕。

1. 選擇來源資料表和目的地 S3 儲存貯體。如果您的帳戶擁有該目的地儲存貯體，您可以使用 **Browse S3** (瀏覽 S3) 按鈕尋找它。如果不是，請使用 `s3://bucketname/prefix format.` 輸入儲存貯體的 URL；**prefix** 是有助於您整理目的地儲存貯體的選用資料夾。

1. 選擇**完整匯出**或**增量匯出**。**完整匯出**會輸出資料表在您所指定時間點的完整資料表快照。**增量匯出**會輸出在指定匯出期間對資料表所做的變更。您的輸出會經過壓縮，因此只會包含匯出期間內項目的最終狀態。即使項目在同一匯出期間內有多個更新，該項目也只會在匯出中出現一次。

------
#### [ Full export ]

   1. 選取您要匯出完整資料表快照的來源時間點。這個時間點可以是 PITR 時段內的任何時間點。或者，您可以選取**目前時間**以匯出最新快照。

   1. 對於**匯出的檔案格式**，請選擇 **DynamoDB JSON** 和 **Amazon Ion** 兩者之一。根據預設，您的資料表會以 DynamoDB JSON 格式在時間點復原時段中的最近可還原時間匯出，並使用 Amazon S3 金鑰 (SSE-S3) 進行加密。您可以視需要變更這些匯出設定。
**注意**  
如果您選擇使用受 AWS Key Management Service (AWS KMS) 保護的金鑰來加密匯出，則金鑰必須位於與目的地 S3 儲存貯體相同的區域。

------
#### [ Incremental export ]

   1. 選取您要匯出增量資料的**匯出期間**。選擇在 PITR 時段內的開始時間。匯出期間必須至少為 15 分鐘，且不超過 24 小時。匯出期間的開始時間包含在內，結束時間則不包含在內。

   1. 選擇**絕對模式**或**相對模式**。

      1. **絕對模式**會依您指定的期間匯出增量資料。

      1. **相對模式**會在相對於匯出任務提交時間的匯出期間匯出增量資料。

   1. 對於**匯出的檔案格式**，請選擇 **DynamoDB JSON** 和 **Amazon Ion** 兩者之一。根據預設，您的資料表會以 DynamoDB JSON 格式在時間點復原時段中的最近可還原時間匯出，並使用 Amazon S3 金鑰 (SSE-S3) 進行加密。您可以視需要變更這些匯出設定。
**注意**  
如果您選擇使用受 AWS Key Management Service (AWS KMS) 保護的金鑰來加密匯出，則金鑰必須位於與目的地 S3 儲存貯體相同的區域。

   1. 對於**匯出檢視類型**，請選取**新舊映像**或**僅限新映像**。新映像提供項目的最新狀態。舊映像提供項目在指定的「開始日期和時間」之前的狀態。預設設定為**新舊映像**。如需新映像和舊映像的詳細資訊，請參閱 [增量匯出輸出](S3DataExport.Output.md#incremental-export-output)。

------

1. 選擇**匯出**以開始。

匯出的資料在交易上不一致。您的交易操作可能在兩次匯出輸出之間未完成。您可能看到經交易操作修改的項目子集反映在匯出中，而同一交易中的另一個修改內容子集卻未反映在相同的匯出請求中。不過，匯出最後會是一致的。如果交易在匯出期間未完成，交易的其餘部分保證會在下一次連續匯出中出現，而且不會重複。用於匯出的期間是以內部系統時鐘為基礎，且可能與您的應用程式本機時鐘相差一分鐘。

## 取得 中過去匯出的詳細資訊 AWS 管理主控台
<a name="S3DataExport_Requesting_Console_Details"></a>

按一下導覽側邊欄中的**匯出至 S3** 區段，即可找到您過去曾執行的匯出任務的相關資訊。此區段包含您在過去 90 天內建立的所有匯出清單。選取**匯出**索引標籤中所列出任務的 ARN 以擷取該匯出的相關資訊，包括您選擇的任何進階組態設定。請注意，雖然匯出任務中繼資料會在 90 天後過期，也無法在此清單中找到早於該時間的任務，但只要儲存貯體政策允許，S3 儲存貯體中的物件就會保留。DynamoDB 絕不會刪除在匯出時其在您的 S3 儲存貯體中建立的任何物件。

## 使用 AWS CLI 和 AWS SDKs 請求匯出
<a name="S3DataExport_Requesting_CLI"></a>

下列範例示範如何將現有資料表匯出至 S3 儲存貯體。

**注意**  
此程序假設您已經啟用時間點復原。若要針對 `MusicCollection` 資料表啟用程序，請執行下列命令。  

```
aws dynamodb update-continuous-backups \
    --table-name MusicCollection \
    --point-in-time-recovery-specification PointInTimeRecoveryEnabled=True
```

**完整匯出**

------
#### [ AWS CLI ]

**注意**  
如果要求跨帳戶資料表匯出，請務必包含 `--s3-bucket-owner` 選項。

```
aws dynamodb export-table-to-point-in-time \
  --table-arn arn:aws:dynamodb:us-west-2:111122223333:table/MusicCollection \
  --s3-bucket ddb-export-musiccollection-9012345678 \
  --s3-prefix 2020-Nov \
  --export-format DYNAMODB_JSON \
  --export-time 1604632434 \
  --s3-bucket-owner 9012345678 \
  --s3-sse-algorithm AES256
```

------
#### [ Python ]

```
import boto3
from datetime import datetime

client = boto3.client('dynamodb')

client.export_table_to_point_in_time(
    TableArn='arn:aws:dynamodb:us-east-1:111122223333:table/TABLE',
    ExportTime=datetime(2023, 9, 20, 12, 0, 0),
    S3Bucket='bucket',
    S3Prefix='prefix',
    S3SseAlgorithm='AES256',
    ExportFormat='DYNAMODB_JSON'
)
```

------
#### [ Java ]

```
DynamoDbClient client = DynamoDbClient.create();

client.exportTableToPointInTime(b -> b
    .tableArn("arn:aws:dynamodb:us-east-1:111122223333:table/TABLE")
    .exportTime(Instant.parse("2023-09-20T12:00:00Z"))
    .s3Bucket("bucket")
    .s3Prefix("prefix")
    .s3SseAlgorithm(S3SseAlgorithm.AES256)
    .exportFormat(ExportFormat.DYNAMODB_JSON));
```

------
#### [ .NET ]

```
var client = new AmazonDynamoDBClient();

await client.ExportTableToPointInTimeAsync(new ExportTableToPointInTimeRequest
{
    TableArn = "arn:aws:dynamodb:us-east-1:111122223333:table/TABLE",
    ExportTime = new DateTime(2023, 9, 20, 12, 0, 0, DateTimeKind.Utc),
    S3Bucket = "bucket",
    S3Prefix = "prefix",
    S3SseAlgorithm = S3SseAlgorithm.AES256,
    ExportFormat = ExportFormat.DYNAMODB_JSON
});
```

------
#### [ JavaScript ]

```
import { DynamoDBClient, ExportTableToPointInTimeCommand } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient();

await client.send(new ExportTableToPointInTimeCommand({
    TableArn: "arn:aws:dynamodb:us-east-1:111122223333:table/TABLE",
    ExportTime: new Date("2023-09-20T12:00:00Z"),
    S3Bucket: "bucket",
    S3Prefix: "prefix",
    S3SseAlgorithm: "AES256",
    ExportFormat: "DYNAMODB_JSON"
}));
```

------
#### [ Go ]

```
cfg, _ := config.LoadDefaultConfig(context.TODO())
client := dynamodb.NewFromConfig(cfg)

exportTime := time.Date(2023, 9, 20, 12, 0, 0, 0, time.UTC)
client.ExportTableToPointInTime(context.TODO(), &dynamodb.ExportTableToPointInTimeInput{
    TableArn:       aws.String("arn:aws:dynamodb:us-east-1:111122223333:table/TABLE"),
    ExportTime:     &exportTime,
    S3Bucket:       aws.String("bucket"),
    S3Prefix:       aws.String("prefix"),
    S3SseAlgorithm: types.S3SseAlgorithmAes256,
    ExportFormat:   types.ExportFormatDynamodbJson,
})
```

------

**增量匯出**

------
#### [ AWS CLI ]

```
aws dynamodb export-table-to-point-in-time \
  --table-arn arn:aws:dynamodb:REGION:ACCOUNT:table/TABLENAME \
  --s3-bucket BUCKET --s3-prefix PREFIX \
  --incremental-export-specification ExportFromTime=1693569600,ExportToTime=1693656000,ExportViewType=NEW_AND_OLD_IMAGES \
  --export-type INCREMENTAL_EXPORT
```

------
#### [ Python ]

```
import boto3
from datetime import datetime

client = boto3.client('dynamodb')

client.export_table_to_point_in_time(
    TableArn='arn:aws:dynamodb:us-east-1:111122223333:table/TABLE',
    IncrementalExportSpecification={
      'ExportFromTime': datetime(2023, 9, 20, 12, 0, 0),
      'ExportToTime': datetime(2023, 9, 20, 13, 0, 0),
      'ExportViewType': 'NEW_AND_OLD_IMAGES'
    },
    ExportType='INCREMENTAL_EXPORT',
    S3Bucket='bucket',
    S3Prefix='prefix',
    S3SseAlgorithm='AES256',
    ExportFormat='DYNAMODB_JSON'
)
```

------
#### [ Java ]

```
DynamoDbClient client = DynamoDbClient.create();

client.exportTableToPointInTime(b -> b
    .tableArn("arn:aws:dynamodb:us-east-1:111122223333:table/TABLE")
    .exportType(ExportType.INCREMENTAL_EXPORT)
    .incrementalExportSpecification(i -> i
        .exportFromTime(Instant.parse("2023-09-20T12:00:00Z"))
        .exportToTime(Instant.parse("2023-09-20T13:00:00Z"))
        .exportViewType(ExportViewType.NEW_AND_OLD_IMAGES))
    .s3Bucket("bucket")
    .s3Prefix("prefix")
    .s3SseAlgorithm(S3SseAlgorithm.AES256)
    .exportFormat(ExportFormat.DYNAMODB_JSON));
```

------
#### [ .NET ]

```
var client = new AmazonDynamoDBClient();

await client.ExportTableToPointInTimeAsync(new ExportTableToPointInTimeRequest
{
    TableArn = "arn:aws:dynamodb:us-east-1:111122223333:table/TABLE",
    ExportType = ExportType.INCREMENTAL_EXPORT,
    IncrementalExportSpecification = new IncrementalExportSpecification
    {
        ExportFromTime = new DateTime(2023, 9, 20, 12, 0, 0, DateTimeKind.Utc),
        ExportToTime = new DateTime(2023, 9, 20, 13, 0, 0, DateTimeKind.Utc),
        ExportViewType = ExportViewType.NEW_AND_OLD_IMAGES
    },
    S3Bucket = "bucket",
    S3Prefix = "prefix",
    S3SseAlgorithm = S3SseAlgorithm.AES256,
    ExportFormat = ExportFormat.DYNAMODB_JSON
});
```

------
#### [ JavaScript ]

```
import { DynamoDBClient, ExportTableToPointInTimeCommand } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient();

await client.send(new ExportTableToPointInTimeCommand({
    TableArn: "arn:aws:dynamodb:us-east-1:111122223333:table/TABLE",
    ExportType: "INCREMENTAL_EXPORT",
    IncrementalExportSpecification: {
        ExportFromTime: new Date("2023-09-20T12:00:00Z"),
        ExportToTime: new Date("2023-09-20T13:00:00Z"),
        ExportViewType: "NEW_AND_OLD_IMAGES"
    },
    S3Bucket: "bucket",
    S3Prefix: "prefix",
    S3SseAlgorithm: "AES256",
    ExportFormat: "DYNAMODB_JSON"
}));
```

------
#### [ Go ]

```
cfg, _ := config.LoadDefaultConfig(context.TODO())
client := dynamodb.NewFromConfig(cfg)

fromTime := time.Date(2023, 9, 20, 12, 0, 0, 0, time.UTC)
toTime := time.Date(2023, 9, 20, 13, 0, 0, 0, time.UTC)
client.ExportTableToPointInTime(context.TODO(), &dynamodb.ExportTableToPointInTimeInput{
    TableArn:   aws.String("arn:aws:dynamodb:us-east-1:111122223333:table/TABLE"),
    ExportType: types.ExportTypeIncrementalExport,
    IncrementalExportSpecification: &types.IncrementalExportSpecification{
        ExportFromTime: &fromTime,
        ExportToTime:   &toTime,
        ExportViewType: types.ExportViewTypeNewAndOldImages,
    },
    S3Bucket:       aws.String("bucket"),
    S3Prefix:       aws.String("prefix"),
    S3SseAlgorithm: types.S3SseAlgorithmAes256,
    ExportFormat:   types.ExportFormatDynamodbJson,
})
```

------

**注意**  
如果您選擇使用受 AWS Key Management Service (AWS KMS) 保護的金鑰來加密匯出，則金鑰必須位於與目的地 S3 儲存貯體相同的區域。

## 使用 AWS CLI 和 AWS SDKs 取得過去匯出的詳細資訊
<a name="S3DataExport_Requesting_CLI_Details"></a>

使用 `list-exports` 命令即可找到您過去曾執行之匯出請求的相關資訊。此命令會傳回您在過去 90 天內建立的所有匯出清單。請注意，雖然匯出任務中繼資料會在 90 天後過期，也無法使用 `list-exports` 命令傳回早於該時間的任務，但只要儲存貯體政策允許，S3 儲存貯體中的物件就會保留。DynamoDB 絕不會刪除在匯出時其在您的 S3 儲存貯體中建立的任何物件。

在匯出成功或失敗之前，其狀態會是 `PENDING`。如果成功，狀態將變更為 `COMPLETED`。如果失敗，狀態將變更為 `FAILED` 並帶有 `failure_message` 和 `failure_reason`。

**列出匯出**

------
#### [ AWS CLI ]

```
aws dynamodb list-exports \
    --table-arn arn:aws:dynamodb:us-east-1:111122223333:table/ProductCatalog
```

------
#### [ Python ]

```
import boto3

client = boto3.client('dynamodb')

print(
  client.list_exports(
     TableArn='arn:aws:dynamodb:us-east-1:111122223333:table/TABLE',
  )
)
```

------
#### [ Java ]

```
DynamoDbClient client = DynamoDbClient.create();

ListExportsResponse response = client.listExports(b -> b
    .tableArn("arn:aws:dynamodb:us-east-1:111122223333:table/TABLE"));

response.exportSummaries().forEach(System.out::println);
```

------
#### [ .NET ]

```
var client = new AmazonDynamoDBClient();

var response = await client.ListExportsAsync(new ListExportsRequest
{
    TableArn = "arn:aws:dynamodb:us-east-1:111122223333:table/TABLE"
});

response.ExportSummaries.ForEach(Console.WriteLine);
```

------
#### [ JavaScript ]

```
import { DynamoDBClient, ListExportsCommand } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient();

const response = await client.send(new ListExportsCommand({
    TableArn: "arn:aws:dynamodb:us-east-1:111122223333:table/TABLE"
}));

console.log(response.ExportSummaries);
```

------
#### [ Go ]

```
cfg, _ := config.LoadDefaultConfig(context.TODO())
client := dynamodb.NewFromConfig(cfg)

response, _ := client.ListExports(context.TODO(), &dynamodb.ListExportsInput{
    TableArn: aws.String("arn:aws:dynamodb:us-east-1:111122223333:table/TABLE"),
})

fmt.Println(response.ExportSummaries)
```

------

**描述匯出**

------
#### [ AWS CLI ]

```
aws dynamodb describe-export \
    --export-arn arn:aws:dynamodb:us-east-1:111122223333:table/ProductCatalog/export/01695353076000-a1b2c3d4
```

------
#### [ Python ]

```
import boto3

client = boto3.client('dynamodb')

print(
  client.describe_export(
     ExportArn='arn:aws:dynamodb:us-east-1:111122223333:table/TABLE/export/01695353076000-06e2188f',
  )['ExportDescription']
)
```

------
#### [ Java ]

```
DynamoDbClient client = DynamoDbClient.create();

DescribeExportResponse response = client.describeExport(b -> b
    .exportArn("arn:aws:dynamodb:us-east-1:111122223333:table/TABLE/export/01695353076000-06e2188f"));

System.out.println(response.exportDescription());
```

------
#### [ .NET ]

```
var client = new AmazonDynamoDBClient();

var response = await client.DescribeExportAsync(new DescribeExportRequest
{
    ExportArn = "arn:aws:dynamodb:us-east-1:111122223333:table/TABLE/export/01695353076000-06e2188f"
});

Console.WriteLine(response.ExportDescription);
```

------
#### [ JavaScript ]

```
import { DynamoDBClient, DescribeExportCommand } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient();

const response = await client.send(new DescribeExportCommand({
    ExportArn: "arn:aws:dynamodb:us-east-1:111122223333:table/TABLE/export/01695353076000-06e2188f"
}));

console.log(response.ExportDescription);
```

------
#### [ Go ]

```
cfg, _ := config.LoadDefaultConfig(context.TODO())
client := dynamodb.NewFromConfig(cfg)

response, _ := client.DescribeExport(context.TODO(), &dynamodb.DescribeExportInput{
    ExportArn: aws.String("arn:aws:dynamodb:us-east-1:111122223333:table/TABLE/export/01695353076000-06e2188f"),
})

fmt.Println(response.ExportDescription)
```

------

# DynamoDB 資料表匯出輸出格式
<a name="S3DataExport.Output"></a>

DynamoDB 資料表匯出內容除了包含資料表資料的檔案之外，還包括資訊清單檔案。這些檔案全都儲存於您在[匯出請求](S3DataExport_Requesting.md)中指定的 Amazon S3 儲存貯體。以下各節說明每個輸出物件的格式和內容。

**Topics**

## 完整匯出輸出
<a name="full-export-output"></a>

### 資訊清單檔案
<a name="S3DataExport.Output_Manifest"></a>

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` 的空白檔案。此檔案驗證目的地儲存貯體可寫入並已開始進行匯出。您可以安全地刪除此檔案。

#### 摘要資訊清單
<a name="S3DataExport.Output_Manifest_Summary"></a>

`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"
}
```

#### 檔案資訊清單
<a name="S3DataExport.Output_Manifest_Files"></a>

`manifest-files.json` 檔案包含內含匯出資料表資料的檔案資訊。檔案採用 [JSON Lines](https://jsonlines.org/) 格式，因此新行將作為項目分隔符號使用。在下列範例中，為了便於閱讀，檔案資訊清單的資料檔案詳細資訊會採用多行格式。

```
{
"itemCount": 8,
   "md5Checksum": "sQMSpEILNgoQmarvDFonGQ==",
   "etag": "af83d6f217c19b8b0fff8023d8ca4716-1",
   "dataFileS3Key": "AWSDynamoDB/01693685827463-2d8752fd/data/asdl123dasas.json.gz"
}
```

### 資料檔案
<a name="S3DataExport.Output_Data"></a>

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
<a name="S3DataExport.Output_Data_DDB-JSON"></a>

以 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
<a name="S3DataExport.Output_Data_ION"></a>

[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"
    }
}
```

## 增量匯出輸出
<a name="incremental-export-output"></a>

### 資訊清單檔案
<a name="S3DataIncrementalExport.Output_Manifest"></a>

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` 的空白檔案。此檔案驗證目的地儲存貯體可寫入並已開始進行匯出。您可以安全地刪除此檔案。

#### 摘要資訊清單
<a name="S3DataIncrementalExport.Output_Manifest_Summary"></a>

`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"
}
```

#### 檔案資訊清單
<a name="S3DataIncrementalExport.Output_Manifest_Files"></a>

`manifest-files.json` 檔案包含內含匯出資料表資料的檔案資訊。檔案採用 [JSON Lines](https://jsonlines.org/) 格式，因此新行將作為項目分隔符號使用。在下列範例中，為了便於閱讀，檔案資訊清單的資料檔案詳細資訊會採用多行格式。

```
{
"itemCount": 8,
   "md5Checksum": "sQMSpEILNgoQmarvDFonGQ==",
   "etag": "af83d6f217c19b8b0fff8023d8ca4716-1",
   "dataFileS3Key": "AWSDynamoDB/data/sgad6417s6vss4p7owp0471bcq.json.gz"
}
```

### 資料檔案
<a name="S3DataIncrementalExport.Output_Data"></a>

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
<a name="S3DataIncrementalExport.Output_Data_DDB-JSON"></a>

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
<a name="S3DataIncrementalExport.Output_Data_ION"></a>

[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"
        }
    }
}
```