Greengrass 连接器入门 (CLI) - AWS IoT Greengrass

AWS IoT Greengrass Version 1 2023 年 6 月 30 日进入延长寿命阶段。有关更多信息,请参阅 AWS IoT Greengrass V1 维护策略。在此日期之后,将 AWS IoT Greengrass V1 不会发布提供功能、增强功能、错误修复或安全补丁的更新。在上面运行的设备 AWS IoT Greengrass V1 不会中断,将继续运行并连接到云端。我们强烈建议您迁移到 AWS IoT Greengrass Version 2,这样可以添加重要的新功能支持其他平台

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

Greengrass 连接器入门 (CLI)

此功能适用于 AWS IoT Greengrass Core v1.7 及更高版本。

本教程介绍如何通过 AWS CLI 使用连接器。

使用连接器可加快开发生命周期。连接器是预先构建、可重复使用的模块,可以更加轻松地与服务、协议和资源进行交互。它们可以帮助您将业务逻辑更快地部署到 Greengrass 设备。有关更多信息,请参阅使用 Greengrass 连接器与服务和协议集成

在本教程中,您将配置和部署 Twilio 通知连接器。连接器接收 Twilio 消息信息作为输入数据,然后触发 Twilio 文本消息。下图中将显示数据流。

从 Lambda 函数到 Twilio 通知连接器再到 Twilio 的数据流。

配置连接器后,您便可创建 Lambda 函数和订阅。

  • 该函数将评估来自温度传感器的模拟数据。它有条件地将 Twilio 消息信息发布到 MQTT 主题。这是连接器订阅的主题。

  • 该订阅允许函数发布到主题,并允许连接器接收来自该主题的数据。

Twilio 通知连接器需要 Twilio 身份验证令牌,才能与 Twilio API 进行交互。令牌是在 AWS Secrets Manager 中创建且从组资源中引用的文本类型密钥。这样一来,AWS IoT Greengrass 便可在 Greengrass 核心上创建密钥的本地副本,在该核心中,此类副本经过加密且可供连接器使用。有关更多信息,请参阅将密钥部署到 AWS IoT Greengrass 核心

本教程包含以下概括步骤:

完成本教程大约需要 30 分钟。

使用 AWS IoT Greengrass API

使用 Greengrass 组及组组件(例如,组中的连接器、函数和资源)时,了解以下模式会很有帮助。

  • 在层次结构顶部,组件有一个 定义 对象,该对象是版本 对象的容器。反过来,版本又是实际连接器、函数或其他组件类型的容器。

  • 当您部署到 Greengrass 核心时,将部署一个特定的组版本。组版本可包含每种类型的组件的一个版本。核心是必需的,而其他组件可根据需要提供。

  • 版本是不可变的,因此当您要进行更改时必须创建新版本。

提示

如果您在运行 AWS CLI 命令时收到错误,请添加 --debug 参数,然后重新运行该命令以获取有关错误的更多信息。

利用 AWS IoT Greengrass API,您可以为某一组件类型创建多个定义。例如,您可以在每次创建 FunctionDefinition 时都创建一个 FunctionDefinitionVersion 对象,也可以向现有定义添加新版本。这种灵活性使您能够自定义版本管理系统。

先决条件

