如需與 Amazon Timestream for LiveAnalytics 類似的功能，請考慮使用 Amazon Timestream for InfluxDB。它提供簡化的資料擷取和單一位數毫秒查詢回應時間，以進行即時分析。[在這裡](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 管理主控台、 AWS CLI和 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 位置的資料來源到 LiveAnalytics 目標 Timestream 資料表的時間、維度和量值的批次載入映射。如需詳細資訊，請參閱[批次載入的資料模型映射](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"
}
]
}
```
------
+ LiveAnalytics 的 Timestream 透過將資料模型中提供的資訊映射至 CSV 標頭來剖析 CSV。資料必須具有代表時間戳記的資料欄、至少一個維度資料欄，以及至少一個量值資料欄。
+ 用於批次載入的 S3 儲存貯體必須位於與用於批次載入的 Timestream for LiveAnalytics 資料表相同的區域，且來自相同的帳戶。
+ 資料`timestamp`欄必須是長資料類型，代表自 Unix epoch 以來的時間。例如，時間戳記`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 定價](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 指定。檔案包含標頭。一欄代表時間戳記。至少有一個其他資料欄代表量值。
用於批次載入的 S3 儲存貯體必須與用於批次載入的 Timestream for LiveAnalytics 資料表位於相同的區域。提交批次載入任務之後，請勿從用於批次載入的 S3 儲存貯體新增或移除檔案。如需使用 S3 儲存貯體的資訊，請參閱 [Amazon S3 入門](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html)。
**注意**
由某些應用程式產生的 CSV 檔案，例如 Excel，可能包含與預期編碼衝突的位元組順序標記 (BOM)。使用 BOM 參考 CSV 檔案的 LiveAnalytics 批次載入任務的 Timestream，會在以程式設計方式處理時擲出錯誤。若要避免這種情況，您可以移除 BOM，這是不可見的字元。
例如，您可以從 Notepad\$1\$1 等應用程式儲存檔案，該應用程式可讓您指定新的編碼。您也可以使用程式設計選項來讀取第一行、從該行移除字元，以及將新值寫入檔案的第一行。
從 Excel 儲存時，有多個 CSV 選項。使用不同的 CSV 選項儲存 可能會阻止所描述的問題。但您應該檢查結果，因為編碼的變更可能會影響某些字元。
## CSV 格式參數
當您代表由格式參數保留的值時，您可以使用逸出字元。例如，如果引號字元是雙引號，若要在資料中代表雙引號，請將逸出字元放在雙引號前面。
如需建立批次載入任務時何時指定這些項目的詳細資訊，請參閱 [建立批次載入任務](batch-load-using-console.md#console_timestream.create-batch-load.using-console)。
| 參數 | 選項 |
| --- | --- |
| 資料欄分隔符號 | （逗號 ('，') \$1 管道 ('\$1') \$1 分號 ('；') \$1 Tab ('/t') \$1 空白空間 (' ')) |
| 逸出字元 | 無 |
| 引號字元 | 主控台：（雙引號 (") \$1 單引號 (')) |
| Null 值 | 空白空間 (' ') |
| 修剪空格 | 主控台：（否 \$1 是） |
# 批次載入的資料模型映射
以下討論資料模型映射的結構描述，並提供 和 範例。
## 資料模型映射結構描述
`CreateBatchLoadTask` 請求語法和呼叫傳回的`BatchLoadTaskDescription`物件，以`DescribeBatchLoadTask`包含包含`DataModel`用於批次載入的 `DataModelConfiguration` 物件。`DataModel` 定義從以 CSV 格式存放在 S3 位置的來源資料映射到 LiveAnalytics 資料庫和資料表的目標 Timestream。
`TimeColumn` 欄位指出要映射至 Timestream for LiveAnalytics 中目的地資料表資料`time`欄的來源資料位置。`TimeUnit` 指定 的單位`TimeColumn`，並且可以是 `MILLISECONDS`、`MICROSECONDS`、 `SECONDS`或 之一`NANOSECONDS`。還有維度和量值的映射。維度映射由來源資料欄和目標欄位組成。
如需詳細資訊，請參閱 [DimensionMapping](https://docs.aws.amazon.com/timestream/latest/developerguide/API_DimensionMapping)。量值的映射有兩個選項： `MixedMeasureMappings`和 `MultiMeasureMappings`。
總而言之， `DataModel`包含下列項目從 S3 位置的資料來源映射至目標 Timestream for LiveAnalytics 資料表。
+ 時間
+ 維度
+ 量值
如果可能，我們建議您將測量資料映射到 Timestream for LiveAnalytics 中的多測量記錄。如需多度量記錄優點的資訊，請參閱 [多度量記錄](writes.md#writes.writing-data-multi-measure)。
如果來源資料中的多個量值存放在一個資料列中，您可以使用 將這些多個量值映射到 Timestream for LiveAnalytics 中的多量值記錄`MultiMeasureMappings`。如果有必須映射至單一度量記錄的值，您可以使用 `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` `MULTI`是指定 的 `MixedMeasureMapping`，則該 `MultiMeasureAttributeMappings`需要 `MixedMeasureMapping`。否則， 會`MeasureValueType`指出單一度量記錄的度量類型。
無論哪種方式，都有可用的 陣列`MultiMeasureAttributeMapping`。您可以在每個 中定義多度量記錄的映射`MultiMeasureAttributeMapping`，如下所示：
`SourceColumn`
位於 Amazon S3 的來源資料中的資料欄。
`TargetMultiMeasureAttributeName`
目的地資料表中目標多度量名稱的名稱。`MeasureNameColumn` 未提供 時，需要此輸入。如果`MeasureNameColumn`提供 ，該資料欄的值會用作多度量名稱。
`MeasureValueType`
`DOUBLE`、`VARCHAR`、 `BIGINT` `BOOLEAN`或 之一`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`、`VARCHAR`、 `BOOLEAN`或 之一`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/zh_tw/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 儲存貯體中的一或多個 CSV 檔案 （一或多個） 映射至 Timestream for LiveAnalytics 資料表中的目的地資料欄。
**注意**
您的角色將需要 檔案的 `SelectObjectContent` 許可。如果沒有這樣做，您將需要手動新增和刪除資料欄。
### 自動載入來源資料欄模式
如果您只指定一個儲存貯體，LiveAnalytics 的 Timestream 可以自動掃描來源 CSV 檔案的資料欄名稱。當沒有現有映射時，您可以選擇**匯入來源資料欄**。
1. 使用從**映射組態輸入設定**中選取的**視覺化建置器**選項，設定時間戳記時間輸入。 `Milliseconds`是預設設定。
1. 按一下**載入來源資料欄**按鈕，匯入來源資料檔案中找到的資料欄標頭。資料表會填入資料來源檔案中的來源資料欄標頭名稱。
1. 選擇每個來源**資料欄的目標資料表資料欄名稱**、**Timestream 屬性類型**和**資料類型**。
如需這些資料欄和可能值的詳細資訊，請參閱 [映射欄位](#batch-load-using-visual-builder-mapping-fields)。
1. 使用drag-to-fill功能一次設定多個資料欄的值。
### 手動新增來源資料欄
如果您使用的是儲存貯體或 CSV 字首，而不是單一 CSV，則可以使用新增資料欄映射和刪除資料欄映射按鈕，從視覺化編輯器新增和刪除**資料欄**映射。 ****還有一個按鈕可重設映射。
### 映射欄位
+ **來源資料欄名稱** – 來源檔案中代表要匯入量值的資料欄名稱。使用**匯入來源資料欄**時，LiveAnalytics 的 Timestream 可以自動填入此值。
+ **目標資料表資料欄名稱** – 選擇性輸入，指出目標資料表中量值的資料欄名稱。
+ **Timestream 屬性類型** – 指定來源欄中資料的屬性類型，例如 `DIMENSION`。
+ **TIMESTAMP** – 指定收集量值的時間。
+ **MULTI** – 表示多個量值。
+ **DIMENSION** – 時間序列中繼資料。
+ **MEAsure\$1NAME** – 對於單一度量記錄，這是度量名稱。
+ **資料類型** – Timestream 資料欄的類型，例如 `BOOLEAN`。
+ **BIGINT** – 64 位元整數。
+ **BOOLEAN** – 邏輯的兩個事實值：true 和 false。
+ **DOUBLE** – 64 位元變數精確度數字。
+ **TIMESTAMP** – 以 UTC 為單位使用奈秒精確度時間，並追蹤 Unix epoch 以來時間的執行個體。
# 搭配 使用批次載入 AWS CLI
**設定**
若要開始使用批次載入，請執行下列步驟。
1. AWS CLI 使用 中的指示安裝 [使用 存取 Amazon Timestream for LiveAnalytics AWS CLI](Tools.CLI.md)。
1. 執行下列命令，以確認 Timestream CLI 命令已更新。驗證 create-batch-load-task 是否在清單中。
`aws timestream-write help`
1. 使用 中的指示準備資料來源[準備批次載入資料檔案](batch-load-preparing-data-file.md)。
1. 使用 中的指示建立資料庫和資料表[使用 存取 Amazon Timestream for LiveAnalytics 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 建立批次載入任務時，您可以使用 JSON 參數 `cli-input-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. 建立名為 的 LiveAnalytics 資料庫 Timestream `BatchLoad`和名為 的資料表`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 使用批次載入
如需如何使用 SDKs 建立、描述和列出批次載入任務 AWS 的範例，請參閱 [建立批次載入任務](code-samples.create-batch-load.md)、[列出批次載入任務](code-samples.list-batch-load-tasks.md)、 [描述批次載入任務](code-samples.describe-batch-load.md)和 [繼續批次載入任務](code-samples.resume-batch-load-task.md)。
# 使用批次載入錯誤報告
批次載入任務具有下列其中一個狀態值：
+ `CREATED` (**已建立**) – 任務已建立。
+ `IN_PROGRESS` (**進行中**) – 任務正在進行中。
+ `FAILED` (**失敗**) – 任務已完成。但偵測到一或多個錯誤。
+ `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
]
]
}
]
}
]
}
```