IoT Analytics 接口 - Amazon IoT Greengrass
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

您正在查看Amazon IoT Greengrass Version 1.Amazon IoT Greengrass Version 2是最新的主要版本Amazon IoT Greengrass. 有关使用Amazon IoT Greengrass V2,请参阅Amazon IoT Greengrass Version 2开发人员指南.

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

IoT Analytics 接口

IoT Analytics 连接器将本地设备数据发送到Amazon IoT Analytics. 您可以使用此连接器作为中央枢纽来收集 Greengrass 核心设备上的传感器以及已连接的 Greengrass 设备中的数据。连接器将数据发送到Amazon IoT Analytics通道在当前 Amazon Web Services 账户 和区域. 它可以将数据发送到默认目标通道和动态指定的通道。

注意

Amazon IoT Analytics 是一项完全托管的服务,可让您收集、存储、处理和查询 IoT 数据。在 Amazon IoT Analytics 中,可以进一步分析和处理该类数据。例如,它可用于训练用于监控机器运行状况的 ML 模型或测试新的建模策略。有关更多信息,请参阅 Amazon IoT Analytics 用户指南 中的什么是 Amazon IoT Analytics?

连接器接受输入 MQTT 主题上的格式化和非格式化数据。它支持两个预定义的主题,其中以内联方式指定目标通道。它还可以接收有关订阅中配置的客户定义的主题的消息。这可用于路由设备中发布到固定主题的消息或处理资源有限的设备中的非结构化或堆栈相关的数据。

此连接器使用 BatchPutMessage API 将数据(以 JSON 或 base64 编码字符串的形式)发送到目标通道。连接器可以将原始数据处理为符合 API 要求的格式。连接器将输入消息缓存在每个通道队列中并异步处理批次。它提供了可让您控制队列和批处理行为以及限制内存消耗的参数。例如,您可以配置最大队列大小、批处理间隔、内存大小和活动通道数。

此连接器具有以下版本。

Version

ARN

4

arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/4

3

arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/3

2

arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/2

1

arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/1

有关版本更改的信息,请参阅更改日志

Requirements

此连接器具有以下要求:

Version 3 - 4
  • Amazon IoT Greengrass Core 软件 v1.9.3 版或更高版本。

  • Python版本 3.7 或 3.8 安装在核心设备上并添加到 PATH 环境变量中。

    注意

    要使用 Python 3.8,请运行以下命令以创建从默认 Python 3.7 安装文件夹到已安装的 Python 3.8 二进制文件的符号链接。

    sudo ln -s path-to-python-3.8/python3.8 /usr/bin/python3.7

    这会将设备配置为满足 Amazon IoT Greengrass 的 Python 要求。

  • 此连接器只能在 Amazon Web Services 区域中使用。Amazon IoT GreengrassAmazon IoT Analytics支持。

  • 创建和配置所有相关的 Amazon IoT Analytics 实体和工作流程。实体包括通道、管道、数据存储和数据集。有关更多信息,请参阅 。Amazon CLI或者控制台过程中的过程Amazon IoT Analytics用户指南.

    注意

    目的地Amazon IoT Analytics通道必须使用相同的帐户并位于 Amazon Web Services 区域 作为此连接器。

  • 这些区域有:Greengrass 组角色配置为允许iotanalytics:BatchPutMessage操作,如以下示例 IAM 策略中所示。通道必须位于当前 Amazon Web Services 账户 和区域.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1528133056761", "Action": [ "iotanalytics:BatchPutMessage" ], "Effect": "Allow", "Resource": [ "arn:aws:iotanalytics:region:account-id:channel/channel_1_name", "arn:aws:iotanalytics:region:account-id:channel/channel_2_name" ] } ] }

    对于组角色要求,您必须将角色配置为授予所需权限,并确保角色已添加到组中。有关更多信息,请参阅 管理 Greengrass 组角色(控制台)管理 Greengrass 组角色 (CLI)

