Greengrass 连接器入门 (CLI) - 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开发人员指南.

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

Greengrass 连接器入门 (CLI)

此功能适用于Amazon IoT Greengrass核心 v1.7 及更高版本。

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

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

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

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

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

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

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

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

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

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

使用 Amazon IoT Greengrass API

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

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

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

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

提示

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

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

Prerequisites

要完成此教程,需要:

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

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

  • Amazon IoT Greengrass必须配置为支持本地密钥,如Secrets 要求.

    注意

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

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

    注意

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

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

     

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

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

第 1 步:创建 Secrets Manager 密钥

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

  1. 首先,创建该密钥。

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

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

    默认情况下,Greengrass 服务角色允许Amazon IoT Greengrass获取名称以Greengrass. 有关更多信息,请参阅密钥要求

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

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

在此步骤中,您将使用Amazon IoT GreengrassAPI 为密钥管理器密钥创建密钥资源。

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

    • Replace秘密 arnARN,您在之前的步骤中复制了密钥。

     

    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

    • Replace秘密 arnARN您的 Secrets Manager 密钥。连接器使用此参数获取本地密钥的值。

    • 使用您的支持 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 函数需要Amazon IoT Greengrass核心开发工具包用于在核心环境中与 MQTT 消息进行通信和访问本地机密等任务。本教程将创建一个 Python 函数,因此您可以在部署包中使用 SDK 的 Python 版本。

  1. Amazon IoT Greengrass核心开发工具包下载页面,下载Amazon IoT Greengrass核心软件开发工具包到您的计算机。

  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"}]}'
    注意

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

  2. 从输出中复制 Arn

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

    • Replace角色 ARNArn复制的。

    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 函数。使用别名,您可以更轻松地管理代码更新,因为您无需更改订阅表或组定义。相反,您只需将别名指向新函数版本。

    注意

    Amazon IoT Greengrass不支持$LATEST版本。

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

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

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

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

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

    • Replace别名 ARNAliasArn创建别名时复制的。

     

    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 主题,因此该订阅使用其中一个主题。这与示例函数发布到的主题相同。

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

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

    • Replace别名 ARNAliasArn,您为函数创建别名时复制。将此 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']"
      注意

      您还可以在Amazon IoT控制台。组 ID 显示在组的设置页面上。组版本 ID 显示在组的部署页面上。

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

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

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

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

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

      • Replace组版本 idLatestVersion为组复制的。

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

  3. 创建组版本。

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

    • Replace核心定义版本 ARNCoreDefinitionVersionArn为核心定义版本复制。

    • Replace资源定义版本 ARNLatestVersionArn复制的资源定义。

    • Replace连接器定义版本 ARNLatestVersionArn为连接器定义复制的。

    • Replace函数定义版本 ARNLatestVersionArn为函数定义复制的。

    • Replace订阅-定义-版本-ARNLatestVersionArn为订阅定义复制的。

    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. 在核心设备终端中,确保 Amazon IoT Greengrass 守护程序正在运行。

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

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

      如果输出包含 root/greengrass/ggc/packages/1.11.3/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

    • Replace部署 IDDeploymentId为部署而复制的。

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

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

测试解决方案

  1. 在存储库的Amazon IoT控制台主页中,选择测试.

    
                的左侧窗格Amazon IoT控制台,突出显示了 Test (
  2. 适用于订阅主题,请使用以下值,然后选择订阅. Twilio 通知连接器向此主题发布状态信息。

    属性

    订阅主题

    twilio/message/status

    MQTT 负载显示

    将负载显示为字符串

  3. 适用于向主题发布,请使用以下值,然后选择发布以调用该函数。

    属性

    主题

    temperature/input

    Message

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

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

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

    如果成功,收件人会收到文本消息,控制台会显示success状态来自输出数据.

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

另请参阅