Twilio 通知连接器 - 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开发人员指南.

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

Twilio 通知连接器

Twilio 通知连接器通过 Twilio 进行自动电话呼叫或发送文本消息。您可以使用该连接器来发送通知,以响应 Greengrass 组中的事件。对于电话呼叫,连接器可以将语音消息转发给收件人。

该连接器接收关于 MQTT 主题的 Twilio 消息信息,然后触发 Twilio 通知。

注意

有关介绍如何使用 Twilio 通知连接器的教程,请参阅Greengrass 连接器入门(控制台)或者Greengrass 连接器入门 (CLI).

此连接器具有以下版本。

Version

ARN

5

arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/5

4

arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4

3

arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/3

2

arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/2

1

arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/1

有关版本更改的信息,请参阅更改日志

Requirements

此连接器具有以下要求:

Version 4 - 5
  • Amazon IoT GreengrassCore 软件 v1.9.3 版或更高版本。Amazon IoT Greengrass必须配置为支持本地密钥,如中所述Secrets 要求.

    注意

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

  • Python版本 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 要求。

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

    注意

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

  • Amazon Secrets Manager 中的文本类型密钥,用于存储 Twilio 身份验证令牌。有关更多信息,请参阅 。创建基本密钥中的Amazon Secrets Manager用户指南.

    注意

    要在 Secrets Manager 控制台中创建密钥,请在明文选项卡。不要包括引号或其他格式。在 API 中,将令牌指定为SecretString属性。

  • Greengrass 组中引用密钥管理器密钥的密钥资源。有关更多信息,请参阅将密钥部署到 Amazon IoT Greengrass 核心

Versions 1 - 3
  • Amazon IoT Greengrass核心软件版本 v1.7 或更高版本。Amazon IoT Greengrass必须配置为支持本地密钥,如中所述Secrets 要求.

    注意

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

  • Python安装在核心设备上并添加到 PATH 环境变量中。

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

    注意

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

  • Amazon Secrets Manager 中的文本类型密钥,用于存储 Twilio 身份验证令牌。有关更多信息,请参阅 。创建基本密钥中的Amazon Secrets Manager用户指南.

    注意

    要在 Secrets Manager 控制台中创建密钥,请在明文选项卡。不要包括引号或其他格式。在 API 中,将令牌指定为SecretString属性。

  • Greengrass 组中引用密钥管理器密钥的密钥资源。有关更多信息,请参阅将密钥部署到 Amazon IoT Greengrass 核心

Connector of

该连接器提供以下参数。

Version 5
TWILIO_ACCOUNT_SID

Twilio 账户 SID,用于调用 Twilio API。

在Amazon IoT控制台:Twilio 账户 SID

:必需true

类型:string

有效模式:.+

TwilioAuthTokenSecretArn

密钥 Secrets Manager 钥,用于存储 Twilio 身份验证令牌。

注意

这用于访问核心上的本地密钥的值。

在Amazon IoT控制台:Twilio 身份验证令牌密钥的 ARN

:必需true

类型:string

有效模式:arn:aws:secretsmanager:[a-z0-9\-]+:[0-9]{12}:secret:([a-zA-Z0-9\\]+/)*[a-zA-Z0-9/_+=,.@\-]+-[a-zA-Z0-9]+

TwilioAuthTokenSecretArn-ResourceId

Greengrass 组中密钥资源的 ID,该资源引用 Twilio 身份验证令牌的密钥。

在Amazon IoT控制台:Twilio 身份验证令牌资源

:必需true

类型:string

有效模式:.+

DefaultFromPhoneNumber

支持 Twilio 的默认电话号码,Twilio 用该电话号码发送消息。Twilio 用该号码来启动文本或呼叫。

  • 如果不配置默认电话号码,必须在输入消息正文的 from_number 属性中指定电话号码。

  • 如果配置默认电话号码,则可视情况通过指定输入消息正文中的 from_number 属性来覆盖默认值。

在Amazon IoT控制台:默认的来电号码

:必需false

类型:string

有效模式:^$|\+[0-9]+

IsolationMode

此连接器的容器化模式。默认值为 GreengrassContainer,这意味着连接器在 Amazon IoT Greengrass 容器内的隔离运行时环境中运行。

注意

组的默认容器化设置不适用于连接器。

在Amazon IoT控制台:容器隔离模式

:必需false

类型:string

有效值:GreengrassContainerNoContainer

有效模式:^NoContainer$|^GreengrassContainer$

Version 1 - 4
TWILIO_ACCOUNT_SID

Twilio 账户 SID,用于调用 Twilio API。

在Amazon IoT控制台:Twilio 账户 SID

