AWS IoT Greengrass
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

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 核心 (v1.7 or later)。要了解如何创建 Greengrass 组和核心,请参阅 AWS IoT Greengrass 入门。“入门”教程还包含用于安装 AWS IoT Greengrass 核心软件的步骤。

  • 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 命令行界面指定参数值以了解语法上的差异。

    如果命令包含 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. 创建一个包含初始版本的资源定义。

    • 使用上一步中复制的密钥的 ARN 替换 secret-arn

     

    JSON 扩展JSON Single-line
    JSON 扩展
    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

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

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

     

    JSON 扩展JSON Single-line
    JSON 扩展
    aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyTwilioNotificationsConnector", "ConnectorArn": "arn:aws-cn:greengrass:区域::/connectors/TwilioNotifications/versions/2", "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-cn:greengrass:区域::/connectors/TwilioNotifications/versions/2", "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 开发工具包。在 Python 部分,选择 v1.4.0 - Current version (on GitHub) (1.4.0 版本 – 最新版本(在 GitHub 上)),然后下载软件开发工具包。

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

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

    from __future__ import print_function 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。

    注意

    AWS IoT Greengrass 不使用此角色,因为对 Greengrass Lambda 函数的权限在 Greengrass 组角色中指定。在本教程中,您将创建一个空角色(或者,您也可以使用现有的执行角色)。

     

    JSON 扩展JSON Single-line
    JSON 扩展
    aws iam create-role --role-name Lambda_empty --assume-role-policy '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com.cn" }, "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.cn"},"Action": "sts:AssumeRole"}]}'
  2. 复制输出的 Arn

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

    • 使用您复制的 Arn 替换 role-arn

    aws lambda create-function \ --function-name TempMonitor \ --zip-file fileb://temp_monitor_python.zip \ --role role-arn \ --handler temp_monitor.function_handler \ --runtime python2.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 Core 上使用 Lambda 函数,请创建一个按别名引用 Lambda 函数的函数定义版本,并定义组级别的配置。有关更多信息,请参阅使用组特定配置控制 Greengrass Lambda 函数的执行

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

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

     

    JSON 扩展JSON Single-line
    JSON 扩展
    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. 创建一个订阅定义,其中包含带有订阅的初始版本。

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

     

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

步骤 8:创建组版本

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

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

  1. 获取组的 ID:

    1. 列出您的组。

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

    3. 从输出中复制组版本的 LatestVersion。您将使用此值获取核心定义版本。

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

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

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

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

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

  3. 创建组版本。

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

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

    • 使用为资源定义复制的 LatestVersionArn 替换 resource-definition-version-arn

    • 使用为连接器定义复制的 LatestVersionArn 替换 connector-definition-version-arn

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

    • 使用为订阅定义复制的 LatestVersionArn 替换 subscription-definition-version-arn

    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.9.0/bin/daemon 条目,则表示守护程序正在运行。

    2. 要启动守护程序,请执行以下操作:

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

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

    • 使用为组版本复制的 Version 替换 group-version-id

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

  4. 获取部署状态。

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

    • 使用为部署复制的 DeploymentId 替换 deployment-id

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

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

测试解决方案

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

    
                AWS IoT Core 控制台的左侧窗格,突出显示了“Test (测试)”。
  2. 对于订阅,请使用以下值,然后选择 Subscribe to topic。Twilio 通知 连接器向此主题发布状态信息。

    属性

    订阅主题

    twilio/message/status

    MQTT 负载显示

    将负载显示为字符串

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

    属性

    主题

    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 消息。

另请参阅