要完成此教程,需要:

  • Greengrass 组和 Greengrass Core(v1.9.3 或更高版本)。要了解如何创建 Greengrass 组和核心,请参阅 入门 AWS IoT Greengrass。“入门”教程还包含用于安装 AWS IoT Greengrass Core 软件的步骤。

  • 安装在 AWS IoT Greengrass 核心设备上的 Python 3.7。

  • AWS IoT Greengrass 必须配置为支持本地密钥,如密钥要求中所述。

    注意

    此要求包括允许访问您的 Secrets Manager 密钥。如果使用的是默认 Greengrass 服务角色,则 Greengrass 有权获得名称以 greengrass- 开头的密钥的值。

  • Twilio 账户 SID、身份验证令牌和支持 Twilio 的电话号码。创建 Twilio 项目后,项目控制面板上会显示这些值。

    注意

    您可以使用 Twilio 试用账户。如果您使用的是试用账号,则必须将非 Twilio 收件人的电话号码添加到经过验证的电话号码列表中。 有关更多信息,请参阅如何使用您的免费 Twilio 试用账户

  • 在您的计算机上安装并配置 AWS CLI。有关更多信息,请参阅 AWS Command Line Interface 用户指南中的安装 AWS Command Line Interface配置 AWS CLI

     

    本教程中的示例是针对 Linux 及其他基于 Unix 的系统编写的。如果您使用的是 Windows,请参阅为 AWS Command Line Interface 指定参数值以了解语法上的差异。

    如果命令包含 JSON 字符串,本教程提供了在单行包含 JSON 的示例。在某些系统上,使用此格式可能会更容易地编辑和运行命令。

步骤 1:创建 Secrets Manager 密钥

在此步骤中,您将使用 AWS Secrets Manager API 为 Twilio 身份验证令牌创建一个密钥。

  1. 首先,创建该密钥。

    • 使用您的 Twilio 身份验证令牌替换 twilio-auth-token

    aws secretsmanager create-secret --name greengrass-TwilioAuthToken --secret-string twilio-auth-token
    注意

    默认情况下,Greengrass 服务角色允许 AWS IoT Greengrass 获取名称以 greengrass- 开头的密钥的值。有关更多信息,请参阅密钥要求

  2. 从输出中复制该密钥的 ARN。您将使用此密钥创建并配置 Twilio 通知连接器。

步骤 2:创建资源定义和版本

在此步骤中,您将使用 AWS IoT Greengrass API 为 Secrets Manager 密钥创建密钥资源。

  1. 创建一个包含初始版本的资源定义。

    • secret-arn 替换为您在上一步中复制的密钥的 ARN

     

    JSON Expanded
    aws greengrass create-resource-definition --name MyGreengrassResources --initial-version '{ "Resources": [ { "Id": "TwilioAuthToken", "Name": "MyTwilioAuthToken", "ResourceDataContainer": { "SecretsManagerSecretResourceData": { "ARN": "secret-arn" } } } ] }'
    JSON Single-line
    aws greengrass create-resource-definition \ --name MyGreengrassResources \ --initial-version '{"Resources": [{"Id": "TwilioAuthToken", "Name": "MyTwilioAuthToken", "ResourceDataContainer": {"SecretsManagerSecretResourceData": {"ARN": "secret-arn"}}}]}'
  2. 从输出中复制该资源定义的 LatestVersionArn。您将使用此值向部署到核心的组版本添加资源定义版本。

步骤 3:创建连接器定义和版本

在此步骤中,您将为 Twilio 通知连接器配置参数。

  1. 创建包含初始版本的连接器定义。

    • 用您的 Twilio 账户 SID 替换 account-sid

    • secret-arn 替换为您的 Secrets Manager 密钥的 ARN。连接器使用此参数获取本地密钥的值。

    • 使用您的支持 Twilio 的电话号码替换 phone-number。Twilio 使用此参数来启动文本消息。可在输入消息负载中覆盖此参数。采用以下格式:+19999999999

     

    JSON Expanded
    aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyTwilioNotificationsConnector", "ConnectorArn": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4", "Parameters": { "TWILIO_ACCOUNT_SID": "account-sid", "TwilioAuthTokenSecretArn": "secret-arn", "TwilioAuthTokenSecretArn-ResourceId": "TwilioAuthToken", "DefaultFromPhoneNumber": "phone-number" } } ] }'
    JSON Single-line
    aws greengrass create-connector-definition \ --name MyGreengrassConnectors \ --initial-version '{"Connectors": [{"Id": "MyTwilioNotificationsConnector", "ConnectorArn": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4", "Parameters": {"TWILIO_ACCOUNT_SID": "account-sid", "TwilioAuthTokenSecretArn": "secret-arn", "TwilioAuthTokenSecretArn-ResourceId": "TwilioAuthToken", "DefaultFromPhoneNumber": "phone-number"}}]}'
    注意

    TwilioAuthToken 是上一步中创建密钥资源时所使用的 ID。

  2. 从输出中复制该连接器定义的 LatestVersionArn。您将使用此值向部署到核心的组版本添加连接器定义版本。