Versions 1 - 2
  • Amazon IoT Greengrass核心软件版本 v1.7 或更高版本。

  • Python安装在核心设备上并添加到 PATH 环境变量中。

  • 此连接器只能在 Amazon Web Services 区域中使用。Amazon IoT GreengrassAmazon IoT Analytics支持。

  • 创建和配置所有相关的 Amazon IoT Analytics 实体和工作流程。实体包括通道、管道、数据存储和数据集。有关更多信息,请参阅 。Amazon CLI或者控制台过程中的过程Amazon IoT Analytics用户指南.

    注意

    目的地Amazon IoT Analytics通道必须使用相同的帐户并位于 Amazon Web Services 区域 作为此连接器。

  • 这些区域有:Greengrass 组角色配置为允许iotanalytics:BatchPutMessage操作,如以下示例 IAM 策略中所示。通道必须位于当前 Amazon Web Services 账户 和区域.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1528133056761", "Action": [ "iotanalytics:BatchPutMessage" ], "Effect": "Allow", "Resource": [ "arn:aws:iotanalytics:region:account-id:channel/channel_1_name", "arn:aws:iotanalytics:region:account-id:channel/channel_2_name" ] } ] }

    对于组角色要求,您必须将角色配置为授予所需权限,并确保角色已添加到组中。有关更多信息,请参阅 管理 Greengrass 组角色(控制台)管理 Greengrass 组角色 (CLI)

Parameters

MemorySize

要分配给此连接器的内存量(以 KB 为单位)。

显示名称Amazon IoT控制台:内存大小

:必需true

类型:string

有效模式:^[0-9]+$

PublishRegion

这些区域有: Amazon Web Services 区域 您的Amazon IoT Analytics通道创建。使用与连接器相同的区域。

注意

这必须还与在组角色中指定的通道的区域匹配。

显示名称Amazon IoT控制台:Publish 区域

:必需false

类型:string

有效模式:^$|([a-z]{2}-[a-z]+-\\d{1})

PublishInterval

将一批收到的数据发布到 Amazon IoT Analytics 的时间间隔(以秒为单位)。

显示名称Amazon IoT控制台:发布间隔

:必需false

类型:string

默认值:1

有效模式:$|^[0-9]+$

IotAnalyticsMaxActiveChannels

连接器主动监控的 Amazon IoT Analytics 通道的最大数量。此值必须大于 0,并且至少等于您希望在某个指定时间发布到连接器的通道的数量。

您可以使用此参数通过限制连接器可在某个给定时间管理的队列总数来限制内存消耗量。在发送所有排队的消息后,队列将被删除。

显示名称Amazon IoT控制台:最大活动通道数

:必需false

类型:string

默认值:50

有效模式:^$|^[1-9][0-9]*$

IotAnalyticsQueueDropBehavior

当队列已满时从通道队列中丢弃消息的行为。

显示名称Amazon IoT控制台:队列丢弃行为

:必需false

类型:string

有效值:DROP_NEWESTDROP_OLDEST

默认值:DROP_NEWEST

有效模式:^DROP_NEWEST$|^DROP_OLDEST$

IotAnalyticsQueueSizePerChannel

在提交或丢弃消息前要在内存(每个通道)中保留的消息的最大数量。此值必须大于 0。

显示名称Amazon IoT控制台:每个通道的最大队列大小

:必需false

类型:string

默认值:2048

有效模式:^$|^[1-9][0-9]*$

IotAnalyticsBatchSizePerChannel

要在一个批处理请求中发送到 Amazon IoT Analytics 通道的消息的最大数量。此值必须大于 0。

显示名称Amazon IoT控制台:每个通道中要批处理的消息的最大数目

:必需false

类型:string

默认值:5

有效模式:^$|^[1-9][0-9]*$

IotAnalyticsDefaultChannelName

此连接器用于已发送到客户定义的输入主题的 Amazon IoT Analytics 通道的名称。

显示名称Amazon IoT控制台:默认通道名称

:必需false

类型:string

有效模式:^[a-zA-Z0-9_]$

IsolationMode

此连接器的容器化模式。默认值为 GreengrassContainer,这意味着连接器在 Amazon IoT Greengrass 容器内的隔离运行时环境中运行。

注意

组的默认容器化设置不适用于连接器。

显示名称Amazon IoT控制台:容器隔离模式

:必需false

类型:string

有效值:GreengrassContainerNoContainer

有效模式:^NoContainer$|^GreengrassContainer$

创建连接器示例 (Amazon CLI)

以下 CLI 命令将创建的ConnectorDefinition,其初始版本包含 IoT Analytics 连接器。

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyIoTAnalyticsApplication", "ConnectorArn": "arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/3", "Parameters": { "MemorySize": "65535", "PublishRegion": "us-west-1", "PublishInterval": "2", "IotAnalyticsMaxActiveChannels": "25", "IotAnalyticsQueueDropBehavior": "DROP_OLDEST", "IotAnalyticsQueueSizePerChannel": "1028", "IotAnalyticsBatchSizePerChannel": "5", "IotAnalyticsDefaultChannelName": "my_channel" } } ] }'
注意