:必需true

类型:string

有效模式:.+

TwilioAuthTokenSecretArn

密钥 Secrets Manager 钥,用于存储 Twilio 身份验证令牌。

注意

这用于访问核心上的本地密钥的值。

在Amazon IoT控制台:Twilio 身份验证令牌密钥的 ARN

:必需true

类型:string

有效模式:arn:aws:secretsmanager:[a-z0-9\-]+:[0-9]{12}:secret:([a-zA-Z0-9\\]+/)*[a-zA-Z0-9/_+=,.@\-]+-[a-zA-Z0-9]+

TwilioAuthTokenSecretArn-ResourceId

Greengrass 组中密钥资源的 ID,该资源引用 Twilio 身份验证令牌的密钥。

在Amazon IoT控制台:Twilio 身份验证令牌资源

:必需true

类型:string

有效模式:.+

DefaultFromPhoneNumber

支持 Twilio 的默认电话号码,Twilio 用该电话号码发送消息。Twilio 用该号码来启动文本或呼叫。

  • 如果不配置默认电话号码,必须在输入消息正文的 from_number 属性中指定电话号码。

  • 如果配置默认电话号码,则可视情况通过指定输入消息正文中的 from_number 属性来覆盖默认值。

在Amazon IoT控制台:默认的来电号码

:必需false

类型:string

有效模式:^$|\+[0-9]+

创建连接器示例 (Amazon CLI)

以下示例 CLI 命令创建ConnectorDefinition,其初始版本包含 Twilio 通知连接器。

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyTwilioNotificationsConnector", "ConnectorArn": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/5", "Parameters": { "TWILIO_ACCOUNT_SID": "abcd12345xyz", "TwilioAuthTokenSecretArn": "arn:aws:secretsmanager:region:account-id:secret:greengrass-secret-hash", "TwilioAuthTokenSecretArn-ResourceId": "MyTwilioSecret", "DefaultFromPhoneNumber": "+19999999999", "IsolationMode" : "GreengrassContainer" } } ] }'

有关介绍如何将 Twilio 通知连接器添加到组的教程,请参阅Greengrass 连接器入门 (CLI)Greengrass 连接器入门(控制台).

输入数据

此连接器接受关于两个 MQTT 主题的 Twilio 消息信息。输入消息必须采用 JSON 格式。

  • 关于 twilio/txt 主题的文本消息信息。

  • 关于 twilio/call 主题的电话消息信息。

注意

输入消息负载可包含文本消息 (message) 或语音消息 (voice_message_location),但不能同时包含二者。

主题筛选条件:twilio/txt
消息属性
request

有关 Twilio 通知的信息。

:必需true

类型:object,包含以下属性的:

recipient

消息收件人。只支持一个收件人。

:必需true

类型:object,包含以下属性的:

name

收件人的姓名。

:必需true

类型:string

有效模式:.*

phone_number

收件人的电话号码。

:必需true

类型:string

有效模式:\+[1-9]+

message

文本消息的文本内容。本主题仅支持文本消息。对于语音消息,请使用 twilio/call

:必需true

类型:string

有效模式:.+

from_number

发件人的 电话号码。Twilio 用该电话号码来启动消息。只有在未配置 DefaultFromPhoneNumber 参数时才需要该属性。如果已配置 DefaultFromPhoneNumber,则可使用该属性来覆盖默认值。

:必需false

类型:string

有效模式:\+[1-9]+

retries

重试次数。默认值为 0。

:必需false

类型:integer

id

请求的任意 ID。此属性用于将输入请求映射到输出响应。

:必需true

类型:string

有效模式:.+

示例输入
{ "request": { "recipient": { "name": "Darla", "phone_number": "+12345000000", "message": "Hello from the edge" }, "from_number": "+19999999999", "retries": 3 }, "id": "request123" }
主题筛选条件:twilio/call
消息属性
request

有关 Twilio 通知的信息。

:必需true

类型:object,包含以下属性的:

recipient

消息收件人。只支持一个收件人。

:必需true

类型:object,包含以下属性的:

name

收件人的姓名。

:必需true

类型:string

有效模式:.+

phone_number

收件人的电话号码。

:必需true

类型:string

有效模式:\+[1-9]+

voice_message_location

语音消息的音频内容的 URL。必须采用 TwiML 格式。本主题仅支持语音消息。对于文本消息,请使用 twilio/txt

:必需true

类型:string

有效模式:.+

from_number

发件人的 电话号码。Twilio 用该电话号码来启动消息。只有在未配置 DefaultFromPhoneNumber 参数时才需要该属性。如果已配置 DefaultFromPhoneNumber,则可使用该属性来覆盖默认值。

