# Amazon S3 への DynamoDB データのエクスポート: 仕組み
DynamoDB の S3 へのエクスポートは、DynamoDB データを Amazon S3 バケットに大規模にエクスポートするためのフルマネージドソリューションです。S3 への DynamoDB エクスポートを使用すると、Amazon DynamoDB テーブルのデータを[ポイントインタイムリカバリ （PITR)](Point-in-time-recovery.md) ウィンドウ内の任意の時点から Amazon S3 バケットにエクスポートできます。エクスポート機能を使用するには、テーブルで PITR を有効にする必要があります。この機能を使用すると、Athena、AWS Glue、Amazon SageMaker AI、Amazon EMR や AWS Lake Formation などの他の AWS のサービスを使用して、データの分析や複雑なクエリを有効にできます。
S3 への DynamoDB エクスポートでは、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 でテーブルのエクスポートをリクエストする
DynamoDB テーブルのエクスポートを使用すると、テーブルデータを Amazon S3 バケットにエクスポートできます。これにより、Athena、AWS Glue、Amazon SageMaker AI、Amazon EMR、および AWS Lake Formation などの他の AWS のサービスを使用して、データに対して分析や複雑なクエリの実行が許可されます。テーブルのエクスポートをリクエストするには、AWS マネジメントコンソール、AWS CLI、または DynamoDB API のいずれかを使用します。
**注記**
Amazon S3 のリクエスタ支払いバケットはサポートされていません。
DynamoDB はフルエクスポートと増分エクスポートの両方をサポートしています。
+ **フルエクスポート**を使用すると、テーブルの完全なスナップショットをポイントインタイムリカバリ (PITR) ウィンドウ内の任意の時点から Amazon S3 バケットにエクスポートできます。
+ **増分エクスポート**では、指定した期間に変更、更新、または削除された DynamoDB テーブルのデータを、PITR ウィンドウ内で Amazon S3 バケットにエクスポートできます。
**Topics**
+ [前提条件](#S3DataExport_Requesting_Permissions)
+ [AWS マネジメントコンソール を使用してエクスポートをリクエストする](#S3DataExport_Requesting_Console)
+ [AWS マネジメントコンソール で過去のエクスポートの詳細を取得する](#S3DataExport_Requesting_Console_Details)
+ [AWS CLI および AWS SDK を使用してエクスポートをリクエストする](#S3DataExport_Requesting_CLI)
+ [AWS CLI および AWS SDK を使用して過去のエクスポートの詳細を取得する](#S3DataExport_Requesting_CLI_Details)
## 前提条件
**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/*"
}
]
}
```
------
別のアカウントにある Amazon S3 バケットに書き込む必要がある場合や書き込みアクセス許可がない場合、Amazon S3 バケット所有者は、DynamoDB からバケットへのエクスポートをユーザーに許可するバケットポリシーを追加する必要があります。エクスポート先の Amazon 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 ユーザー/ロールを通じて付与されます。ベストプラクティスを含む暗号化の詳細については、「[Amazon 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 マネジメントコンソール を使用してエクスポートをリクエストする
DynamoDB コンソールを使用して、`MusicCollection` という既存のテーブルをエクスポートする方法を次の例に示します。
**注記**
この手順は、ポイントインタイムリカバリを有効にしていることを前提としています。これを `MusicCollection` テーブルに対して有効にするには、[**Overview**] (概要) タブにある [**Table details**] (テーブルの詳細) セクションの [**Point-in-time recovery**] (ポイントインタイムリカバリ) で [**Enable**] (有効化) を選択します。
**テーブルのエクスポートをリクエストするには**
1. AWS マネジメントコンソール にサインインして DynamoDB コンソール ([https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)) を開きます。
1. コンソールの左側のナビゲーションペインで、**[S3 へのエクスポート]** を選択します。
1. **[S3 にエクスポート]** ボタンを選択します。
1. コピー元テーブルとエクスポート先の S3 バケットを選択します。エクスポート先のバケットがお客様のアカウントによって所有されている場合は、**[Browse S3]** (S3 を参照) ボタンをクリックしてバケットを検索します。そうでない場合は、`s3://bucketname/prefix format.` の形式でバケットの URL を入力します。ここで、**prefix** は、エクスポート先のバケットを整理するのに役立つオプションのフォルダです。
1. **[フルエクスポート]** または **[増分エクスポート]** を選択します。**フルエクスポート**では、指定した時点のテーブルのフルテーブルスナップショットが出力されます。**増分エクスポート**では、指定したエクスポート期間中にテーブルに加えられた変更が出力されます。出力は、エクスポート期間における項目の最終状態のみを含むように圧縮されます。同じエクスポート期間内に複数の更新があったとしても、項目はエクスポートに 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. **[エクスポート]** を選択して開始します。
エクスポートされたデータは、トランザクションとして一貫しません。トランザクションオペレーションは、2 つのエクスポート出力間で分断される可能性があります。トランザクションオペレーションで変更された項目のサブセットはエクスポートに反映される一方で、同じトランザクションで変更された別のサブセットは同じエクスポートリクエストに反映されない場合があります。ただし、最終的にエクスポートの一貫性は保たれます。エクスポート中にトランザクションが分断された場合、残りのトランザクションは直後のエクスポートに (重複することなく) 含まれます。エクスポートに使用される時間は内部システムクロックに基づいており、変動する可能性はアプリケーションのローカルクロックの 1 分のみです。
## AWS マネジメントコンソール で過去のエクスポートの詳細を取得する
過去に実行したエクスポートタスクに関する情報は、ナビゲーションサイドバーで **[S3 へのエクスポート]** セクションを選択して確認できます。このセクションには、過去 90 日間に作成したエクスポートの一覧が表示されます。**[エクスポート]** タブにリストされているタスクの ARN を選択すると、エクスポートに関する情報 (選択した詳細設定など) を取得できます。エクスポートタスクのメタデータは 90 日後に期限切れになり、それより古いジョブはこのリストに表示されなくなりますが、S3 バケット内のオブジェクトは、バケットポリシーで許可されている限り維持されます。エクスポート中に S3 バケットに作成されたオブジェクトが DynamoDB によって削除されることはありません。
## AWS CLI および AWS SDK を使用してエクスポートをリクエストする
以下の例は、既存のテーブルを 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 SDK を使用して過去のエクスポートの詳細を取得する
過去に実行したエクスポートリクエストに関する情報は、`list-exports` コマンドを実行して見つけることができます。このコマンドは、過去 90 日間に作成されたすべてのエクスポートのリストを返します。エクスポートタスクのメタデータは 90 日後に期限切れになり、それより古いジョブは `list-exports` コマンドによって返されなくなりますが、S3 バケット内のオブジェクトは、バケットポリシーで許可されている限り維持されます。エクスポート中に S3 バケットに作成されたオブジェクトが DynamoDB によって削除されることはありません。
エクスポートのステータスは、成功または失敗するまで `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 テーブルのエクスポート出力形式
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/) 形式であるため、改行が項目区切り文字として使用されます。次の例では、読みやすくするためにファイルマニフェストの 1 つのデータファイルの詳細が複数行にフォーマットされています。
```
{
"itemCount": 8,
"md5Checksum": "sQMSpEILNgoQmarvDFonGQ==",
"etag": "af83d6f217c19b8b0fff8023d8ca4716-1",
"dataFileS3Key": "AWSDynamoDB/01693685827463-2d8752fd/data/asdl123dasas.json.gz"
}
```
### データファイル
DynamoDB では、DynamoDB JSON と Amazon Ion の 2 つの形式でテーブルデータをエクスポートできます。選択した形式にかかわらず、データは、 キーによって名前が付けられた複数の圧縮ファイルに書き込まれます。これらのファイルも `manifest-files.json` ファイル内に一覧表示されます。
フルエクスポート後の Amazon S3 バケットのディレクトリ構造では、export 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 Glue など、多くの AWS サービスで、この形式は自動的に解析されます。
次の例では、読みやすくするために DynamoDB JSON エクスポートの 1 つの項目が複数行にフォーマットされています。
```
{
"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 データ型と ion データ型のマッピングを示します。
| DynamoDB データ型 | Ion 表現 |
| --- | --- |
| 文字列 (S) | 文字列 |
| ブール型 (BOOL) | ブール |
| 数値 (N) | 小数点 |
| バイナリ (B) | blob |
| セット (SS、NS、BS) | リスト (型注釈 \$1DynamoDB\$1SS、\$1DynamoDB\$1NS、または \$1DynamoDB\$1BS) |
| リスト | リスト |
| マップ | 構造体 |
Ion エクスポート内の項目は、改行で区切られます。各行は Ion バージョンマーカーで始まり、Ion 形式の項目が続きます。次の例では、読みやすくするために 1 つの 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/) 形式であるため、改行が項目区切り文字として使用されます。次の例では、読みやすくするためにファイルマニフェストの 1 つのデータファイルの詳細が複数行にフォーマットされています。
```
{
"itemCount": 8,
"md5Checksum": "sQMSpEILNgoQmarvDFonGQ==",
"etag": "af83d6f217c19b8b0fff8023d8ca4716-1",
"dataFileS3Key": "AWSDynamoDB/data/sgad6417s6vss4p7owp0471bcq.json.gz"
}
```
### データファイル
DynamoDB では、DynamoDB JSON と Amazon Ion の 2 つの形式でテーブルデータをエクスポートできます。選択した形式にかかわらず、データは、 キーによって名前が付けられた複数の圧縮ファイルに書き込まれます。これらのファイルも `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` オペレーションであったかどうかを示すデータ構造が含まれます。タイムスタンプは内部システムクロックに基づいており、アプリケーションクロックとは異なる場合があります。増分エクスポートでは、出力構造の 2 つのエクスポートビュータイプ (**新旧イメージ**、または**新しいイメージのみ**) を選択できます。
+ **新しいイメージ**には、項目の最新の状態が表示されます。
+ **古いイメージ**には、**指定した開始日時**の直前の項目の状態が表示されます。
ビュータイプは、エクスポート期間中に項目がどのように変更されたかを確認する場合に役立ちます。また、特にダウンストリームシステムに DynamoDB パーティションキーと異なるパーティションキーがある場合に、ダウンストリームシステムを効率的に更新するのにも役立ちます。
増分エクスポート出力の項目が `insert`、`update`、または `delete` のどれであったかは、出力の構造を見れば推測できます。両方のエクスポートビュータイプについて、増分エクスポートの構造とそれに対応するオペレーションを以下の表にまとめています。
| Operation | 新しいイメージのみ | 新旧イメージ |
| --- | --- | --- |
| Insert | キー \$1 新しいイメージ | キー \$1 新しいイメージ |
| 更新 | キー \$1 新しいイメージ | キー \$1 新しいイメージ \$1 古いイメージ |
| 削除 | キー | キー \$1 古いイメージ |
| delete \$1 insert | 出力なし | 出力なし |
#### 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 データ型と ion データ型のマッピングを示します。
| DynamoDB データ型 | Ion 表現 |
| --- | --- |
| 文字列 (S) | 文字列 |
| ブール型 (BOOL) | ブール |
| 数値 (N) | 小数点 |
| バイナリ (B) | blob |
| セット (SS、NS、BS) | リスト (型注釈 \$1DynamoDB\$1SS、\$1DynamoDB\$1NS、または \$1DynamoDB\$1BS) |
| リスト | リスト |
| マップ | 構造体 |
Ion エクスポート内の項目は、改行で区切られます。各行は Ion バージョンマーカーで始まり、Ion 形式の項目が続きます。次の例では、読みやすくするために 1 つの 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"
}
}
}
```