此连接器中的 Lambda 函数具有长时间生存的生命周期。

在Amazon IoT Greengrass控制台中添加连接器,您可以从组的连接器页. 有关更多信息,请参阅Greengrass 连接器入门(控制台)

输入数据

此连接器接受有关预定义的和客户定义的 MQTT 主题的数据。发布者可以是 Greengrass 设备、Lambda 函数或其他连接器。

预定义主题

连接器支持以下两个结构化的 MQTT 主题,这些主题允许发布者以内联方式指定通道名称。

  • A格式消息上的iotanalytics/channels/+/messages/put主题。这些输入消息中的 IoT 数据必须格式化为 JSON 和 base64 编码字符串。

  • iotanalytics/channels/+/messages/binary/put 主题上的非格式化消息。此主题上接收的输入消息将被视为二进制数据,并且可包含任何数据类型。

    要发布到预定义主题,请将 + 通配符替换为通道名称。例如:

    iotanalytics/channels/my_channel/messages/put
客户定义的主题

连接器支持 # 主题语法,可让其接受您在订阅中配置的任何 MQTT 主题上的输入消息。我们建议您指定主题路径,而不仅使用#通配符。这些消息将发送到您为连接器指定的默认通道。

客户定义的主题上的输入消息将被视为二进制数据。它们可以使用任何消息格式,并且可以包含任何数据类型。您可以使用客户定义的主题来路由设备中发布到固定主题的消息。您还可以使用这些主题来接受无法将数据处理为要发送到连接器的格式化消息的设备中的输入数据。

有关订阅和 MQTT 主题的更多信息,请参阅输入和输出

组角色必须允许对所有目标通道执行 iotanalytics:BatchPutMessage 操作。有关更多信息,请参阅Requirements

主题筛选条件:iotanalytics/channels/+/messages/put

使用此主题将格式化消息发送到连接器并动态指定目标通道。此主题还允许您指定在响应输出中返回的 ID。连接器验证 ID 对于其发送到 Amazon IoT Analytics 的出站 BatchPutMessage 请求中的每个消息是否是唯一的。将丢弃具有重复 ID 的消息。

发送到此主题的输入数据必须使用以下消息格式。

消息属性
request

要发送到指定通道的数据。

:必需true

类型:object,包含以下属性的:

message

采用 JSON 或 base64 编码字符串形式的设备或传感器数据。

:必需true

类型:string

id

请求的任意 ID。此属性用于将输入请求映射到输出响应。如果指定,响应对象中的 id 属性将设置为该值。如果您忽略此属性,则连接器将生成一个 ID。

:必需false

类型:string

有效模式:.*

示例输入
{ "request": { "message" : "{\"temp\":23.33}" }, "id" : "req123" }
主题筛选条件:iotanalytics/channels/+/messages/binary/put

使用此主题将未格式化的消息发送到连接器并动态指定目标通道。

连接器数据不会解析在此主题上收到的输入消息。它会将这些消息视为二进制数据。在将消息发送到 Amazon IoT Analytics 之前,连接器会对其进行编码和格式化以符合 BatchPutMessage API 要求:

  • 连接器对原始数据进行 base64 编码并将已编码的负载包含在出站 BatchPutMessage 请求中。

  • 连接器为每个输入消息生成并分配一个 ID。

    注意

    连接器的响应输出不包含这些输入消息的 ID 关联。

消息属性

无。

主题筛选条件:#

使用此主题将任何消息格式发送到默认通道。在您的设备发布到固定主题或您希望将数据发送到无法将数据处理为连接器支持的消息格式的设备中的默认通道时,这尤其有用。

您可以在创建用于将此连接器连接到数据源的订阅中定义主题语法。我们建议您指定主题路径,而不仅使用#通配符。

连接器数据不会解析已发布到此输入主题的消息。所有输入消息将被视为二进制数据。在将消息发送到 Amazon IoT Analytics 之前,连接器会对其进行编码和格式化以符合 BatchPutMessage API 要求:

  • 连接器对原始数据进行 base64 编码并将已编码的负载包含在出站 BatchPutMessage 请求中。

  • 连接器为每个输入消息生成并分配一个 ID。

    注意

    连接器的响应输出不包含这些输入消息的 ID 关联。

消息属性

无。

输出数据

此连接器将状态信息发布为 MQTT 主题的输出数据。此信息包含Amazon IoT Analytics接收并发送到的每个输入消息Amazon IoT Analytics.

订阅中的主题筛选条件

iotanalytics/messages/put/status