:必需false

类型:string

有效模式:\+[1-9]+

retries

重试次数。默认值为 0。

:必需false

类型:integer

id

请求的任意 ID。此属性用于将输入请求映射到输出响应。

:必需true

类型:string

有效模式:.+

示例输入
{ "request": { "recipient": { "name": "Darla", "phone_number": "+12345000000", "voice_message_location": "https://some-public-TwiML" }, "from_number": "+19999999999", "retries": 3 }, "id": "request123" }

输出数据

此连接器将状态信息发布为 MQTT 主题的输出数据。

订阅中的主题筛选条件

twilio/message/status

输出示例:成功
{ "response": { "status": "success", "payload": { "from_number": "+19999999999", "messages": { "message_status": "queued", "to_number": "+12345000000", "name": "Darla" } } }, "id": "request123" }
输出示例:失败
{ "response": { "status": "fail", "error_message": "Recipient name cannot be None", "error": "InvalidParameter", "payload": None } }, "id": "request123" }

输出中的 payload 属性是发送消息时来自 Twilio API 的响应。如果连接器检测到输入数据无效(例如,它不指定必填的输入字段),则连接器会返回错误并将值设置为 None。以下为示例负载:

{ 'from_number':'+19999999999', 'messages': { 'name':'Darla', 'to_number':'+12345000000', 'message_status':'undelivered' } }
{ 'from_number':'+19999999999', 'messages': { 'name':'Darla', 'to_number':'+12345000000', 'message_status':'queued' } }

用法示例

使用以下概括步骤设置可用于尝试连接器的示例 Python 3.7 Lambda 函数。

注意

Greengrass 连接器入门(控制台)Greengrass 连接器入门 (CLI) 主题包含端到端步骤,说明如何设置、部署和测试 Twilio 通知连接器。

  1. 确保满足连接器的要求

  2. 创建并发布将输入数据发送到连接器的 Lambda 函数。

    示例代码保存为 PY 文件。下载并解压缩Amazon IoT Greengrass适用于 Python 的核心工具包. 然后,创建一个 zip 包,其中在根级别包含 PY 文件和 greengrasssdk 文件夹。此 zip 包是您上传到的部署包Amazon Lambda.

    创建 Python 3.7 Lambda 函数后,发布函数版本并创建别名。

  3. 配置 Greengrass 组。

    1. 通过函数的别名添加 Lambda(推荐)。将 Lambda 生命周期配置为长时间生存(或"Pinned": true)。

    2. 添加所需的密钥资源并授予对 Lambda 函数的读取访问权限。

    3. 添加连接器并配置其参数

    4. 添加允许连接器接收输入数据并针对支持的主题筛选条件发送输出数据的订阅。

      • 将 Lambda 函数设置为源,将连接器设置为目标,并使用支持的输入主题筛选条件。

      • 将连接器设置为源,将 Amazon IoT Core 设置为目标,并使用支持的输出主题筛选条件。您可以使用此订阅查看中的状态消息。Amazon IoT控制台。

  4. 部署组。

  5. 在Amazon IoT控制台、测试页面上,订阅输出数据主题以查看连接器中的状态消息。示例 Lambda 函数是长时间生存的,并且在部署组后立即开始发送消息。

    完成测试后,您可以将 Lambda 生命周期设置为按需(或"Pinned": false)并部署组。这会阻止函数发送消息。

Example

以下示例 Lambda 函数将输入消息发送到连接器。此示例触发文本消息。

import greengrasssdk import json iot_client = greengrasssdk.client('iot-data') TXT_INPUT_TOPIC = 'twilio/txt' CALL_INPUT_TOPIC = 'twilio/call' def publish_basic_message(): txt = { "request": { "recipient" : { "name": "Darla", "phone_number": "+12345000000", "message": 'Hello from the edge' }, "from_number" : "+19999999999" }, "id" : "request123" } print("Message To Publish: ", txt) client.publish(topic=TXT_INPUT_TOPIC, payload=json.dumps(txt)) publish_basic_message() def lambda_handler(event, context): return

Licenses

Twilio 通知连接器包含以下第三方软件/许可:

此连接器在Greengrass 核心软件许可协议.

Changelog

下表介绍每一版的连接器中的更改。

Version

更改

5

增加了用于配置连接器容器化模式的 IsolationMode 参数。

4

已将 Lambda 运行时升级到 Python 3.7,这会更改运行时要求。

3

进行了修复,以减少过多的日志记录。

2

少量错误修复和改进。

1

首次发布。

Greengrass 组每次只能包含一个连接器版本。有关升级连接器版本的信息,请参阅升级连接器版本

另请参阅