步骤 4:创建 Lambda 函数部署程序包

要创建 Lambda 函数,您必须先创建一个包含函数代码和依赖项的 Lambda 函数部署包。Greengrass Lambda 函数需要 AWS IoT Greengrass Core 软件开发工具包来执行各项任务,例如在核心环境中与 MQTT 消息通信和访问本地机密等。本教程将创建一个 Python 函数,因此您需要在部署包中使用 Python 版本的软件开发工具包。

  1. AWS IoT Greengrass Core 软件开发工具包下载页面,将适用于 Python 的 AWS IoT Greengrass Core 软件开发工具包下载到您的计算机上。

  2. 解压缩下载的程序包以获取软件开发工具包。软件开发工具包是 greengrasssdk 文件夹。

  3. 将以下 Python 代码函数保存在名为 temp_monitor.py 的本地文件中。

    import greengrasssdk import json import random client = greengrasssdk.client('iot-data') # publish to the Twilio Notifications connector through the twilio/txt topic def function_handler(event, context): temp = event['temperature'] # check the temperature # if greater than 30C, send a notification if temp > 30: data = build_request(event) client.publish(topic='twilio/txt', payload=json.dumps(data)) print('published:' + str(data)) print('temperature:' + str(temp)) return # build the Twilio request from the input data def build_request(event): to_name = event['to_name'] to_number = event['to_number'] temp_report = 'temperature:' + str(event['temperature']) return { "request": { "recipient": { "name": to_name, "phone_number": to_number, "message": temp_report } }, "id": "request_" + str(random.randint(1,101)) }
  4. 将以下项目压缩到名为 temp_monitor_python.zip 的文件中。在创建 ZIP 文件时,仅包含代码和依赖项,而不包含文件夹。

    • temp_monitor.py。应用程序逻辑。

    • greengrasssdk。发布 MQTT 消息的 Python Greengrass Lambda 函数所需的库。

    此即 Lambda 函数部署程序包。

步骤 5:创建 Lambda 函数

现在,创建一个使用部署程序包的 Lambda 函数。

  1. 创建 IAM 角色,以便您可以在创建该函数时传入角色 ARN。

    JSON Expanded
    aws iam create-role --role-name Lambda_empty --assume-role-policy '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }'
    JSON Single-line
    aws iam create-role --role-name Lambda_empty --assume-role-policy '{"Version": "2012-10-17", "Statement": [{"Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"},"Action": "sts:AssumeRole"}]}'
    注意

    AWS IoT Greengrass 不使用此角色,因为对 Greengrass Lambda 函数的权限在 Greengrass 组角色中指定。对于本教程,您将创建一个空角色。

  2. 从输出中复制 Arn

  3. 使用 AWS Lambda API 创建 TempMonitor 函数。以下命令假定该 zip 文件位于当前目录中。

    • role-arn 替换为复制的 Arn

    aws lambda create-function \ --function-name TempMonitor \ --zip-file fileb://temp_monitor_python.zip \ --role role-arn \ --handler temp_monitor.function_handler \ --runtime python3.7
  4. 发布该函数的版本。

    aws lambda publish-version --function-name TempMonitor --description 'First version'
  5. 为发布的版本创建别名。

    Greengrass 组可以按别名(推荐)或版本引用 Lambda 函数。使用别名,您可以更轻松地管理代码更新,因为您在更新函数代码时,不必更改订阅表或组定义。相反,您只需将别名指向新的函数版本。

    注意

    AWS IoT Greengrass 不支持 $LATEST 版本的 Lambda 别名。

    aws lambda create-alias --function-name TempMonitor --name GG_TempMonitor --function-version 1
  6. 从输出中复制 AliasArn。在为 AWS IoT Greengrass 配置函数时以及在创建订阅时,使用此值。

