Amazon Timestream for LiveAnalytics に類似した機能をご希望の場合は Amazon Timestream for InfluxDB をご検討ください。リアルタイム分析に適した、シンプルなデータインジェストと 1 桁ミリ秒のクエリ応答時間を特徴としています。詳細については、[こちら](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html)を参照してください。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Timestream for LiveAnalytics でのバッチロードの使用
Amazon Timestream for LiveAnalytics の*バッチロード*を使用すると、Amazon S3 に保存されている CSV ファイルをバッチで Timestream に取り込むことができます。この新機能により、他のツールに頼ったり、カスタムコードを記述したりすることなく、Timestream for LiveAnalytics でデータを取得できます。バッチロードを使用して、クエリや分析にすぐに必要ではないデータなどを、柔軟な待機時間でバックフィルできます。
バッチロードタスクは AWS CLI、 AWS マネジメントコンソール、、および AWS SDKs を使用して作成できます。詳細については[コンソールでのバッチロードの使用](batch-load-using-console.md)、[でのバッチロードの使用 AWS CLI](batch-load-using-cli.md)、および[AWS SDKs](batch-load-using-sdk.md)を参照してください。
バッチロードに加えて、WriteRecords API オペレーションを使用して複数のレコードを同時に書き込むことができます。どちらを使用すべきかのガイダンスについては、「[WriteRecords API オペレーションかバッチロードかの選択](writes.writes-or-batch-load.md)」を参照してください。
**Topics**
+ [Timestream でのバッチロードの概念](batch-load-concepts.md)
+ [バッチロードの前提条件](batch-load-prerequisites.md)
+ [バッチロードのベストプラクティス](batch-load-best-practices.md)
+ [バッチロードデータファイルの準備](batch-load-preparing-data-file.md)
+ [バッチロードのデータモデルマッピング](batch-load-data-model-mappings.md)
+ [コンソールでのバッチロードの使用](batch-load-using-console.md)
+ [でのバッチロードの使用 AWS CLI](batch-load-using-cli.md)
+ [AWS SDKs](batch-load-using-sdk.md)
+ [バッチロードエラーレポートの使用](batch-load-using-error-reports.md)
# Timestream でのバッチロードの概念
バッチロード機能の理解を深めるため、次の概念を確認してください。
**バッチロードタスク** – Amazon Timestream でソースデータと送信先を定義するタスク。バッチロードタスクを作成するときに、データモデルなどの追加設定を指定します。バッチロードタスクは AWS マネジメントコンソール、、 AWS CLI、および AWS SDKs を使用して作成できます。
**インポート先** – Timestream の送信先データベースとテーブル。データベースとテーブルの作成については、「[データベースを作成する](console_timestream.md#console_timestream.db.using-console)」と「[テーブルを作成する](console_timestream.md#console_timestream.table.using-console)」を参照してください。
**データソース** – S3 バケットに保存されているソースの CSV ファイル。データファイルの準備については、「[バッチロードデータファイルの準備](batch-load-preparing-data-file.md)」を参照してください。S3 の料金については、「[Amazon S3 料金表](https://aws.amazon.com/s3/pricing/)」を参照してください。
**バッチロードエラーレポート** – バッチロードタスクのエラーに関する情報を保存するレポート。バッチロードエラーレポートの S3 ロケーションは、バッチロードタスクの一部として定義します。レポート内の情報については、「[バッチロードエラーレポートの使用](batch-load-using-error-reports.md)」を参照してください。
**データモデルマッピング** – S3 ロケーションのデータソースからターゲットとなる Timestream for LiveAnalytics テーブルへの時間、ディメンション、メジャーのバッチロードマッピング。詳細については、「[バッチロードのデータモデルマッピング](batch-load-data-model-mappings.md)」を参照してください。
# バッチロードの前提条件
これは、バッチロードを使用するための前提条件のリストです。ベストプラクティスについては、[バッチロードのベストプラクティス](batch-load-best-practices.md)を参照してください。
+ バッチロードソースデータは、ヘッダーを含む CSV 形式で Amazon S3 に保存されます。
+ Amazon S3 ソースバケットごとに、アタッチされたポリシーに次の権限が必要です。
```
"s3:GetObject",
"s3:GetBucketAcl"
"s3:ListBucket"
```
同様に、レポートが書き込まれる Amazon S3 出力バケットごとに、アタッチされたポリシーに次の権限が必要です。
```
"s3:PutObject",
"s3:GetBucketAcl"
```
例えば、次のようになります。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"s3:GetObject",
"s3:GetBucketAcl",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-source-bucket1\u201d",
"arn:aws:s3:::amzn-s3-demo-source-bucket2\u201d"
],
"Effect": "Allow"
},
{
"Action": [
"s3:PutObject",
"s3:GetBucketAcl"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-destination-bucket\u201d"
],
"Effect": "Allow"
}
]
}
```
------
+ Timestream for LiveAnalytics は、データモデルで提供された情報を CSV ヘッダーにマッピングすることで CSV を解析します。データには、タイムスタンプを表す列、少なくとも 1 つのディメンション列、および少なくとも 1 つのメジャー列が必要です。
+ バッチロードで使用される S3 バケットは、バッチロードで使用される Timestream for LiveAnalytics テーブルと同じリージョンの同じアカウントにある必要があります。
+ `timestamp` 列は、Unix エポックからの時間を表す long データ型である必要があります。例えば、`2021-03-25T08:45:21Z` というタイムスタンプは `1616661921` と表されます。Timestream がサポートしているタイムスタンプ精度は、秒、ミリ秒、マイクロ秒、ナノ秒です。クエリ言語を使用する場合、`to_unixtime` などの関数を使用して形式を変換できます。詳細については、「[日付/時間関数](date-time-functions.md)」を参照してください。
+ Timestream は、ディメンション値については文字列データ型をサポートしています。メジャー列については長整数、倍精度浮動小数点数、文字列、ブールの各データ型をサポートしています。
バッチロードの制限とクォータについては、「[バッチロード](ts-limits.md#limits.batch-load)」を参照してください。
# バッチロードのベストプラクティス
次の条件と推奨事項に準拠している場合、バッチロードで最適な動作が得られます (高スループット)。
1. 並列処理と取り込み速度を向上させるために、取り込み用に送信される CSV ファイルが小さい (特に、ファイルサイズが 100 MB～1 GB)。
1. バッチロードの進行中は、同じテーブルに同時にデータを取り込まないようにする (WriteRecords API オペレーションやスケジュールされたクエリの使用など)。これによりスロットリングが発生する可能性があり、バッチロードタスクは失敗します。
1. バッチロードタスクの実行中に、バッチロードで使用される S3 バケットからファイルを追加、変更、または削除しない。
1. テーブルまたはソースから権限を削除または取り消したり、バッチロードタスクがスケジュールされているか進行中の S3 バケットをレポートしたりしない。
1. カーディナリティの高いディメンション値のセットを持つデータを取り込む場合は、「[マルチメジャーレコードのパーティショニングに関する推奨事項](data-modeling.md#data-modeling-multi-measure-partitioning)」のガイダンスに従う。
1. 小さなファイルを送信して、データの正確性をテストする。バッチロードに送信されたデータについては、正確性に関係なく課金されます。料金の詳細については、「[Amazon Timestream pricing](https://aws.amazon.com/timestream/pricing/)」を参照してください。
1. `ActiveMagneticStorePartitions` が 250 未満でない限り、バッチロードタスクを再開しない。ジョブがスロットリングされて失敗する可能性があります。同じデータベースに対して複数のジョブを同時に送信すると数が減ります。
コンソールのベストプラクティスは以下のとおりです。
1. [ビルダー](batch-load-using-console.md#batch-load-using-visual-builder)は、マルチメジャーレコードに単一のメジャー名のみを使用する単純なデータモデリングにのみ使用します。
1. より複雑なデータモデリングには、JSON を使用します。例えば、マルチメジャーレコードを使用するときに複数のメジャー名を使用する場合は、JSON を使用します。
他の Timestream for LiveAnalytics のベストプラクティスについては、「[ベストプラクティス](best-practices.md)」を参照してください。
# バッチロードデータファイルの準備
ソースデータファイルには区切り文字で区切られた値があります。より具体的な用語でいうと、カンマ区切り値 (CSV) がよく使用されます。列の有効な区切り文字には、カンマとパイプなどがあります。レコードは新しい行で区切られます。ファイルは Amazon S3 に保存する必要があります。新しいバッチロードタスクを作成すると、ソースデータの場所はファイルの ARN によって指定されます。ファイルにはヘッダーが含まれています。1 つの列はタイムスタンプを表します。少なくとも 1 つの他の列はメジャーを表します。
バッチロードで使用される S3 バケットは、バッチロードで使用される Timestream for LiveAnalytics テーブルと同じリージョンに存在する必要があります。バッチロードタスクの送信後に、バッチロードで使用される S3 バケットにファイルを追加または削除しないでください。S3 バケットの取り扱いについて詳しくは、「[Amazon S3 の開始方法](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html)」を参照してください。
**注記**
Excel などの一部のアプリケーションによって生成される CSV ファイルには、予想されるエンコーディングと競合するバイトオーダーマーク (BOM) が含まれている場合があります。BOM 付きの CSV ファイルを参照する Timestream for LiveAnalytics のバッチロードタスクは、プログラムで処理されるとエラーをスローします。これを回避するには、非表示の文字である BOM を削除します。
例えば、新しいエンコードを指定できる Notepad\$1\$1 などのアプリケーションからファイルを保存できます。また、最初の行を読み取ってその行から BOM を削除し、ファイルの最初の行に新しい値を書き込むプログラムオプションを使用することもできます。
Excel から保存する場合、複数の CSV オプションがあります。別の CSV オプションで保存すると、説明した問題の発生を防止できる可能性があります。ただし、エンコードの変更が一部の文字に影響する可能性があるため、結果を確認する必要があります。
## CSV 形式パラメータ
エスケープ文字は、形式パラメータで予約されている値を表すときに使用します。例えば、引用文字が二重引用符の場合、データ内で二重引用符を表すには、二重引用符の前にエスケープ文字を配置します。
バッチロードタスクの作成時にこれらを指定するタイミングについては、「[バッチロードタスクを作成する](batch-load-using-console.md#console_timestream.create-batch-load.using-console)」を参照してください。
| パラメータ | オプション |
| --- | --- |
| 列区切り文字 | (カンマ (',') \$1 パイプ ('\$1') \$1 セミコロン (';') \$1 タブ ('/t') \$1 空白 (' ')) |
| エスケープ文字 | なし |
| 引用文字 | コンソール: (二重引用符 (") \$1 一重引用符 (')) |
| Null 値 | 空白 (' ') |
| 空白を削除する | コンソール: (いいえ \$1 はい) |
# バッチロードのデータモデルマッピング
以下にデータモデルマッピングのスキーマについて説明し、例を示します。
## データモデルマッピングスキーマ
`DescribeBatchLoadTask` への呼び出しによって返される `CreateBatchLoadTask` リクエスト構文と `BatchLoadTaskDescription` オブジェクトには、バッチロード用の `DataModel` を含む `DataModelConfiguration` オブジェクトが含まれます。`DataModel` は、S3 ロケーションに CSV 形式で保存されているソースデータからターゲットの Timestream for LiveAnalytics データベースとテーブルへのマッピングを定義します。
`TimeColumn` フィールドは、Timestream for LiveAnalytics の送信先テーブルの `time` 列にマッピングされる値のソースデータの場所を示します。`TimeUnit` は `TimeColumn` の単位を指定し、`MILLISECONDS`、`SECONDS`、`MICROSECONDS`、`NANOSECONDS` のいずれかを指定できます。ディメンションとメジャーのマッピングもあります。ディメンションマッピングは、ソース列とターゲットフィールドで構成されます。
詳細については、「[DimensionMapping](https://docs.aws.amazon.com/timestream/latest/developerguide/API_DimensionMapping)」を参照してください。メジャーのマッピングには、`MixedMeasureMappings` と `MultiMeasureMappings` の 2 つのオプションがあります。
要約すると、`DataModel` には、S3 ロケーションにあるデータソースからターゲットの Timestream for LiveAnalytics テーブルへのマッピングが含まれます。
+ Time
+ ディメンション
+ メジャー
可能であれば、メジャーデータを Timestream for LiveAnalytics のマルチメジャーレコードにマッピングすることをお勧めします。マルチメジャーレコードの利点については、「[マルチメジャーレコード](writes.md#writes.writing-data-multi-measure)」を参照してください。
ソースデータの複数のメジャーが単一の行に保存されている場合は、`MultiMeasureMappings` を使用して、これらの複数のメジャーを Timestream for LiveAnalytics のマルチメジャーレコードにマッピングできます。単一メジャーレコードへのマッピングが必要な値がある場合は、`MixedMeasureMappings` を使用できます。
`MixedMeasureMappings` と `MultiMeasureMappings` の両方に `MultiMeasureAttributeMappings` が含まれます。単一メジャーレコードが必要かどうかにかかわらず、マルチメジャーレコードがサポートされます。
Timestream for LiveAnalytics でマルチメジャーターゲットレコードのみが必要な場合は、次の構造でメジャーマッピングを定義できます。
```
CreateBatchLoadTask
MeasureNameColumn
MultiMeasureMappings
TargetMultiMeasureName
MultiMeasureAttributeMappings array
```
**注記**
可能な場合は常に、`MultiMeasureMappings` を使用することをお勧めします。
Timestream for LiveAnalytics で単一メジャーターゲットレコードが必要な場合は、次の構造でメジャーマッピングを定義できます。
```
CreateBatchLoadTask
MeasureNameColumn
MixedMeasureMappings array
MixedMeasureMapping
MeasureName
MeasureValueType
SourceColumn
TargetMeasureName
MultiMeasureAttributeMappings array
```
`MultiMeasureMappings` を使用する場合、`MultiMeasureAttributeMappings` 配列が常に必要となります。`MixedMeasureMappings` 配列を使用するとき、`MeasureValueType` が特定の `MixedMeasureMapping` の `MULTI` である場合、その `MixedMeasureMapping` には `MultiMeasureAttributeMappings` が必要です。それ以外の場合、`MeasureValueType` は単一メジャーレコードのメジャータイプを示します。
いずれの場合も、`MultiMeasureAttributeMapping` の配列を使用できます。各 `MultiMeasureAttributeMapping` のマルチメジャーレコードへのマッピングは、次のように定義します。
`SourceColumn`
Amazon S3 にあるソースデータの列。
`TargetMultiMeasureAttributeName`
送信先テーブル内のターゲットマルチメジャーの名前。この入力は、`MeasureNameColumn` が指定されていない場合に必須です。`MeasureNameColumn` が指定されている場合、その列の値がマルチメジャー名として使用されます。
`MeasureValueType`
`DOUBLE`、`BIGINT`、`BOOLEAN`、`VARCHAR`、`TIMESTAMP` のいずれか。
## `MultiMeasureMappings` の例を使用したデータモデルマッピング
この例では、推奨アプローチである各メジャー値を専用列に保存するマルチメジャーレコードへのマッピングを示します。サンプル CSV は[サンプル CSV](samples/batch-load-sample-file.csv.zip) でダウンロードできます。サンプルには、Timestream for LiveAnalytics テーブルのターゲット列にマッピングする次の見出しがあります。
+ `time`
+ `measure_name`
+ `region`
+ `location`
+ `hostname`
+ `memory_utilization`
+ `cpu_utilization`
CSV ファイル内の列 `time` と列 `measure_name` を特定します。この場合、これらは同じ名前の Timestream for LiveAnalytics テーブル列に直接マッピングされます。
+ `time` は `time` にマッピングされる
+ `measure_name` は `measure_name` (または選択した値) にマッピングされる
API を使用している場合は、`TimeColumn` フィールドに `time` を指定し、`TimeUnit` フィールドに `MILLISECONDS` などのサポートされている時間単位の値を指定します。これらは、コンソールの**ソース列名**と**タイムスタンプ時間入力**に対応しています。`MeasureNameColumn` キーで定義されている `measure_name` を使用して、レコードをグループ化またはパーティション化できます。
サンプルでは、`region`、`location`、`hostname` はディメンションです。ディメンションは `DimensionMapping` オブジェクトの配列にマッピングされます。
メジャーの場合、値 `TargetMultiMeasureAttributeName` は Timestream for LiveAnalytics テーブルの列になります。この例のように、同じ名前を保持できます。または、新しい名前を指定できます。`MeasureValueType` は、`DOUBLE`、`BIGINT`、`BOOLEAN`、`VARCHAR`、`TIMESTAMP` のいずれかです。
```
{
"TimeColumn": "time",
"TimeUnit": "MILLISECONDS",
"DimensionMappings": [
{
"SourceColumn": "region",
"DestinationColumn": "region"
},
{
"SourceColumn": "location",
"DestinationColumn": "location"
},
{
"SourceColumn": "hostname",
"DestinationColumn": "hostname"
}
],
"MeasureNameColumn": "measure_name",
"MultiMeasureMappings": {
"MultiMeasureAttributeMappings": [
{
"SourceColumn": "memory_utilization",
"TargetMultiMeasureAttributeName": "memory_utilization",
"MeasureValueType": "DOUBLE"
},
{
"SourceColumn": "cpu_utilization",
"TargetMultiMeasureAttributeName": "cpu_utilization",
"MeasureValueType": "DOUBLE"
}
]
}
}
```
![\[Visual builder interface showing column mappings for timestream data attributes and types.\]](http://docs.aws.amazon.com/ja_jp/timestream/latest/developerguide/images/column-mapping.jpg)
## `MixedMeasureMappings` の例を使用したデータモデルマッピング
このアプローチは、Timestream for LiveAnalytics の単一メジャーレコードにマッピングする必要がある場合にのみ使用することをお勧めします。
# コンソールでのバッチロードの使用
以下は、 AWS マネジメントコンソールでバッチロードを使用する手順です。サンプル CSV は[サンプル CSV](samples/batch-load-sample-file.csv.zip) でダウンロードできます。
**Topics**
+ [バッチロードへのアクセス](#console_timestream.access-batch-load.using-console)
+ [バッチロードタスクを作成する](#console_timestream.create-batch-load.using-console)
+ [バッチロードタスクの再開](#console_timestream.resume-batch-load.using-console)
+ [ビジュアルビルダーの使用](#batch-load-using-visual-builder)
## バッチロードへのアクセス
AWS マネジメントコンソールを使用してバッチロードにアクセスするには、次の手順に従います。
1. [Amazon Timestream コンソール](https://console.aws.amazon.com/timestream)を開きます。
1. ナビゲーションペインで、**[管理ツール]**、**[バッチロードタスク]** の順に選択します。
1. ここから、バッチロードタスクのリストを表示し、特定のタスクの詳細を確認できます。タスクを作成および再開することもできます。
## バッチロードタスクを作成する
AWS マネジメントコンソールを使用してバッチロードタスクを作成するには、次の手順に従います。
1. [Amazon Timestream コンソール](https://console.aws.amazon.com/timestream)を開きます。
1. ナビゲーションペインで、**[管理ツール]**、**[バッチロードタスク]** の順に選択します。
1. **[バッチロードタスクを作成]** を選択します。
1. **[インポート先]** で、次を選択します。
+ **[ターゲットデータベース]** – 「[データベースを作成する](console_timestream.md#console_timestream.db.using-console)」で作成されたデータベース名を選択します。
+ **[ターゲットテーブル]** – 「[テーブルを作成する](console_timestream.md#console_timestream.table.using-console)」で作成されたテーブル名を選択します。
必要に応じて、**[新しいテーブルを作成]** ボタンを使用して、このパネルからテーブルを追加できます。
1. **[データソース]** の **[データソースの S3 ロケーション]** から、ソースデータが保存されている S3 バケットを選択します。**S3 参照**ボタンを使用して、アクティブな AWS アカウントがアクセスできる S3 リソースを表示するか、S3 ロケーション URL を入力します。データソースは同じリージョンに配置する必要があります。
1. **[ファイル形式の設定]** (拡張可能セクション) では、デフォルト設定を使用して入力データを解析できます。**[高度な設定]** を選択することもできます。そこから **[CSV 形式のパラメータ]** を選択し、入力データを解析するパラメータを選択できます。これらのパラメータについては、「[CSV 形式パラメータ](batch-load-preparing-data-file.md#batch-load-data-file-options)」を参照してください。
1. **[データモデルマッピングを設定]** から、データモデルを設定します。データモデルに関するその他のガイダンスについては、「[バッチロードのデータモデルマッピング](batch-load-data-model-mappings.md)」を参照してください。
+ **[データモデルマッピング]** から **[マッピング設定入力]** を選択し、次のいずれかを選択します。
+ **[ビジュアルビルダー]** – データを視覚的にマッピングするには、**[TargetMultiMeasureName]** または **[MeasureNameColumn]** を選択します。次に、**[ビジュアルビルダー]** から列をマッピングします。
ビジュアルビルダーは、単一の CSV ファイルがデータソースとして選択されたときに、データソースファイルからソース列ヘッダーを自動的に検出してロードします。属性とデータ型を選択してマッピングを作成します。
ビジュアルビルダーの使用について詳しくは、「[ビジュアルビルダーの使用](#batch-load-using-visual-builder)」を参照してください。
+ **[JSON エディタ]** – データモデルを設定するための自由形式の JSON エディタ。Timestream for LiveAnalytics に精通しており、高度なデータモデルマッピングを構築する場合は、このオプションを選択します。
+ **[S3 からの JSON ファイル]** – S3 に保存した JSON モデルファイルを選択します。データモデルを既に設定していて、追加のバッチロードに再利用する場合は、このオプションを選択します。
1. **[エラーログレポート]** の **[エラーログの S3 ロケーション]** から、エラーの報告に使用される S3 ロケーションを選択します。このレポートの使用方法については、「[バッチロードエラーレポートの使用](batch-load-using-error-reports.md)」を参照してください。
1. **[暗号化キータイプ]** で、次のいずれかを選択します。
+ **[Amazon S3-managed キー (SSE-S3)]** – Amazon S3 が作成、管理、使用する暗号化キー。
+ **AWS KMS key (SSE-KMS)** – AWS Key Management Service () で保護された暗号化キーAWS KMS。
1. [**次へ**] を選択します。
1. **[レビューして作成]** ページで設定を確認し、必要に応じて編集します。
**注記**
タスクの作成後にバッチロードタスク設定を変更することはできません。タスクの完了時間は、インポートされるデータの量によって異なります。
1. **[バッチロードタスクを作成]** を選択します。
## バッチロードタスクの再開
「進行が停止しました」というステータス (引き続き再開可能) のバッチロードタスクを選択すると、タスクを再開するように求められます。これらのタスクの詳細を表示すると、**[タスクを再開]** ボタンを含むバナーもあります。再開可能なタスクには「再開期限」日が記載されています。その日付を過ぎると、タスクを再開することはできません。
## ビジュアルビルダーの使用
ビジュアルビルダーを使用して、S3 バケットに保存されている 1 つ以上の CSV ファイルのソースデータ列を、Timestream for LiveAnalytics テーブルの送信先列にマッピングできます。
**注記**
ロールには、ファイルの `SelectObjectContent` 権限が必要です。この権限がない場合は、列を手動で追加および削除する必要があります。
### ソース列の自動ロードモード
Timestream for LiveAnalytics では、単一のバケットのみを指定すると、ソース CSV ファイルを自動的にスキャンして列名を探すことができます。既存のマッピングがない場合は、**[ソース列をインポート]** を選択できます。
1. **[マッピング設定入力設定]** から **[ビジュアルビルダー]** オプションを選択し、タイムスタンプの時間入力を設定します。`Milliseconds` がデフォルト設定です。
1. ソースデータファイルにある列ヘッダーをインポートするには、**[ソース列を読み込む]** ボタンをクリックします。テーブルには、データソースファイルのソース列ヘッダー名が入力されます。
1. 各ソース列の **[ターゲットテーブルの列名]**、**[Timestream 属性タイプ]**、**[データ型]** を選択します。
これらの列と指定できる値の詳細については、「[フィールドのマッピング](#batch-load-using-visual-builder-mapping-fields)」を参照してください。
1. drag-to-fill 機能を使用して、一度に複数の列の値を設定します。
### ソース列を手動で追加する
単一の CSV ではなくバケットまたは CSV プレフィックスを使用している場合は、**[列マッピングを追加]** ボタンと **[列マッピングを削除]** ボタンを使用して、ビジュアルエディタから列マッピングを追加および削除できます。マッピングをリセットするボタンもあります。
### フィールドのマッピング
+ **[ソース列名]** – インポートするメジャーを表すソースファイル内の列の名前。Timestream for LiveAnalytics は、**[ソース列をインポート]** を使用するときに、この値を自動的に入力できます。
+ **[ターゲットテーブルの列名]** – ターゲットテーブルのメジャーの列名を示すオプションの入力。
+ **[Timestream 属性タイプ]** – `DIMENSION` など、指定されたソース列内のデータの属性タイプ。
+ **TIMESTAMP** – メジャーが収集された日時を指定します。
+ **MULTI** – 複数のメジャーが表されます。
+ **DIMENSION** – 時系列メタデータ。
+ **MEASURE\$1NAME** – 単一メジャーレコードの場合、これがメジャー名です。
+ **[データ型]** – `BOOLEAN` など、Timestream 列のタイプ。
+ **BIGINT** – 64 ビットの整数。
+ **BOOLEAN** – ロジックの 2 つの真理値である true と false。
+ **DOUBLE** – 64 ビットの可変精度数。
+ **TIMESTAMP** – UTC でナノ秒の精度時間を使用し、Unix エポックからの時間を追跡する時間内のインスタンス。
# でのバッチロードの使用 AWS CLI
**セットアップ**
バッチロードの使用を開始するには、次の手順を実行します。
1. 「」の手順 AWS CLI を使用して をインストールします[を使用した LiveAnalytics 用 Amazon Timestream へのアクセス AWS CLI](Tools.CLI.md)。
1. 次のコマンドを実行して、Timestream CLI コマンドが更新されていることを確認します。create-batch-load-task がリストにあることを確認します。
`aws timestream-write help`
1. 「[バッチロードデータファイルの準備](batch-load-preparing-data-file.md)」の手順に沿ってデータソースを準備します。
1. 「[を使用した LiveAnalytics 用 Amazon Timestream へのアクセス AWS CLI](Tools.CLI.md)」の手順に沿ってデータベースとテーブルを作成します。
1. レポート出力用の S3 バケットを作成します。バケットは同じリージョンに存在している必要があります。バケットの詳細については、「[Amazon S3 汎用バケットの作成、設定、操作](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-buckets-s3.html)」を参照してください。
1. バッチロードタスクを作成します。手順については、「[バッチロードタスクを作成する](#batch-load-using-cli-create-task)」を参照してください。
1. タスクのステータスを確認します。手順については、「[バッチロードタスクを記述する](#batch-load-using-cli-describe-task)」を参照してください。
## バッチロードタスクを作成する
`create-batch-load-task` コマンドを使用してバッチロードタスクを作成できます。CLI を使用してバッチロードタスクを作成する場合、`cli-input-json` の JSON パラメータを使用できます。これにより、パラメータを単一の JSON フラグメントに集約できます。また、`data-model-configuration`、`data-source-configuration`、`report-configuration`、`target-database-name`、`target-table-name` などの他のいくつかのパラメータを使用して、これらの詳細を分割することもできます。
例については、「[バッチロードタスクの作成例](#batch-load-using-cli-example)」を参照してください。
## バッチロードタスクを記述する
バッチロードタスクの説明は、次のように取得できます。
```
aws timestream-write describe-batch-load-task --task-id
```
以下に、応答の例を示します。
```
{
"BatchLoadTaskDescription": {
"TaskId": "",
"DataSourceConfiguration": {
"DataSourceS3Configuration": {
"BucketName": "test-batch-load-west-2",
"ObjectKeyPrefix": "sample.csv"
},
"CsvConfiguration": {},
"DataFormat": "CSV"
},
"ProgressReport": {
"RecordsProcessed": 2,
"RecordsIngested": 0,
"FileParseFailures": 0,
"RecordIngestionFailures": 2,
"FileFailures": 0,
"BytesIngested": 119
},
"ReportConfiguration": {
"ReportS3Configuration": {
"BucketName": "test-batch-load-west-2",
"ObjectKeyPrefix": "",
"EncryptionOption": "SSE_S3"
}
},
"DataModelConfiguration": {
"DataModel": {
"TimeColumn": "timestamp",
"TimeUnit": "SECONDS",
"DimensionMappings": [
{
"SourceColumn": "vehicle",
"DestinationColumn": "vehicle"
},
{
"SourceColumn": "registration",
"DestinationColumn": "license"
}
],
"MultiMeasureMappings": {
"TargetMultiMeasureName": "test",
"MultiMeasureAttributeMappings": [
{
"SourceColumn": "wgt",
"TargetMultiMeasureAttributeName": "weight",
"MeasureValueType": "DOUBLE"
},
{
"SourceColumn": "spd",
"TargetMultiMeasureAttributeName": "speed",
"MeasureValueType": "DOUBLE"
},
{
"SourceColumn": "fuel",
"TargetMultiMeasureAttributeName": "fuel",
"MeasureValueType": "DOUBLE"
},
{
"SourceColumn": "miles",
"TargetMultiMeasureAttributeName": "miles",
"MeasureValueType": "DOUBLE"
}
]
}
}
},
"TargetDatabaseName": "BatchLoadExampleDatabase",
"TargetTableName": "BatchLoadExampleTable",
"TaskStatus": "FAILED",
"RecordVersion": 1,
"CreationTime": 1677167593.266,
"LastUpdatedTime": 1677167602.38
}
}
```
## バッチロードタスクを一覧表示する
バッチロードタスクは次のように一覧表示できます。
```
aws timestream-write list-batch-load-tasks
```
出力は次のように表示されます。
```
{
"BatchLoadTasks": [
{
"TaskId": "",
"TaskStatus": "FAILED",
"DatabaseName": "BatchLoadExampleDatabase",
"TableName": "BatchLoadExampleTable",
"CreationTime": 1677167593.266,
"LastUpdatedTime": 1677167602.38
}
]
}
```
## バッチロードタスクを再開する
バッチロードタスクは、次のように再開できます。
```
aws timestream-write resume-batch-load-task --task-id
```
レスポンスには、成功が示されるか、エラー情報が含まれることがあります。
## バッチロードタスクの作成例
**Example**
1. `BatchLoad` という名前の Timestream for LiveAnalytics データベースと、`BatchLoadTest` という名前のテーブルを作成します。確認し、必要に応じて `MemoryStoreRetentionPeriodInHours` と `MagneticStoreRetentionPeriodInDays` の値を調整します。
```
aws timestream-write create-database --database-name BatchLoad \
aws timestream-write create-table --database-name BatchLoad \
--table-name BatchLoadTest \
--retention-properties "{\"MemoryStoreRetentionPeriodInHours\": 12, \"MagneticStoreRetentionPeriodInDays\": 100}"
```
1. コンソールを使用して S3 バケットを作成し、その場所に `sample.csv` ファイルをコピーします。サンプル CSV は[サンプル CSV](samples/batch-load-sample-file.csv.zip) でダウンロードできます。
1. コンソールを使用して、Timestream for LiveAnalytics の S3 バケットを作成し、バッチロードタスクがエラーで完了した場合にレポートを書き込みます。
1. バッチロードタスクを作成します。*\$1INPUT\$1BUCKET* と *\$1REPORT\$1BUCKET* は、前のステップで作成したバケットに置き換えてください。
```
aws timestream-write create-batch-load-task \
--data-model-configuration "{\
\"DataModel\": {\
\"TimeColumn\": \"timestamp\",\
\"TimeUnit\": \"SECONDS\",\
\"DimensionMappings\": [\
{\
\"SourceColumn\": \"vehicle\"\
},\
{\
\"SourceColumn\": \"registration\",\
\"DestinationColumn\": \"license\"\
}\
],
\"MultiMeasureMappings\": {\
\"TargetMultiMeasureName\": \"mva_measure_name\",\
\"MultiMeasureAttributeMappings\": [\
{\
\"SourceColumn\": \"wgt\",\
\"TargetMultiMeasureAttributeName\": \"weight\",\
\"MeasureValueType\": \"DOUBLE\"\
},\
{\
\"SourceColumn\": \"spd\",\
\"TargetMultiMeasureAttributeName\": \"speed\",\
\"MeasureValueType\": \"DOUBLE\"\
},\
{\
\"SourceColumn\": \"fuel_consumption\",\
\"TargetMultiMeasureAttributeName\": \"fuel\",\
\"MeasureValueType\": \"DOUBLE\"\
},\
{\
\"SourceColumn\": \"miles\",\
\"MeasureValueType\": \"BIGINT\"\
}\
]\
}\
}\
}" \
--data-source-configuration "{
\"DataSourceS3Configuration\": {\
\"BucketName\": \"$INPUT_BUCKET\",\
\"ObjectKeyPrefix\": \"$INPUT_OBJECT_KEY_PREFIX\"
},\
\"DataFormat\": \"CSV\"\
}" \
--report-configuration "{\
\"ReportS3Configuration\": {\
\"BucketName\": \"$REPORT_BUCKET\",\
\"EncryptionOption\": \"SSE_S3\"\
}\
}" \
--target-database-name BatchLoad \
--target-table-name BatchLoadTest
```
上記のコマンドは、次の出力を返します。
```
{
"TaskId": "TaskId "
}
```
1. タスクの進行状況を確認します。*\$1TASK\$1ID* は、前のステップで返されたタスク ID に置き換えてください。
```
aws timestream-write describe-batch-load-task --task-id $TASK_ID
```
**出力の例**
```
{
"BatchLoadTaskDescription": {
"ProgressReport": {
"BytesIngested": 1024,
"RecordsIngested": 2,
"FileFailures": 0,
"RecordIngestionFailures": 0,
"RecordsProcessed": 2,
"FileParseFailures": 0
},
"DataModelConfiguration": {
"DataModel": {
"DimensionMappings": [
{
"SourceColumn": "vehicle",
"DestinationColumn": "vehicle"
},
{
"SourceColumn": "registration",
"DestinationColumn": "license"
}
],
"TimeUnit": "SECONDS",
"TimeColumn": "timestamp",
"MultiMeasureMappings": {
"MultiMeasureAttributeMappings": [
{
"TargetMultiMeasureAttributeName": "weight",
"SourceColumn": "wgt",
"MeasureValueType": "DOUBLE"
},
{
"TargetMultiMeasureAttributeName": "speed",
"SourceColumn": "spd",
"MeasureValueType": "DOUBLE"
},
{
"TargetMultiMeasureAttributeName": "fuel",
"SourceColumn": "fuel_consumption",
"MeasureValueType": "DOUBLE"
},
{
"TargetMultiMeasureAttributeName": "miles",
"SourceColumn": "miles",
"MeasureValueType": "DOUBLE"
}
],
"TargetMultiMeasureName": "mva_measure_name"
}
}
},
"TargetDatabaseName": "BatchLoad",
"CreationTime": 1672960381.735,
"TaskStatus": "SUCCEEDED",
"RecordVersion": 1,
"TaskId": "TaskId ",
"TargetTableName": "BatchLoadTest",
"ReportConfiguration": {
"ReportS3Configuration": {
"EncryptionOption": "SSE_S3",
"ObjectKeyPrefix": "ObjectKeyPrefix ",
"BucketName": "amzn-s3-demo-bucket"
}
},
"DataSourceConfiguration": {
"DataSourceS3Configuration": {
"ObjectKeyPrefix": "sample.csv",
"BucketName": "amzn-s3-demo-source-bucket"
},
"DataFormat": "CSV",
"CsvConfiguration": {}
},
"LastUpdatedTime": 1672960387.334
}
}
```
# AWS SDKs
AWS SDK でのバッチロードタスクの作成、記述、一覧表示の方法例については、「[バッチロードタスクを作成する](code-samples.create-batch-load.md)」「[バッチロードタスクを記述する](code-samples.describe-batch-load.md)」「[バッチロードタスクを一覧表示する](code-samples.list-batch-load-tasks.md)」「[バッチロードタスクを再開する](code-samples.resume-batch-load-task.md)」を参照してください。
# バッチロードエラーレポートの使用
バッチロードタスクには、次のいずれかのステータス値があります。
+ `CREATED` (**[作成済み]**) – タスクが作成されています。
+ `IN_PROGRESS` (**[進行中]**) – タスクが進行中です。
+ `FAILED` (**[失敗]**) – タスクは完了しましたが、1 つ以上のエラーが検出されました。
+ `SUCCEEDED` (**[完了済み]**) – タスクはエラーなしで完了しました。
+ `PROGRESS_STOPPED` (**[進行が停止しました]**) – タスクは停止しましたが、完了していません。タスクを再開できます。
+ `PENDING_RESUME` (**[保留中のレジュメ]**) – タスクは再開保留中です。
エラーが発生すると、それに対して定義された S3 バケットにエラーログレポートが作成されます。エラーは、個別の配列で taskErrors または fileErrors に分類されます。以下に、エラーレポートの例を示します。
```
{
"taskId": "9367BE28418C5EF902676482220B631C",
"taskErrors": [],
"fileErrors": [
{
"fileName": "example.csv",
"errors": [
{
"reason": "The record timestamp is outside the time range of the data ingestion window.",
"lineRanges": [
[
2,
3
]
]
}
]
}
]
}
```