终止支持通知：2026 年 10 月 7 日， Amazon 将停止对的支持。 Amazon IoT Greengrass Version 1 2026 年 10 月 7 日之后，您将无法再访问这些 Amazon IoT Greengrass V1 资源。如需了解更多信息，请访问[迁移自 Amazon IoT Greengrass Version 1](https://docs.amazonaws.cn/greengrass/v2/developerguide/migrate-from-v1.html)。 本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # IoT Analytics 连接器 **警告** 此连接器已进入*生命周期延长阶段*， Amazon IoT Greengrass 不会发布更新来提供功能、现有功能增强、安全补丁或错误修复。有关更多信息，请参阅 [Amazon IoT Greengrass Version 1 维护政策](maintenance-policy.md)。 IoT Analytics 连接器将本地设备数据发送到 Amazon IoT Analytics。您可以使用此连接器作为中央枢纽来收集 Greengrass 核心设备上的传感器以及[已连接的客户端设备](what-is-gg.md#greengrass-devices)中的数据。连接器将数据发送到当前 Amazon Web Services 账户 和区域中的 Amazon IoT Analytics 频道。它可以将数据发送到默认目标通道和动态指定的通道。 **注意** Amazon IoT Analytics 是一项完全托管的服务，允许您收集、存储、处理和查询 IoT 数据。在中 Amazon IoT Analytics，可以进一步分析和处理数据。例如，它可用于训练用于监控机器运行状况的 ML 模型或测试新的建模策略。有关更多信息，请参阅[什么是 Amazon IoT Analytics？](https://docs.amazonaws.cn/iotanalytics/latest/userguide/welcome.html) 在《*Amazon IoT Analytics 用户指南》*中。 连接器接受[输入 MQTT 主题](#iot-analytics-connector-data-input)上的格式化和非格式化数据。它支持两个预定义的主题，其中以内联方式指定目标通道。它还可以接收有关[订阅中配置的](connectors.md#connectors-inputs-outputs)客户定义的主题的消息。这可用于路由客户端设备中发布到固定主题的消息或处理资源有限的设备中的非结构化或堆栈相关的数据。 此连接器使用 [https://docs.amazonaws.cn/iotanalytics/latest/userguide/api.html#cli-iotanalytics-batchputmessage](https://docs.amazonaws.cn/iotanalytics/latest/userguide/api.html#cli-iotanalytics-batchputmessage) API 将数据（以 JSON 或 base64 编码字符串的形式）发送到目标通道。连接器可以将原始数据处理为符合 API 要求的格式。连接器将输入消息缓存在每个通道队列中并异步处理批次。它提供了可让您控制队列和批处理行为以及限制内存消耗的参数。例如，您可以配置最大队列大小、批处理间隔、内存大小和活动通道数。 此连接器具有以下版本。 | 版本 | 进行筛选 | | --- | --- | | 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` | 有关版本更改的信息，请参阅[更改日志](#iot-analytics-connector-changelog)。 ## 要求 此连接器具有以下要求： ------ #### [ Version 3 - 4 ] + Amazon IoT Greengrass 核心软件 v1.9.3 或更高版本。 + [Python](https://www.python.org/) 版本 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 IoT Greengrass](https://docs.amazonaws.cn/general/latest/gr/greengrass.html) 和 [Amazon IoT Analytics](https://docs.amazonaws.cn/general/latest/gr/iot-analytics.html) 的 Amazon Web Services 区域中使用。 + 所有相关 Amazon IoT Analytics 实体和工作流程均已创建和配置。实体包括通道、管道、数据存储和数据集。有关更多信息，请参阅《*Amazon IoT Analytics 用户指南》*中的 [Amazon CLI](https://docs.amazonaws.cn/iotanalytics/latest/userguide/getting-started.html) 或[控制台](https://docs.amazonaws.cn/iotanalytics/latest/userguide/quickstart.html)过程。 **注意** 目标 Amazon IoT Analytics 频道必须使用与该连接器相同的帐户并且位于 Amazon Web Services 区域 相同的帐户中。 + [Greengrass 组角色](group-role.md)，配置为允许对目标通道执行 `iotanalytics:BatchPutMessage` 操作，如以下示例 IAM policy 中所示。通道必须位于当前 Amazon Web Services 账户 和区域中。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "Stmt1528133056761", "Action": [ "iotanalytics:BatchPutMessage" ], "Effect": "Allow", "Resource": [ "arn:aws:iotanalytics:{{us-east-1}}:{{123456789012}}:channel/{{channel_1_name}}", "arn:aws:iotanalytics:{{us-east-1}}:{{123456789012}}:channel/{{channel_2_name}}" ] } ] } ``` ------ 对于组角色要求，您必须将角色配置为授予所需权限，并确保角色已添加到组中。有关更多信息，请参阅[管理 Greengrass 组角色（控制台）](group-role.md#manage-group-role-console)或[管理 Greengrass 组角色 (CLI)](group-role.md#manage-group-role-cli)。 ------ #### [ Versions 1 - 2 ] + Amazon IoT Greengrass 核心软件 v1.7 或更高版本。 + [Python](https://www.python.org/) 版本 2.7 已安装在核心设备上，并已添加到 PATH 环境变量中。 + 此连接器只能在同时支持 [Amazon IoT Greengrass](https://docs.amazonaws.cn/general/latest/gr/greengrass.html) 和 [Amazon IoT Analytics](https://docs.amazonaws.cn/general/latest/gr/iot-analytics.html) 的 Amazon Web Services 区域中使用。 + 所有相关 Amazon IoT Analytics 实体和工作流程均已创建和配置。实体包括通道、管道、数据存储和数据集。有关更多信息，请参阅《*Amazon IoT Analytics 用户指南》*中的 [Amazon CLI](https://docs.amazonaws.cn/iotanalytics/latest/userguide/getting-started.html) 或[控制台](https://docs.amazonaws.cn/iotanalytics/latest/userguide/quickstart.html)过程。 **注意** 目标 Amazon IoT Analytics 频道必须使用与该连接器相同的帐户并且位于 Amazon Web Services 区域 相同的帐户中。 + [Greengrass 组角色](group-role.md)，配置为允许对目标通道执行 `iotanalytics:BatchPutMessage` 操作，如以下示例 IAM policy 中所示。通道必须位于当前 Amazon Web Services 账户 和区域中。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "Stmt1528133056761", "Action": [ "iotanalytics:BatchPutMessage" ], "Effect": "Allow", "Resource": [ "arn:aws:iotanalytics:{{us-east-1}}:{{123456789012}}:channel/{{channel_1_name}}", "arn:aws:iotanalytics:{{us-east-1}}:{{123456789012}}:channel/{{channel_2_name}}" ] } ] } ``` ------ 对于组角色要求，您必须将角色配置为授予所需权限，并确保角色已添加到组中。有关更多信息，请参阅[管理 Greengrass 组角色（控制台）](group-role.md#manage-group-role-console)或[管理 Greengrass 组角色 (CLI)](group-role.md#manage-group-role-cli)。 ------ ## 参数 `MemorySize` 要分配给此连接器的内存量（以 KB 为单位）。 Amazon IoT 控制台中的显示名称：**内存大小** 必需：`true` 类型：`string` 有效模式：`^[0-9]+$` `PublishRegion` 您的 Amazon IoT Analytics 频道是在其中创建的。 Amazon Web Services 区域 使用与连接器相同的区域。 这必须还与在[组角色](#iot-analytics-connector-req)中指定的通道的区域匹配。 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` 此连接器的[容器化](connectors.md#connector-containerization)模式。默认值为`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 函数的生命周期[很长](lambda-functions.md#lambda-lifecycle)。 在 Amazon IoT Greengrass 控制台中，您可以从群组的 “连接器” 页面添加**连接器**。有关更多信息，请参阅 [Greengrass 连接器入门（控制台）](connectors-console.md)。 ## 输入数据 此连接器接受有关预定义的和客户定义的 MQTT 主题的数据。发布者可以是客户端设备、Lambda 函数或其他连接器。 预定义主题 连接器支持以下两个结构化的 MQTT 主题，这些主题允许发布者以内联方式指定通道名称。 + `iotanalytics/channels/+/messages/put` 主题上的[格式化消息](#iot-analytics-connector-data-input-json)。这些输入消息中的 IoT 数据必须格式化为 JSON 和 base64 编码字符串。 + `iotanalytics/channels/+/messages/binary/put` 主题上的非格式化消息。此主题上接收的输入消息将被视为二进制数据，并且可包含任何数据类型。 要发布到预定义主题，请将 `+` 通配符替换为通道名称。例如： ``` iotanalytics/channels/my_channel/messages/put ``` Customer-defined 话题 连接器支持 `#` 主题语法，可让其接受您在订阅中配置的任何 MQTT 主题上的输入消息。我们建议您在订阅中指定主题路径，而不是仅使用 `#` 通配符。 这些消息将发送到您为连接器指定的默认通道。 客户定义的主题上的输入消息将被视为二进制数据。它们可以使用任何消息格式，并且可以包含任何数据类型。您可以使用客户定义的主题来路由设备中发布到固定主题的消息。您还可以使用这些主题来接受无法将数据处理为要发送到连接器的格式化消息的客户端设备中的输入数据。 有关订阅和 MQTT 主题的更多信息，请参阅[输入和输出](connectors.md#connectors-inputs-outputs)。 组角色必须允许对所有目标通道执行 `iotanalytics:BatchPutMessage` 操作。有关更多信息，请参阅 [要求](#iot-analytics-connector-req)。 **主题筛选条件**：`iotanalytics/channels/+/messages/put` 使用此主题将格式化消息发送到连接器并动态指定目标通道。此主题还允许您指定在响应输出中返回的 ID。连接器验证其发送到的出站`BatchPutMessage`请求中的每封邮件的 ID 是否是唯一的。 Amazon IoT Analytics将丢弃具有重复 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 关联。 **消息属性** 无。 **主题筛选条件**：`#` 使用此主题将任何消息格式发送到默认通道。在您的客户端设备发布到固定主题或您希望将数据发送到无法将数据处理为连接器[支持的消息格式](#iot-analytics-connector-data-input-json)的客户端设备中的默认通道时，这尤其有用。 您可以在创建用于将此连接器连接到数据源的订阅中定义主题语法。我们建议您在订阅中指定主题路径，而不是仅使用 `#` 通配符。 连接器数据不会解析已发布到此输入主题的消息。所有输入消息将被视为二进制数据。在将消息发送到之前 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" } ``` 如果连接器检测到可重试的错误（如连接错误），它会在下一批次中重试发布。指数退避由 SDK 处理。 Amazon 带可重试的错误的请求将添加回通道队列，以根据 `IotAnalyticsQueueDropBehavior` 参数进行进一步发布。 ## 用法示例 使用以下概括步骤设置可用于尝试连接器的示例 Python 3.7 Lambda 函数。 **注意** 如果你使用其他 Python 运行时，你可以创建从 Py Python3.x thon 3.7 的符号链接。 [连接器入门（控制台）](connectors-console.md) 和 [连接器入门 (CLI)](connectors-cli.md) 主题包含详细步骤，说明如何配置和部署示例 Twilio 通知连接器。 1. 确保满足连接器的[要求](#iot-analytics-connector-req)。 对于组角色要求，您必须将角色配置为授予所需权限，并确保角色已添加到组中。有关更多信息，请参阅[管理 Greengrass 组角色（控制台）](group-role.md#manage-group-role-console)或[管理 Greengrass 组角色 (CLI)](group-role.md#manage-group-role-cli)。 1. 创建并发布将输入数据发送到连接器的 Lambda 函数。 将[示例代码](#iot-analytics-connector-usage-example)保存为 PY 文件。下载并解压[适用于 Python 的Amazon IoT Greengrass Core 软件开发工具包](lambda-functions.md#lambda-sdks-core)。然后，创建一个 zip 包，其中在根级别包含 PY 文件和 `greengrasssdk` 文件夹。此 zip 包是您上传到 Amazon Lambda的部署包。 创建 Python 3.7 Lambda 函数后，请发布函数版本并创建别名。 1. 配置 Greengrass 组。 1. 通过别名来添加 Lambda 函数（推荐）。将 Lambda 生命周期配置为长时间生存（或在 CLI 中设置为 `"Pinned": true`）。 1. 添加连接器并配置其[参数](#iot-analytics-connector-param)。 1. 添加允许连接器接收[输入数据](#iot-analytics-connector-data-input)并针对支持的主题筛选条件发送[输出数据](#iot-analytics-connector-data-output)的订阅。 + 将 Lambda 函数设置为源，将连接器设置为目标，并使用支持的输入主题筛选条件。 + 将连接器设置为源，将 Amazon IoT Core 设置为目标，并使用支持的输出主题筛选条件。您可以使用此订阅在 Amazon IoT 控制台中查看状态消息。 1. 部署组。 1. 在 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 ``` ## 限制 此连接器受以下限制的约束。 + 对 Amazon IoT Analytics [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/iotanalytics.html#IoTAnalytics.Client.batch_put_message](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/iotanalytics.html#IoTAnalytics.Client.batch_put_message)操作施加 适用于 Python (Boto3) 的 Amazon SDK 的所有限制。 + Amazon IoT Analytics [ BatchPutMessage](https://docs.amazonaws.cn/iotanalytics/latest/userguide/api.html#cli-iotanalytics-batchputmessage)API 施加的所有配额。有关更多信息，请参阅 Amazon IoT Analytics 中的 S [ervice Quot](https://docs.amazonaws.cn/general/latest/gr/iot-analytics.html#limits_iot_analytics) as *Amazon Web Services 一般参考*。 + 每个通道每秒 100000 条消息。 + 每个批次 100 条消息。 + 每条消息 128 KB。 此 API 使用通道名称（而不是通道 ARN），因此，不支持将数据发送到跨区域或跨账户通道。 + Amazon IoT Greengrass 核心强加的所有配额。有关更多信息，请参阅中的 Amazon IoT Greengrass 内核[服务配额*Amazon Web Services 一般参考*](https://docs.amazonaws.cn/general/latest/gr/greengrass.html#limits_greengrass)。 以下配额可能尤其适用： + 设备发送的消息的最大大小为 128 KB。 + Greengrass 核心路由器中的最大消息队列大小为 2.5 MB。 + 主题字符串的最大长度为 256 字节的 UTF-8 编码字符。 ## 许可证 IoT Analytics 连接器包括以下第三方 software/licensing： + [适用于 Python (Boto3) 的 Amazon SDK](https://pypi.org/project/boto3/)/Apache 许可证 2.0 + [botocore](https://pypi.org/project/botocore/)/Apache 许可证 2.0 + [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF 许可证 + [docutils](https://pypi.org/project/docutils/)/BSD 许可证，GNU 通用公共许可证 (GPL)，Python 软件基金会许可证，公共领域 + [jmespath](https://pypi.org/project/jmespath/)/MIT 许可证 + [s3transfer](https://pypi.org/project/s3transfer/)/Apache 许可证 2.0 + [urllib3](https://pypi.org/project/urllib3/)/MIT 许可证 该连接器在 [Greengrass Core 软件许可协议](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)下发布。 ## 更改日志 下表介绍每个版本连接器的更改。 | 版本 | 更改 | | --- | --- | | 4 | 增加用于配置连接器容器化模式的 `IsolationMode` 参数。 | | 3 | 已将 Lambda 运行时升级到 Python 3.7，这会更改运行时要求。 | | 2 | 进行了修复，以减少过多的日志记录。 | | 1 | 初始版本。 | Greengrass 组在一个时间上只能包含一个版本的连接器。有关升级连接器版本的信息，请参阅[升级连接器版本](connectors.md#upgrade-connector-versions)。 ## 另请参阅 + [使用 Greengrass 连接器与服务和协议集成](connectors.md) + [Greengrass 连接器入门（控制台）](connectors-console.md) + [Greengrass 连接器入门 (CLI)](connectors-cli.md) + [什么是 Amazon IoT Analytics？](https://docs.amazonaws.cn/iotanalytics/latest/userguide/welcome.html) 在《*Amazon IoT Analytics 用户指南》*中