现在,您已准备就绪,可以为 AWS IoT Greengrass 配置函数。

步骤 6:创建函数定义和版本

要在 AWS IoT Greengrass 核心上使用 Lambda 函数,请创建一个按别名引用 Lambda 函数的函数定义版本,并定义组级别的配置。有关更多信息,请参阅使用组特定的配置控制 Greengrass Lambda 函数的执行

  1. 创建一个包含初始版本的函数定义。

    • alias-arn 替换为您创建别名时复制的 AliasArn

     

    JSON Expanded
    aws greengrass create-function-definition --name MyGreengrassFunctions --initial-version '{ "Functions": [ { "Id": "TempMonitorFunction", "FunctionArn": "alias-arn", "FunctionConfiguration": { "Executable": "temp_monitor.function_handler", "MemorySize": 16000, "Timeout": 5 } } ] }'
    JSON Single-line
    aws greengrass create-function-definition \ --name MyGreengrassFunctions \ --initial-version '{"Functions": [{"Id": "TempMonitorFunction", "FunctionArn": "alias-arn", "FunctionConfiguration": {"Executable": "temp_monitor.function_handler", "MemorySize": 16000,"Timeout": 5}}]}'
  2. 从输出中复制 LatestVersionArn。您将使用此值向部署到核心的组版本添加函数定义版本。

  3. 从输出中复制 Id。您在稍后更新该函数时将使用此值。

步骤 7:创建订阅定义和版本

在该步骤中,您将添加一个订阅,使 Lambda 函数将输入数据发送到连接器。此连接器定义它订阅的 MQTT 主题,因此该订阅使用其中一个主题。这与示例函数发布到的主题相同。

对于本教程,您还可以创建订阅,以允许函数从 AWS IoT 接收模拟温度读数,并允许 AWS IoT 从连接器接收状态信息。

  1. 创建一个订阅定义,其中包含带有订阅的初始版本。

    • alias-arn替换为您为函数创建别名时复制的 AliasArn。将此 ARN 用于使用它的两个订阅。

     

    JSON Expanded
    aws greengrass create-subscription-definition --initial-version '{ "Subscriptions": [ { "Id": "TriggerNotification", "Source": "alias-arn", "Subject": "twilio/txt", "Target": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4" }, { "Id": "TemperatureInput", "Source": "cloud", "Subject": "temperature/input", "Target": "alias-arn" }, { "Id": "OutputStatus", "Source": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4", "Subject": "twilio/message/status", "Target": "cloud" } ] }'
    JSON Single-line
    aws greengrass create-subscription-definition \ --initial-version '{"Subscriptions": [{"Id": "TriggerNotification", "Source": "alias-arn", "Subject": "twilio/txt", "Target": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4"},{"Id": "TemperatureInput", "Source": "cloud", "Subject": "temperature/input", "Target": "alias-arn"},{"Id": "OutputStatus", "Source": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4", "Subject": "twilio/message/status", "Target": "cloud"}]}'
  2. 从输出中复制 LatestVersionArn。您将使用此值向部署到核心的组版本添加订阅定义版本。

步骤 8:创建组版本

现在已准备就绪,可以创建一个包含要部署的所有项目的组版本。要实现此目的,需要创建一个引用每种组件类型的目标版本的组版本。

