本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用摄取数据 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)*中的。 要标识资产属性，请指定以下项之一： + 向其发送数据的资产属性的 `assetId` 和 `propertyId`。 + `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`是一个 timestamp-quality-value (TQV) 结构，其中包含 a `value` `timestamp`、a 和（可选）。`quality` + `value` – 包含下列字段之一的结构，具体取决于要设置的属性的类型： + `booleanValue` + `doubleValue` + `integerValue` + `stringValue` + `nullValue` + `nullValue`— 一种结构，其中的以下字段表示属性值的类型，值为 Null，质量为`BAD`或`UNCERTAIN`。 + `valueType`— \$1“B”、“D”、“S”、“I”\$1 的枚举 + `timestamp` – 包含当前 Unix 纪元时间（以秒为单位）的结构，`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 的数据。 要标识资产属性，请指定以下项之一。 您要向其发送数据的资产属性的 `ASSET_ID` 和 `PROPERTY_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` – 有符号的 32 位整数，范围是 [-2,147,483,648, 2,147,483,647]。 + `DOUBLE` – 具有 [-10^100, 10^100] 范围和 IEEE 754 双精度的浮点数。 + `BOOLEAN` – `true` 或 `false`。 + `TIMESTAMP_SECONDS` – 数据点的时间戳，以 Unix 纪元时间表示。 + `TIMESTAMP_NANO_OFFSET` – 从 `TIMESTAMP_SECONDS` 转换时的纳秒偏移量。 + `QUALITY` –（可选）资产属性值的质量。值可以是以下值之一。 + `GOOD` –（默认）数据不受任何问题的影响。 + `BAD` – 数据受传感器故障等问题的影响。 + `UNCERTAIN` – 数据受传感器不准确等问题的影响。 有关如何在计算中 AWS IoT SiteWise 处理数据质量的更多信息，请参阅[公式表达式中的数据质量](expression-tutorials.md#data-quality)。 + `VALUE` – 资产属性的值。 **Example .csv 格式的数据文件** ``` 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 替换为发送与此批量导入任务相关的错误的 Amazon S3 存储桶的*-for-errors*名称。 + 将 amzn-s3-demo-bucket 替换为发送与此批量导入任务相关的错误的 Amazon S3 存储桶*-for-errors-prefix*的前缀。 Amazon S3 使用前缀作为文件夹名称来整理存储桶中的数据。每个 Amazon S3 对象都有一个键，作为对象在存储桶中的唯一标识符。桶内的每个对象都只能有一个键。前缀必须以正斜杠（/）结尾。有关更多信息，请参阅 *Amazon Simple Storage Service 用户指南*中的[使用前缀整理对象](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-prefixes.html)。 + 将 amzn-s3-demo-bucket 替换为从中导入数据的 Amazon S3 存储桶的*-data*名称。 + *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 角色。 确保您的角色具有以下示例中显示的权限。将 amzn-s3-demo-bucket 替换为包含您的数据的 Amazon S3 存储桶的*-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" ```