支援終止通知：2026 年 10 月 7 日 AWS 將停止 的支援 AWS IoT Greengrass Version 1。2026 年 10 月 7 日之後，您將無法再存取 AWS IoT Greengrass V1 資源。如需詳細資訊，請造訪[從 遷移 AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html)。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Twilio 通知連接器 **警告** 此連接器已進入*延長生命週期階段*，且 AWS IoT Greengrass 不會發行提供現有功能、增強功能、安全修補程式或錯誤修正的更新。如需詳細資訊，請參閱[AWS IoT Greengrass Version 1 維護政策](maintenance-policy.md)。 Twilio Notifications [連接器](connectors.md)會透過 Twilio 自動撥打電話或傳送文字訊息。您可以使用此連接器傳送通知，以回應 Greengrass 群組中的事件。對於電話呼叫，連接器可以將語音訊息轉發給收件人。 此連接器會接收 MQTT 主題上的 Twilio 訊息，然後觸發 Twilio 通知。 **注意** 如需示範如何使用 Twilio Notifications 連接器的教學課程，請參閱 [Greengrass 連接器入門 (主控台)](connectors-console.md)或 [Greengrass 連接器入門 (CLI)](connectors-cli.md)。 此連接器具有下列版本。 | 版本 | 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` | 如需版本變更的詳細資訊，請參閱 [Changelog](#twilio-notifications-connector-changelog)。 ## 要求 此連接器有下列要求： ------ #### [ Version 4 - 5 ] + AWS IoT Greengrass 核心軟體 v1.9.3 或更新版本。 AWS IoT Greengrass 必須設定為支援本機秘密，如[秘密需求](secrets.md#secrets-reqs)中所述。 **注意** 此要求包括允許存取您的 Secrets Manager 秘密。如果您使用預設的 Greengrass 服務角色，Greengrass 有權取得名稱開頭為 *greengrass-* 的秘密值。 + 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 3.7 或 3.8 版。 **注意** 若要使用 Python 3.8，請執行下列命令來建立從預設 Python 3.7 安裝資料夾到已安裝 Python 3.8 二進位檔的符號連結。 ``` sudo ln -s {{path-to-python-3.8}}/python3.8 /usr/bin/python3.7 ``` 這會設定您的裝置以符合 AWS IoT Greengrass的 Python 需求。 + Twilio 帳戶 SID、驗證字符和已啟用 Twilio 的電話號碼。在您建立 Twilio 專案後，您就可在專案儀表板上使用這些值。 **注意** 您可以使用 Twilio 試用帳戶。如果您使用的是試驗帳戶，則必須將非 Twilio 收件人的電話號碼新增至已驗證的電話號碼清單。如需詳細資訊，請參閱[如何使用您的 免費 Twilio 試用帳戶](https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account)。 + 在 中 AWS Secrets Manager 存放 Twilio 驗證字符的文字類型秘密。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[建立基本秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)。 **注意** 若要在 Secrets Manager 主控台中建立秘密，請在**純文字**索引標籤上輸入您的字符。請勿包含引號或其他格式。在 API 中，指定字符做為 `SecretString` 屬性的值。 + Greengrass 群組中參考 Secrets Manager 秘密的秘密資源。如需詳細資訊，請參閱[將秘密部署到 AWS IoT Greengrass 核心](secrets.md)。 ------ #### [ Versions 1 - 3 ] + AWS IoT Greengrass 核心軟體 v1.7 或更新版本。 AWS IoT Greengrass 必須設定為支援本機秘密，如[秘密需求](secrets.md#secrets-reqs)中所述。 **注意** 此要求包括允許存取您的 Secrets Manager 秘密。如果您使用預設 Greengrass 服務角色，Greengrass 有權取得名稱開頭為 *greengrass-* 的秘密值。 + 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 2.7 版。 + Twilio 帳戶 SID、驗證字符和已啟用 Twilio 的電話號碼。在您建立 Twilio 專案後，您就可在專案儀表板上使用這些值。 **注意** 您可以使用 Twilio 試用帳戶。如果您使用的是試驗帳戶，則必須將非 Twilio 收件人的電話號碼新增至已驗證的電話號碼清單。如需詳細資訊，請參閱[如何使用您的 免費 Twilio 試用帳戶](https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account)。 + 在 中 AWS Secrets Manager 存放 Twilio 驗證字符的文字類型秘密。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[建立基本秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)。 **注意** 若要在 Secrets Manager 主控台中建立秘密，請在**純文字**索引標籤上輸入您的字符。請勿包含引號或其他格式。在 API 中，指定字符做為 `SecretString` 屬性的值。 + Greengrass 群組中參考 Secrets Manager 秘密的秘密資源。如需詳細資訊，請參閱[將秘密部署到 AWS IoT Greengrass 核心](secrets.md)。 ------ ## 連接器參數 此連接器提供下列參數。 ------ #### [ Version 5 ] `TWILIO_ACCOUNT_SID` 用於叫用 Twilio API 的 Twilio 帳戶 SID。 在 AWS IoT 主控台中顯示名稱：**Twilio 帳戶 SID** 必要：`true` 類型：`string` 有效模式： `.+` `TwilioAuthTokenSecretArn` 存放 Twilio 驗證字符之 Secrets Manager 秘密的 ARN。 這用於存取核心上的本機私密值。 在 AWS 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 群組中參考 Twilio 驗證字符私密的私密資源的 ID。 AWS IoT 主控台中的顯示名稱：**Twilio 驗證字符資源** 必要：`true` 類型：`string` 有效模式： `.+` `DefaultFromPhoneNumber` 預設已啟用 Twilio 的電話號碼，供 Twilio 用來傳送訊息。Twilio 使用此號碼來起始文字或通話。 + 如果您不設定預設電話號碼，則必須在輸入訊息本文的 `from_number` 屬性中指定電話號碼。 + 如果您設定預設電話號碼，您可以選擇在輸入訊息本文中指定 `from_number` 屬性，以覆寫預設值。 AWS IoT 主控台中的顯示名稱：**電話號碼的預設** 必要：`false` 類型：`string` 有效模式： `^$|\+[0-9]+` `IsolationMode` 此連接器的[容器化](connectors.md#connector-containerization)模式。預設值為 `GreengrassContainer`，這表示連接器會在 AWS IoT Greengrass 容器內的隔離執行時間環境中執行。 群組的預設容器化設定不會套用至連接器。 AWS IoT 主控台中的顯示名稱：**容器隔離模式** 必要：`false` 類型：`string` 有效值：`GreengrassContainer` 或 `NoContainer` 有效模式： `^NoContainer$|^GreengrassContainer$` ------ #### [ Version 1 - 4 ] `TWILIO_ACCOUNT_SID` 用於叫用 Twilio API 的 Twilio 帳戶 SID。 在 AWS IoT 主控台中顯示名稱：**Twilio 帳戶 SID** 必要：`true` 類型：`string` 有效模式： `.+` `TwilioAuthTokenSecretArn` 存放 Twilio 驗證字符之 Secrets Manager 秘密的 ARN。 這用於存取核心上的本機私密值。 AWS 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 群組中參考 Twilio 驗證字符私密的私密資源的 ID。 AWS IoT 主控台中的顯示名稱：**Twilio 驗證字符資源** 必要：`true` 類型：`string` 有效模式： `.+` `DefaultFromPhoneNumber` 預設已啟用 Twilio 的電話號碼，供 Twilio 用來傳送訊息。Twilio 使用此號碼來起始文字或通話。 + 如果您不設定預設電話號碼，則必須在輸入訊息本文的 `from_number` 屬性中指定電話號碼。 + 如果您設定預設電話號碼，您可以選擇在輸入訊息本文中指定 `from_number` 屬性，以覆寫預設值。 AWS IoT 主控台中的顯示名稱：**電話號碼的預設** 必要：`false` 類型：`string` 有效模式： `^$|\+[0-9]+` ------ ### 建立範例連接器 (AWS CLI) 下列範例 CLI 命令`ConnectorDefinition`會使用包含 Twilio Notifications 連接器的初始版本建立 。 ``` 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 Notifications 連接器新增至群組的教學課程，請參閱 [Greengrass 連接器入門 (CLI)](connectors-cli.md)和 [Greengrass 連接器入門 (主控台)](connectors-console.md)。 ## 輸入資料 此連接器接受兩個 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 連接器入門 (主控台)](connectors-console.md) 和 [Greengrass 連接器入門 (CLI)](connectors-cli.md) 主題包含端對端步驟，說明如何設定、部署和測試 Twilio 通知連接器。 1. 確定您符合連接器的[要求](#twilio-notifications-connector-req)。 1. 建立並發佈 Lambda 函數，將輸入資料傳送至連接器。 將[範例程式碼](#twilio-notifications-connector-usage-example)儲存為 PY 檔案。下載並解壓縮[AWS IoT Greengrass 適用於 Python 的 Core SDK](lambda-functions.md#lambda-sdks-core)。然後，建立在根層級包含 PY 檔案和 `greengrasssdk` 資料夾的 zip 套件。此 zip 套件是您上傳至 的部署套件 AWS Lambda。 建立 Python 3.7 Lambda 函數後，發佈函數版本並建立別名。 1. 設定 Greengrass 群組。 1. 依別名新增 Lambda 函數 （建議）。將 Lambda 生命週期設定為長期 （或在 CLI `"Pinned": true`中）。 1. 新增必要的秘密資源，並授予 Lambda 函數的讀取存取權。 1. 新增連接器並設定其[參數](#twilio-notifications-connector-param)。 1. 新增訂閱，允許連接器在支援主題篩選條件上接收[輸入資料](#twilio-notifications-connector-data-input)並傳送[輸出資料](#twilio-notifications-connector-data-output)。 + 將 Lambda 函數設定為來源，將連接器設定為目標，並使用支援的輸入主題篩選條件。 + 將連接器設為來源、將 AWS IoT Core 設為目標，並使用支援的輸出主題篩選條件。您可以使用此訂閱在 AWS IoT 主控台中檢視狀態訊息。 1. 部署群組。 1. 在 AWS IoT 主控台**的測試**頁面上，訂閱輸出資料主題，以檢視連接器的狀態訊息。Lambda 函數範例為長期函數，並在部署群組後立即開始傳送訊息。 完成測試後，您可以將 Lambda 生命週期設定為隨需 （或在 CLI `"Pinned": false`中） 並部署群組。這會讓函數停止傳送訊息。 ### 範例 下列範例 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 ``` ## 授權 Twilio Notifications 連接器包含下列第三方軟體/授權： + [twilio-python](https://github.com/twilio/twilio-python)/MIT 此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。 ## 變更記錄 下表說明每個版本連接器的變更。 | 版本 | 變更 | | --- | --- | | 5 | 已新增 `IsolationMode` 參數，以設定連接器的容器化模式。 | | 4 | 將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 | | 3 | 可減少過多記錄的修正。 | | 2 | 少量错误修复和改进。 | | 1 | 初始版本。 | Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。 ## 另請參閱 + [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md) + [Greengrass 連接器入門 (主控台)](connectors-console.md) + [Greengrass 連接器入門 (CLI)](connectors-cli.md) + [Twilio API 參考](https://www.twilio.com/docs/api)