Amazon IoT Greengrass Version 1 2023 年 6 月 30 日进入延长寿命阶段。有关更多信息，请参阅 Amazon IoT Greengrass V1 维护策略。在此日期之后，将 Amazon IoT Greengrass V1 不会发布提供功能、增强功能、错误修复或安全补丁的更新。在上面运行的设备 Amazon IoT Greengrass V1 不会中断，将继续运行并连接到云端。我们强烈建议您迁移到 Amazon IoT Greengrass Version 2，这样可以添加重要的新功能并支持其他平台。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
IoT Analytics 连接器
警告
此连接器已进入生命周期延长阶段，Amazon IoT Greengrass 不会发布更新来提供功能、现有功能增强、安全补丁或错误修复。有关更多信息，请参阅Amazon IoT Greengrass Version 1 维护策略。
IoT Analytics 连接器将本地设备数据发送到 Amazon IoT Analytics。您可以使用此连接器作为中央枢纽来收集 Greengrass 核心设备上的传感器以及已连接的客户端设备中的数据。连接器将数据发送到当前 Amazon Web Services 账户 和区域中的 Amazon IoT Analytics 通道。它可以将数据发送到默认目标通道和动态指定的通道。
注意
Amazon IoT Analytics 是一项完全托管的服务，可让您收集、存储、处理和查询 IoT 数据。在 Amazon IoT Analytics 中，可以进一步分析和处理该类数据。例如，它可用于训练用于监控机器运行状况的 ML 模型或测试新的建模策略。有关更多信息，请参阅《Amazon IoT Analytics 用户指南》中的什么是 Amazon IoT Analytics？。
连接器接受输入 MQTT 主题上的格式化和非格式化数据。它支持两个预定义的主题，其中以内联方式指定目标通道。它还可以接收有关订阅中配置的客户定义的主题的消息。这可用于路由客户端设备中发布到固定主题的消息或处理资源有限的设备中的非结构化或堆栈相关的数据。
此连接器使用 BatchPutMessage API 将数据（以 JSON 或 base64 编码字符串的形式）发送到目标通道。连接器可以将原始数据处理为符合 API 要求的格式。连接器将输入消息缓存在每个通道队列中并异步处理批次。它提供了可让您控制队列和批处理行为以及限制内存消耗的参数。例如，您可以配置最大队列大小、批处理间隔、内存大小和活动通道数。
此连接器具有以下版本。
版本 |
ARN |
|---|---|
4 |
|
3 |
|
2 |
|
1 |
|
有关版本更改的信息，请参阅更改日志。
要求
此连接器具有以下要求：
参数
MemorySize-
要分配给此连接器的内存量（以 KB 为单位）。
Amazon IoT 控制台中的显示名称：内存大小
必需：
true类型：
string有效模式：
^[0-9]+$ PublishRegion-
在其中创建 Amazon IoT Analytics 通道的 Amazon Web Services 区域。使用与连接器相同的区域。
注意
这必须还与在组角色中指定的通道的区域匹配。
Amazon IoT 控制台中的显示名称：发布区域
必需：
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_NEWEST或DROP_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有效值：
GreengrassContainer或NoContainer有效模式：
^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 主题的数据。发布者可以是客户端设备、Lambda 函数或其他连接器。
- 预定义主题
-
连接器支持以下两个结构化的 MQTT 主题，这些主题允许发布者以内联方式指定通道名称。
-
iotanalytics/channels/+/messages/put主题上的格式化消息。这些输入消息中的 IoT 数据必须格式化为 JSON 和 base64 编码字符串。 -
iotanalytics/channels/+/messages/binary/put主题上的非格式化消息。此主题上接收的输入消息将被视为二进制数据，并且可包含任何数据类型。要发布到预定义主题，请将
+通配符替换为通道名称。例如：iotanalytics/channels/my_channel/messages/put
-
- 客户定义的主题
-
连接器支持
#主题语法，可让其接受您在订阅中配置的任何 MQTT 主题上的输入消息。我们建议您在订阅中指定主题路径，而不是仅使用#通配符。 这些消息将发送到您为连接器指定的默认通道。客户定义的主题上的输入消息将被视为二进制数据。它们可以使用任何消息格式，并且可以包含任何数据类型。您可以使用客户定义的主题来路由设备中发布到固定主题的消息。您还可以使用这些主题来接受无法将数据处理为要发送到连接器的格式化消息的客户端设备中的输入数据。
有关订阅和 MQTT 主题的更多信息，请参阅输入和输出。
组角色必须允许对所有目标通道执行 iotanalytics:BatchPutMessage 操作。有关更多信息，请参阅要求。
- 主题筛选条件：
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 之前，连接器会对其进行编码和格式化以符合
BatchPutMessageAPI 要求：连接器对原始数据进行 base64 编码并将已编码的负载包含在出站
BatchPutMessage请求中。连接器为每个输入消息生成并分配一个 ID。
注意
连接器的响应输出不包含这些输入消息的 ID 关联。
- 消息属性
-
无。
- 主题筛选条件：
# -
使用此主题将任何消息格式发送到默认通道。在您的客户端设备发布到固定主题或您希望将数据发送到无法将数据处理为连接器支持的消息格式的客户端设备中的默认通道时，这尤其有用。
您可以在创建用于将此连接器连接到数据源的订阅中定义主题语法。我们建议您在订阅中指定主题路径，而不是仅使用
#通配符。连接器数据不会解析已发布到此输入主题的消息。所有输入消息将被视为二进制数据。在将消息发送到 Amazon IoT Analytics 之前，连接器会对其进行编码和格式化以符合
BatchPutMessageAPI 要求：连接器对原始数据进行 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 函数。
注意
-
如果要使用其他 Python 运行时，您可以创建从 Python3.x 到 Python 3.7 的符号链接。
-
连接器入门（控制台） 和 连接器入门 (CLI) 主题包含详细步骤，说明如何配置和部署示例 Twilio 通知连接器。
确保满足连接器的要求。
对于组角色要求，您必须将角色配置为授予所需权限，并确保角色已添加到组中。有关更多信息，请参阅管理 Greengrass 组角色（控制台）或管理 Greengrass 组角色 (CLI)。
-
创建并发布将输入数据发送到连接器的 Lambda 函数。
将示例代码保存为 PY 文件。下载并解压适用于 Python 的 Amazon IoT Greengrass Core 软件开发工具包。然后，创建一个 zip 包，其中在根级别包含 PY 文件和
greengrasssdk文件夹。此 zip 包是您上传到 Amazon Lambda 的部署包。创建 Python 3.7 Lambda 函数后，请发布函数版本并创建别名。
-
配置 Greengrass 组。
-
部署组。
-
在 Amazon IoT 控制台中的测试页面上，订阅输出数据主题以查看连接器中的状态消息。示例 Lambda 函数是长时间生存的，并且在部署组后立即开始发送消息。
完成测试后，您可以将 Lambda 生命周期设置为按需（或在 CLI 中设置为
"Pinned": false）并部署组。这会阻止函数发送消息。
示例
以下示例 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_message操作施加的所有限值。 由 Amazon IoT Analytics BatchPutMessage API 施加的所有配额。有关更多信息，Amazon IoT Analytics 请参阅 Amazon Web Services 一般参考 中的服务限额。
每个通道每秒 100000 条消息。
每个批次 100 条消息。
每条消息 128 KB。
此 API 使用通道名称（而不是通道 ARN），因此，不支持将数据发送到跨区域或跨账户通道。
由 Amazon IoT Greengrass 核心施加的所有配额。有关更多信息，请参阅 Amazon Web Services 一般参考 中的适用于 Amazon IoT Greengrass 核心的服务限额。
以下配额可能尤其适用：
设备发送的消息的最大大小为 128 KB。
Greengrass 核心路由器中的最大消息队列大小为 2.5 MB。
主题字符串的最大长度为 256 字节的 UTF-8 编码的字符。
许可证
IoT Analytics 连接器包含以下第三方软件/许可：
-
Amazon SDK for Python (Boto3)
/Apache 许可证 2.0 -
botocore
/Apache 许可证 2.0 -
dateutil
/PSF 许可证 -
docutils
/BSD 许可证，GNU 通用公共许可证 (GPL)，Python 软件基金会许可证，公共领域 -
jmespath
/MIT 许可证 -
s3transfer
/Apache 许可证 2.0 -
urllib3
/MIT 许可证
此连接器在 Greengrass Core 软件许可协议
更改日志
下表介绍每个版本连接器的更改。
版本 |
更改 |
|---|---|
4 |
增加用于配置连接器容器化模式的 |
3 |
已将 Lambda 运行时升级到 Python 3.7，这会更改运行时要求。 |
2 |
进行了修复，以减少过多的日志记录。 |
1 |
首次发布。 |
Greengrass 组在一个时间上只能包含一个版本的连接器。有关升级连接器版本的信息，请参阅升级连接器版本。
另请参阅
-
Amazon IoT Analytics 用户指南 中的什么是 Amazon IoT Analytics？