本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 AWS IoT SiteWise APIs 擷取資料 使用 AWS IoT SiteWise APIs將時間戳記工業資料傳送至資產的屬性和測量屬性。APIs接受包含timestamp-quality-value(TQV) 結構的承載。 # BatchPutAssetPropertyValue API 使用 [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) 操作上傳您的資料。透過此操作，您可以一次上傳多個資料項目，以從多個裝置收集資料，並在單一請求中傳送所有資料。 **重要** [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) 操作受下列配額限制： 每個請求最多 10 個[項目](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html#API_BatchPutAssetPropertyValue_RequestSyntax)。 每個項目最多 10 個[屬性值](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_PutAssetPropertyValueEntry.html#iotsitewise-Type-PutAssetPropertyValueEntry-propertyValues) (TQV 資料點）。 AWS IoT SiteWise 拒絕時間戳記為過去 7 天以上或未來超過 10 分鐘的任何資料。 如需這些配額的詳細資訊，請參閱 *AWS IoT SiteWise API 參考*中的 [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html)。 若要識別資產屬性，請指定下列其中一項： + 資料傳送到的資產屬性`propertyId`的 `assetId`和 。 + `propertyAlias`，這是資料串流別名 （例如 `/company/windfarm/3/turbine/7/temperature`)。若要使用這個選項，您必須先設定您的資產屬性別名。若要設定屬性別名，請參閱 [管理 的資料串流 AWS IoT SiteWise](manage-data-streams.md)。 以下範例示範如何從儲存在 JSON 檔案的承載中，設定風力渦輪機的溫度和每分鐘旋轉 (RPM) 讀數。 ``` aws iotsitewise batch-put-asset-property-value --cli-input-json file://batch-put-payload.json ``` 中的範例承載`batch-put-payload.json`具有下列內容。 ``` { "enablePartialEntryProcessing": true, "entries": [ { "entryId": "unique entry ID", "propertyAlias": "/company/windfarm/3/turbine/7/temperature", "propertyValues": [ { "value": { "integerValue": 38 }, "timestamp": { "timeInSeconds": 1575691200 } } ] }, { "entryId": "unique entry ID", "propertyAlias": "/company/windfarm/3/turbine/7/rpm", "propertyValues": [ { "value": { "doubleValue": 15.09 }, "timestamp": { "timeInSeconds": 1575691200 }, "quality": "GOOD" } ] }, { "entryId": "unique entry ID", "propertyAlias": "/company/windfarm/3/turbine/7/rpm", "propertyValues": [ { "value": { "nullValue":{"valueType": "D"} }, "timestamp": { "timeInSeconds": 1575691200 }, "quality": "BAD" } ] } ] } ``` 指定 `enablePartialEntryProcessing`為 `true` 允許擷取不會導致失敗的所有值。預設行為是 `false`。如果值無效，則整個項目的擷取會失敗。 承載中的每個項目都包含 `entryId`，您可以將其定義為任何獨特的字串。如果有任何請求項目失敗，每個錯誤都會包含對應請求的 `entryId`，這樣您就可以知道要重試哪些請求。 `propertyValues` 清單中的每個結構都是時間戳記品質值 (TQV) 結構，其中包含一個 `value`、一個 `timestamp`，以及選擇性地包含一個 `quality`。 + `value` – 包含下列其中一個欄位的結構，取決於所設定屬性的類型： + `booleanValue` + `doubleValue` + `integerValue` + `stringValue` + `nullValue` + `nullValue` – 具有下列欄位的結構，表示值為 Null 且品質為 `BAD`或 的屬性值類型`UNCERTAIN`。 + `valueType` – \$1"B"、"D"、"S"、"I"\$1 的列舉 + `timestamp` – 包含目前 Unix epoch 時間的結構，以秒為單位`timeInSeconds`，。如果您有時間精確的資料，您也可以在 `timestamp`結構中設定`offsetInNanos`金鑰。 AWS IoT SiteWise 會拒絕過去 7 天或未來 10 分鐘以上時間戳記的任何資料點。 + `quality` – （選用） 下列其中一個品質字串： + `GOOD` – （預設） 資料不會受到任何問題的影響。 + `BAD` – 資料會受到感應器故障等問題的影響。 + `UNCERTAIN` – 資料受到感應器不準確等問題的影響。 如需如何在運算中 AWS IoT SiteWise 處理資料品質的詳細資訊，請參閱[公式表達式中的資料品質](expression-tutorials.md#data-quality)。 # CreateBulkImportJob API 使用 `CreateBulkImportJob` API 從 Amazon S3 匯入大量資料。您的資料必須以 CSV 格式儲存在 Amazon S3 中。資料檔案可以有下列資料欄。 **注意** 不支援早於 1970 年 1 月 1 日 00：00：00 UTC 的資料。 若要識別資產屬性，請指定下列其中一項。 您要傳送資料的資產屬性`PROPERTY_ID`的 `ASSET_ID`和 。 `ALIAS`，這是資料串流別名 （例如 `/company/windfarm/3/turbine/7/temperature`)。若要使用這個選項，您必須先設定您的資產屬性別名。若要了解如何設定屬性別名，請參閱[管理 的資料串流 AWS IoT SiteWise](manage-data-streams.md)。 + `ALIAS` – 識別 屬性的別名，例如 OPC UA 伺服器資料串流路徑 （例如 `/company/windfarm/3/turbine/7/temperature`)。如需詳細資訊，請參閱[管理 的資料串流 AWS IoT SiteWise](manage-data-streams.md)。 + `ASSET_ID` – 資產的 ID。 + `PROPERTY_ID` – 資產屬性的 ID。 + `DATA_TYPE` – 屬性的資料類型可以是下列其中一項。 + `STRING` – 最多 1024 個位元組的字串。 + `INTEGER` – 範圍為 【-2，147，483，648， 2，147，483，647】 的帶正負號 32 位元整數。 + `DOUBLE` – 範圍為 【-10^100、10^100】 和 IEEE 754 雙精度的浮點數。 + `BOOLEAN` – `true`或 `false`。 + `TIMESTAMP_SECONDS` – 資料點的時間戳記，以 Unix epoch 時間為單位。 + `TIMESTAMP_NANO_OFFSET` – 從 涵蓋的奈秒位移`TIMESTAMP_SECONDS`。 + `QUALITY` – （選用） 資產屬性值的品質。值可以是下列其中一項。 + `GOOD` – （預設） 資料不會受到任何問題的影響。 + `BAD` – 資料會受到感應器故障等問題的影響。 + `UNCERTAIN` – 資料受到感應器不準確等問題的影響。 如需如何在運算中 AWS IoT SiteWise 處理資料品質的詳細資訊，請參閱[公式表達式中的資料品質](expression-tutorials.md#data-quality)。 + `VALUE` – 資產屬性的值。 **Example .csv 格式的資料檔案 (s)** ``` asset_id,property_id,DOUBLE,1635201373,0,GOOD,1.0 asset_id,property_id,DOUBLE,1635201374,0,GOOD,2.0 asset_id,property_id,DOUBLE,1635201375,0,GOOD,3.0 ``` ``` unmodeled_alias1,DOUBLE,1635201373,0,GOOD,1.0 unmodeled_alias1,DOUBLE,1635201374,0,GOOD,2.0 unmodeled_alias1,DOUBLE,1635201375,0,GOOD,3.0 unmodeled_alias1,DOUBLE,1635201376,0,GOOD,4.0 unmodeled_alias1,DOUBLE,1635201377,0,GOOD,5.0 unmodeled_alias1,DOUBLE,1635201378,0,GOOD,6.0 unmodeled_alias1,DOUBLE,1635201379,0,GOOD,7.0 unmodeled_alias1,DOUBLE,1635201380,0,GOOD,8.0 unmodeled_alias1,DOUBLE,1635201381,0,GOOD,9.0 unmodeled_alias1,DOUBLE,1635201382,0,GOOD,10.0 ``` AWS IoT SiteWise 提供下列 API 操作來建立大量匯入任務，並取得現有任務的相關資訊。 + [CreateBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateBulkImportJob.html) – 建立新的大量匯入任務。 + [DescribeBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeBulkImportJob.html) – 擷取大量匯入任務的相關資訊。 + [ListBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListBulkImportJobs.html) – 擷取所有大量匯入任務的分頁摘要清單。 # 建立 AWS IoT SiteWise 大量匯入任務 (AWS CLI) 使用 [CreateBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateBulkImportJob.html) API 操作，將資料從 Amazon S3 傳輸到 AWS IoT SiteWise。[CreateBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateBulkImportJob.html) API 可擷取大量歷史資料，並以小批次緩衝擷取分析資料串流。它為資料擷取提供了經濟實惠的基本概念。下列為使用 AWS CLI的範例。 **重要** 在建立大量匯入任務之前，您必須啟用 AWS IoT SiteWise 暖層或 AWS IoT SiteWise 冷層。如需詳細資訊，請參閱[在 中設定儲存體設定 AWS IoT SiteWise](configure-storage.md)。 [CreateBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateBulkImportJob.html) API 支援將歷史資料擷取至 ， AWS IoT SiteWise 並可選擇設定adaptive-ingestion-flag參數。 設為 時`false`，API 會擷取歷史資料，而不會觸發運算或通知。 設為 時`true`，API 會擷取新資料、計算指標和轉換資料，以在七天內最佳化持續的分析和通知。 執行下列命令。將 *file-name* 取代為包含大量匯入任務組態的檔案名稱。 ``` aws iotsitewise create-bulk-import-job --cli-input-json file://file-name.json ``` **Example 大量匯入任務組態** 以下是組態設定的範例： + 將 *adaptive-ingestion-flag* 取代為 `true`或 `false`。 + 如果設定為 `false`，大量匯入任務會將歷史資料擷取至 AWS IoT SiteWise。 + 如果設定為 `true`，大量匯入任務會執行下列動作： + 將新資料擷取至 AWS IoT SiteWise。 + 計算指標和轉換，並支援具有七天內時間戳記的資料通知。 + 將 *delete-files-after-import-flag* 取代為 `true`，以在擷取至 AWS IoT SiteWise 暖層儲存之後從 Amazon S3 資料儲存貯體中刪除資料。 + 將 amzn-s3-demo-bucket*-for-errors* 取代為與此大量匯入任務相關聯之錯誤的 Amazon S3 儲存貯體名稱。 + 將 amzn-s3-demo-bucket*-for-errors-prefix* 取代為與此大量匯入任務相關聯的錯誤的 Amazon S3 儲存貯體字首。 Amazon S3 使用 字首做為資料夾名稱來組織儲存貯體中的資料。每個 Amazon S3 物件都有一個金鑰，其為儲存貯體中的唯一識別符。儲存貯體中的每個物件只能有一個金鑰。前綴必須以正斜線 (/) 結尾。如需詳細資訊，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用字首組織物件](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-prefixes.html)。 + 將 amzn-s3-demo-bucket*-data* 取代為匯入資料的 Amazon S3 儲存貯體名稱。 + 將 *data-bucket-key* 取代為包含您資料的 Amazon S3 物件的金鑰。每個物件都有一個唯一識別碼的金鑰。每個物件只有一個金鑰。 + 將 *data-bucket-version-id* 取代為版本 ID，以識別包含您資料的特定 Amazon S3 物件版本。此為選用參數。 + 將 *column-name* 取代為 .csv 檔案中指定的資料欄名稱。 + 將 *job-name* 取代為可識別大量匯入任務的唯一名稱。 + 將 *job-role-arn* 取代為允許 AWS IoT SiteWise 讀取 Amazon S3 資料的 IAM 角色。 請確定您的角色具有下列範例所示的許可。以包含資料的 Amazon S3 儲存貯體名稱取代 amzn-s3-demo-bucket*-*data。此外，請將 *amzn-s3-demo-bucket-for-errors* 取代為 Amazon S3 儲存貯體的名稱，此儲存貯體會傳送與此大量匯入任務相關聯的錯誤。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "s3:GetObject", "s3:GetBucketLocation" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket-data", "arn:aws:s3:::amzn-s3-demo-bucket-data/*" ], "Effect": "Allow" }, { "Action": [ "s3:PutObject", "s3:GetObject", "s3:GetBucketLocation" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket-for-errors", "arn:aws:s3:::amzn-s3-demo-bucket-for-errors/*" ], "Effect": "Allow" } ] } ``` ``` { "adaptiveIngestion": adaptive-ingestion-flag, "deleteFilesAfterImport": delete-files-after-import-flag, "errorReportLocation": { "bucket": "amzn-s3-demo-bucket-for-errors", "prefix": "amzn-s3-demo-bucket-for-errors-prefix" }, "files": [ { "bucket": "amzn-s3-demo-bucket-data", "key": "data-bucket-key", "versionId": "data-bucket-version-id" } ], "jobConfiguration": { "fileFormat": { "csv": { "columnNames": [ "column-name" ] } } }, "jobName": "job-name", "jobRoleArn": "job-role-arn" } ``` **Example 回應** ``` { "jobId":"f8c031d0-01d1-4b94-90b1-afe8bb93b7e5", "jobStatus":"PENDING", "jobName":"myBulkImportJob" } ``` # 描述 AWS IoT SiteWise 大量匯入任務 (AWS CLI) 使用 [DescribeBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeBulkImportJob.html) API 操作擷取特定大量匯入任務的相關資訊 AWS IoT SiteWise。此操作會傳回詳細資訊，例如任務的狀態、建立時間和任務失敗時的錯誤資訊。您可以使用此操作來監控任務進度和疑難排解問題。若要使用 `DescribeBulkImportJob`，您需要 `CreateBulkImportJob`操作中的任務 ID。API 會傳回下列資訊： + 正在匯入的檔案清單，包括其 Amazon S3 儲存貯體位置和金鑰 + 錯誤報告位置 （如適用） + 任務組態詳細資訊，例如檔案格式和 CSV 資料欄名稱 + 任務建立和上次更新時間戳記 + 目前的任務狀態 （例如，任務為進行中、已完成或失敗） + 用於匯入任務的 IAM 角色 ARN 對於已完成的任務，請檢閱結果以確認資料整合成功。如果任務失敗，請檢查錯誤詳細資訊以診斷和解決問題。 將 *job-ID* 取代為您要擷取的大量匯入任務 ID。 ``` aws iotsitewise describe-bulk-import-job --job-id job-ID ``` **Example 回應** ``` { "files":[ { "bucket":"amzn-s3-demo-bucket1", "key":"100Tags12Hours.csv" }, { "bucket":"amzn-s3-demo-bucket2", "key":"BulkImportData1MB.csv" }, { "bucket":" amzn-s3-demo-bucket3", "key":"UnmodeledBulkImportData1MB.csv" } ], "errorReportLocation":{ "prefix":"errors/", "bucket":"amzn-s3-demo-bucket-for-errors" }, "jobConfiguration":{ "fileFormat":{ "csv":{ "columnNames":[ "ALIAS", "DATA_TYPE", "TIMESTAMP_SECONDS", "TIMESTAMP_NANO_OFFSET", "QUALITY", "VALUE" ] } } }, "jobCreationDate":1645745176.498, "jobStatus":"COMPLETED", "jobName":"myBulkImportJob", "jobLastUpdateDate":1645745279.968, "jobRoleArn":"arn:aws:iam::123456789012:role/DemoRole", "jobId":"f8c031d0-01d1-4b94-90b1-afe8bb93b7e5" } ``` # 列出 AWS IoT SiteWise 大量匯入任務 (AWS CLI) 使用 [ListBulkImportJobs](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListBulkImportJobss.html) API 操作來擷取大量匯入任務的摘要清單 AWS IoT SiteWise。此操作提供有效的方法來監控和管理資料匯入程序。它會傳回每個任務的下列金鑰資訊： + 任務 ID。每個大量匯入任務的唯一識別符 + 任務名稱。您在建立任務時指派給任務的名稱 + 目前狀態。任務的目前狀態 （例如 COMPLETED、RUNNING、FAILED) ListBulkImportJobs 特別適用於取得所有大量匯入任務的完整概觀。這可協助您追蹤多個資料匯入、識別任何需要注意的任務，以及維護有條不紊的工作流程。操作支援分頁，可讓您有效率地擷取大量任務摘要。您可以使用此操作傳回的任務 IDs搭配 [DescribeBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeBulkImportJob.html) 操作，以擷取特定任務的詳細資訊。這個兩步驟程序可讓您先取得所有任務的高階檢視，然後深入了解感興趣的任務詳細資訊。使用 時`ListBulkImportJobs`，您可以套用篩選條件來縮小結果範圍。例如，您可以根據任務狀態篩選任務，以僅擷取已完成的任務或僅擷取執行中的任務。此功能可協助您專注於目前任務最相關的資訊。`nextToken` 如果有更多結果可用， 操作也會傳回 。您可以在後續呼叫中使用此字符來擷取下一組任務摘要，即使您有大量任務，也能反覆執行所有大量匯入任務。下列範例示範如何使用 `ListBulkImportJobs`搭配 AWS CLI 來擷取已完成任務的清單。 ``` aws iotsitewise list-bulk-import-jobs --filter COMPLETED ``` **Example 已完成任務的回應篩選條件** ``` { "jobSummaries":[ { "id":"bdbbfa52-d775-4952-b816-13ba1c7cb9da", "name":"myBulkImportJob", "status":"COMPLETED" }, { "id":"15ffc641-dbd8-40c6-9983-5cb3b0bc3e6b", "name":"myBulkImportJob2", "status":"COMPLETED" } ] } ``` 此命令示範如何使用 `ListBulkImportJobs`擷取已完成但失敗的任務清單。最大值設定為 50 個結果，而我們將下一個字符用於分頁結果。 ``` aws iotsitewise list-bulk-import-jobs --filter COMPLETED_WITH_FAILURES --max-results 50 --next-token "string" ```