首先,获取核心定义版本的组 ID 和 ARN。这些值是创建组版本所必需的。

  1. 获取组的 ID 和最新组版本:

    1. 获取目标 Greengrass 组和组版本的 ID。此过程假定这是最新的组和组版本。以下查询将返回最近创建的组。

      aws greengrass list-groups --query "reverse(sort_by(Groups, &CreationTimestamp))[0]"

      或者,您也可以按名称查询。系统不要求组名称是唯一的,所以可能会返回多个组。

      aws greengrass list-groups --query "Groups[?Name=='MyGroup']"
      注意

      您还可以在 AWS IoT 控制台中找到这些值。组 ID 显示在组的设置页面上。组版本 ID 显示在组的部署选项卡上。

    2. 从输出中复制目标组的 Id。您将使用此值获取核心定义版本及部署组的时间。

    3. 从输出中复制 LatestVersion,这是添加到组的最后一个版本的 ID。您将使用此值获取核心定义版本。

  2. 获取核心定义版本的 ARN:

    1. 获取组版本。在此步骤中,我们假定最新组版本包含一个核心定义版本。

      • 使用为组复制的 替换 group-idId

      • 使用为组复制的 LatestVersion 替换 group-version-id

      aws greengrass get-group-version \ --group-id group-id \ --group-version-id group-version-id
    2. 从输出中复制 CoreDefinitionVersionArn

  3. 创建组版本。

    • 使用为组复制的 替换 group-idId

    • 使用为核心函数版本复制的 CoreDefinitionVersionArn 替换 core-definition-version-arn

    • resource-definition-version-arn 替换为您针对资源定义复制的 LatestVersionArn

    • connector-definition-version-arn 替换为您针对连接器定义复制的 LatestVersionArn

    • 使用为函数定义复制的 LatestVersionArn 替换 function-definition-version-arn

    • subscription-definition-version-arn 替换为您针对订阅定义复制的 LatestVersionArn

    aws greengrass create-group-version \ --group-id group-id \ --core-definition-version-arn core-definition-version-arn \ --resource-definition-version-arn resource-definition-version-arn \ --connector-definition-version-arn connector-definition-version-arn \ --function-definition-version-arn function-definition-version-arn \ --subscription-definition-version-arn subscription-definition-version-arn
  4. 从输出中复制 Version 的值。这是组版本的 ID。您将使用此值部署组版本。

步骤 9:创建部署

将组部署到核心设备。

  1. 在核心设备终端中,确保 AWS IoT Greengrass 守护程序正在运行。

    1. 要检查守护程序是否正在运行,请执行以下操作:

      ps aux | grep -E 'greengrass.*daemon'

      如果输出包含 root/greengrass/ggc/packages/1.11.6/bin/daemon 条目,则表示守护程序正在运行。

    2. 启动进程守护程序:

      cd /greengrass/ggc/core/ sudo ./greengrassd start
  2. 创建 部署。

    • 使用为组复制的 替换 group-idId

    • 使用为新组版本复制的 替换 group-version-idVersion

    aws greengrass create-deployment \ --deployment-type NewDeployment \ --group-id group-id \ --group-version-id group-version-id
  3. 从输出中复制 DeploymentId

  4. 获取部署状态。

    • 使用为组复制的 替换 group-idId

    • deployment-id 替换为您针对部署复制的 DeploymentId

    aws greengrass get-deployment-status \ --group-id group-id \ --deployment-id deployment-id

    如果状态为 Success,则部署成功。有关问题排查帮助,请参阅故障排除 AWS IoT Greengrass

测试解决方案

  1. 在 AWS IoT 控制台主页上,选择测试

  2. 对于订阅主题,请使用以下值,然后选择订阅。Twilio 通知连接器向此主题发布状态信息。

    属性

    Value

    订阅主题

    twilio/message/status

    MQTT 负载显示

    将负载显示为字符串

  3. 对于发布到主题,请使用以下值,然后选择发布 来调用函数。

    属性

    Value

    主题

    temperature/input

    消息

    recipient-name 替换为文本消息收件人的姓名,将 recipient-phone-number 替换为文本消息收件人的电话号码。示例:+12345000000

    { "to_name": "recipient-name", "to_number": "recipient-phone-number", "temperature": 31 }

    如果您使用的是试用账号,则必须将非 Twilio 收件人的电话号码添加到经过验证的电话号码列表中。有关更多信息,请参阅验证您的个人电话号码

    如果成功,收件人将收到短信,控制台将在输出数据中显示 success 状态。

    现在,将输入消息中的 temperature 更改为 29 并发布。由于温度小于 30,因此 TempMonitor 函数不会触发 Twilio 消息。

另请参阅