输出示例:成功
{ "response" : { "status" : "success" }, "id" : "req123" }
输出示例:失败
{ "response" : { "status" : "fail", "error" : "ResourceNotFoundException", "error_message" : "A resource with the specified name could not be found." }, "id" : "req123" }
注意

如果连接器检测到可重试的错误(例如,连接错误),它会在下一批处理中重试发布。指数回退由Amazon软件开发工具包。带可重试的错误的请求将添加回通道队列,以根据 IotAnalyticsQueueDropBehavior 参数进行进一步发布。

使用示例

使用以下概括步骤设置可用于尝试连接器的示例 Python 3.7 Lambda 函数。

注意
  1. 确保满足连接器的要求

    对于组角色要求,您必须将角色配置为授予所需权限,并确保角色已添加到组中。有关更多信息,请参阅 管理 Greengrass 组角色(控制台)管理 Greengrass 组角色 (CLI)

  2. 创建并发布将输入数据发送到连接器的 Lambda 函数。

    示例代码保存为 PY 文件。下载并解压缩Amazon IoT Greengrass适用于 Python 的核心 SDK. 然后,创建一个 zip 包,其中在根级别包含 PY 文件和 greengrasssdk 文件夹。此 zip 包是您上传到的部署包Amazon Lambda.

    创建 Python 3.7 Lambda 函数后,发布函数版本并创建别名。

  3. 配置 Greengrass 组。

    1. 通过函数的别名添加 Lambda(推荐)。将 Lambda 生命周期配置为长时间生存(或"Pinned": true)。

    2. 添加连接器并配置其参数

    3. 添加允许连接器接收输入数据并针对支持的主题筛选条件发送输出数据的订阅。

      • 将 Lambda 函数设置为源,将连接器设置为目标,并使用支持的输入主题筛选条件。

      • 将连接器设置为源,将 Amazon IoT Core 设置为目标,并使用支持的输出主题筛选条件。您可以使用此订阅查看中的状态消息。Amazon IoT控制台。

  4. 部署组。

  5. 在Amazon IoT控制台、测试页面上,订阅输出数据主题以查看连接器中的状态消息。示例 Lambda 函数是长时间生存的,并且在部署组后立即开始发送消息。

    完成测试后,您可以将 Lambda 生命周期设置为按需(或"Pinned": false)并部署组。这会阻止函数发送消息。

Example

以下示例 Lambda 函数将输入消息发送到连接器。

import greengrasssdk import time import json iot_client = greengrasssdk.client('iot-data') send_topic = 'iotanalytics/channels/my_channel/messages/put' def create_request_with_all_fields(): return { "request": { "message" : "{\"temp\":23.33}" }, "id" : "req_123" } def publish_basic_message(): messageToPublish = create_request_with_all_fields() print("Message To Publish: ", messageToPublish) iot_client.publish(topic=send_topic, payload=json.dumps(messageToPublish)) publish_basic_message() def lambda_handler(event, context): return

Limits

此连接器受以下限制的约束。

  • 由Amazon SDK for Python (Boto3)(对于 )Amazon IoT Analytics batch_put_messageaction.

  • 由 Amazon IoT Analytics BatchPutMessage API 施加的所有配额。有关更多信息,请参阅 。Service Quotas对于 来说为Amazon IoT Analytics中的Amazon一般参考.

    • 每个通道每秒 100000 条消息。

    • 每个批次 100 条消息。

    • 每条消息 128 KB。

    此 API 使用通道名称(而不是通道 ARN),因此,不支持将数据发送到跨区域或跨账户通道。

  • 由 Amazon IoT Greengrass 核心施加的所有配额。有关更多信息,请参阅 。Service Quotas(对于 )Amazon IoT Greengrass核心Amazon一般参考.

    以下配额可能尤其适用:

    • 设备发送的消息的最大大小为 128 KB。

    • Greengrass 核心路由器中的最大消息队列大小为 2.5 MB。

    • 主题字符串的最大长度为 256 字节的 UTF-8 编码的字符。

Licenses

IoT Analytics 连接器包含以下第三方软件/许可:

此连接器在Greengrass 核心软件许可协议.

Changelog

下表介绍每一版的连接器中的更改。

Version

更改

4

添加了IsolationMode参数配置连接器容器化模式。

3

已将 Lambda 运行时升级到 Python 3.7,这会更改运行时要求。

2

进行了修复,以减少过多的日志记录。

1

首次发布。

Greengrass 组每次只能包含一个连接器版本。有关升级连接器版本的信息,请参阅升级连接器版本

另请参阅