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核心 v1.7 及更高版本。
此教學課程示範如何透過 AWS CLI 使用連接器。
使用連接器來加速您的開發生命週期。連接器是預先建置的、可重複使用的模組,可讓您更輕鬆地與服務、通訊協定和資源互動。它們可協助您更快地將商業邏輯部署到 Greengrass 裝置。如需詳細資訊,請參閱 使用 Greengrass 連接器來整合服務和通訊協定。
在此教學課程中,您將設定和部署Twilio 通知連接器。連接器接收 Twilio 訊息資訊做為輸入資料,然後觸發 Twilio 文字訊息。下圖顯示資料流程。
![從 Lambda 函數到 Twilio 通知連接器到 Twilio 的資料流程。](images/connectors/twilio-solution.png)
設定連接器之後,您將建立 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 可讓您為一個元件類型建立多個定義。例如,您可以在每次建立 FunctionDefinitionVersion
時建立 FunctionDefinition
物件,或者您可以將新版本新增到現有的定義。這種彈性可讓您自訂版本管理系統。
先決條件
為完成此教學課程您需要:
-
Greengrass 群組和 Greengrass 核心 (1.9.3 版或更新版本)。若要了解如何建立 Greengrass 群組或核心,請參閱 開始使用 AWS IoT Greengrass。入門教學課程也包含 AWS IoT Greengrass Core 軟體的安裝步驟。
-
安裝在 AWS IoT Greengrass 核心裝置上的 Python 3.7。
-
AWS IoT Greengrass必須設定為支援本機私密,如中所述Secrets 要求。
注意
這項要求包括允許存取 Secrets Manager 秘密。如果您使用的是預設 Greengrass 服務角色,Greengrass 有許可取得名稱開頭為之私密值的許可greengrass。
-
Twilio 帳戶 SID、驗證字符和已啟用 Twilio 的電話號碼。在您建立 Twilio 專案後,您就可在專案儀表板上使用這些值。
注意
您可以使用 Twilio 試用帳戶。如果您使用的是試用帳戶,則必須將非 Twilio 收件人電話號碼新增到已驗證的電話號碼清單中。如需詳細資訊,請參閱「」如何使用您的免費 Twilio 試用帳戶
。
-
在您的電腦上安裝和設定的 AWS CLI。如需詳細資訊,請參閱「」安裝AWS Command Line Interface和設定AWS CLI中的AWS Command Line Interface使用者指南。
此教學課程中的範例是針對 Linux 和其他以 Unix 為基礎的系統所撰寫。如果您使用的是 Windows,請參閱為 指定參數值AWS Command Line Interface以了解語法上的差異。
如果命令包含 JSON 字串,教學課程提供的範例會在單行上有 JSON。在某些系統上,使用此格式也許能讓編輯和執行命令更輕鬆。
步驟 1:建立 Secrets Manager 秘密
在此步驟中,您將使用 AWS Secrets Manager API 建立 Twilio 驗證字符的私密。
-
首先,建立私密。
Replace
twilio-auth-token
使用您的 Twilio auth token 換成您的驗證字符。
aws secretsmanager create-secret --name greengrass-TwilioAuthToken --secret-string
twilio-auth-token
注意
預設情況下,Greengrass 服務角色允許AWS IoT Greengrass獲得 Secrets name 開頭的秘密的價值greengrass。如需詳細資訊,請參閱私密需求。
-
從輸出複製私密的
ARN
。您可以使用此 ARN 來建立私密資源和設定 Twilio 通知連接器。
步驟 2:建立資源定義和版本
在此步驟中,您會使用AWS IoT GreengrassAPI 為 Secrets Manager 秘密建立私密資源。
-
建立包含最初版本的資源定義。
將
secret-arn
換成您在上一步複製的私密ARN
。
從輸出複製資源定義的
LatestVersionArn
。您可以使用這個值,將資源定義版本新增至您部署到核心的群組版本。
步驟 3:建立連接器定義和版本
在此步驟中,您將設定 Twilio 通知連接器的參數。
-
建立含有最初版本的連接器定義。
將
account-sid
換成您的 Twilio 帳戶 SID。Replace
秘密阿恩
與ARN
您 Secrets Manager 秘密。連接器使用此 ARN 取得本機私密的值。將
phone-number
換成已啟用 Twilio 的電話號碼。Twilio 以此啟動文字訊息。這可在輸入訊息承載中覆寫。使用下列格式:+19999999999
。
注意
TwilioAuthToken
是您在上一步中用來建立私密資源的 ID。 從輸出複製連接器定義的
LatestVersionArn
。您可以使用這個值,將連接器定義版本新增至您部署到核心的群組版本。
步驟 4:建立 Lambda 函數部署套件
若要建立 Lambda 函數,您必須先建立 Lambda 函數部署套件包含函數程式碼和相依性。Greengrass · Lambda 函數需要AWS IoT Greengrass核心開發套件用於任務,例如在核心環境中與 MQTT 消息進行通信以及訪問本地機密。本教程創建了一個 Python 函數,因此您可以在部署包中使用 SDK 的 Python 版本。
-
來自AWS IoT Greengrass核心開發套件下載頁面,下載AWS IoT Greengrass適用於 Python 的核心 SDK 到您的計算機。
-
解壓縮下載的封裝,以取得軟體開發套件。SDK 為
greengrasssdk
資料夾。 -
將以下 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)) }
-
將下列項目壓縮成名為
temp_monitor_python.zip
的檔案。建立 ZIP 檔案時,只包含程式碼及其依存項目,而不包含資料夾。-
temp_monitor.py。應用程式邏輯。
-
greengrasssdk。適用於發佈 MQTT 訊息之 Python Greengrass Lambda 函數所需的程式庫。
這是您的 Lambda 函數部署套件。
-
步驟 5:建立 Lambda 函數
現在,建立一個使用部署套件的 Lambda 函數。
-
建立 IAM 角色,供您建立函數時傳入角色 ARN 中。
注意
AWS IoT Greengrass不使用此角色,因為函數的許可是在 Greengrass 群組角色中指定。本教學課程將建立空白角色。
-
從輸出複製
Arn
。 -
使用AWS LambdaAPI 來建立 TempMonitor 函數。以下命令假設 zip 檔是在目前的目錄。
Replace
角色 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 -
發佈函數的一個版本。
aws lambda publish-version --function-name TempMonitor --description 'First version'
-
建立發佈版本的別名。
Greengrass 組可以通過別名(推薦)或版本引用 Lambda 函數。使用別名可讓您更輕鬆地管理程式碼更新,因為當函數程式碼更新時,您不需要變更訂閱資料表或群組定義。相反,您只需將別名指向新函數版本即可。
注意
AWS IoT Greengrass不支援 Lambda 別名$LATEST版本。
aws lambda create-alias --function-name TempMonitor --name GG_TempMonitor --function-version 1
-
從輸出複製
AliasArn
。當您為 AWS IoT Greengrass 設定函數和建立訂閱時,您會使用這個值。
現在,您可以開始為 AWS IoT Greengrass 設定函數。
步驟 6:建立函數定義和版本
若要在某個項目上使用 Lambda 函數AWS IoT Greengrass核心,您建立函數定義版本來依別名參考 Lambda 函數,並定義群組層級組態。如需詳細資訊,請參閱 使用群組特定組態來控制 Greengrass Lambda 函數的執行。
-
建立包含最初版本的函數定義。
將
alias-arn
換成您建立別名時所複製的AliasArn
。
從輸出複製
LatestVersionArn
。您可以使用這個值,將函數定義版本新增至您部署到核心的群組版本。從輸出複製
Id
。稍後更新函數時,您會使用這個值。
步驟 7:建立訂閱定義和版本
在此步驟中,您新增訂閱讓 Lambda 函數將輸入資料傳送到連接器。連接器定義它所訂閱的 MQTT 主題,所以這個訂閱使用其中一個主題。這是範例函數發佈到的同一個主題。
在本教學課程中,您也可以建立訂閱,以允許該函數從 AWS IoT 接收模擬溫度讀數,並允許 AWS IoT 從連接器接收狀態資訊。
-
建立包含最初版本的訂閱定義,而此版本包含訂閱。
將
alias-arn
換成您為函數建立別名時所複製的AliasArn
。對用到它的兩個訂閱都使用此 ARN。
從輸出複製
LatestVersionArn
。您可以使用這個值,將訂閱定義版本新增至您部署到核心的群組版本。
步驟 8:建立群組版本
現在,您可以開始建立群組版本,其中包含您要部署的所有項目。若要這樣做,您需要建立群組版本來參考每個元件類型的目標版本。
首先,取得核心定義版本的群組 ID 和 ARN。建立群組版本需要這些值。
-
獲取群組 ID 和最新群組版本:
-
取得目標 Greengrass 群組 ID 和目標群組版本 ID。此程序假設這是最新的群組和群組版本。以下查詢會傳回最近建立的群組。
aws greengrass list-groups --query "reverse(sort_by(Groups, &CreationTimestamp))[0]"
或者,您可以依名稱查詢。群組名稱不需要是唯一名稱,因此可能會傳回多個群組。
aws greengrass list-groups --query "Groups[?Name=='
MyGroup
']"注意
您也可以在中尋找這些值AWS IoT主控台。群組 ID 會顯示在群組的 Settings (設定) 頁面上。群組版本 ID 會顯示在群組上部署索引標籤。
-
從輸出複製目標群組的
Id
。部署群組時,您可以使用此 ID 取得核心定義版本。 -
從輸出複製
LatestVersion
,這是新增至群組的最新版本 ID。您可以使用此取得核心定義版本。
-
-
取得核心定義版本的 ARN:
取得群組版本。在此步驟中,我們假設最新的群組版本包含核心定義版本。
將
group-id
取代為您為群組所複製的Id
。Replace
group-version-id
與LatestVersion
您為群組複製的。
aws greengrass get-group-version \ --group-id
group-id
\ --group-version-idgroup-version-id
從輸出複製
CoreDefinitionVersionArn
。
-
建立群組版本。
將
group-id
取代為您為群組所複製的Id
。Replace
core-definition-version-arn
與CoreDefinitionVersionArn
您為核心定義版本複製的。Replace
resource-definition-version-arn
與LatestVersionArn
您為資源定義所複製的。Replace
connector-definition-version-arn
與LatestVersionArn
您為連接器定義所複製的。Replace
function-definition-version-arn
與LatestVersionArn
您為函數定義所複製的。Replace
subscription-definition-version-arn
與LatestVersionArn
您為 Subscribe (訂閱定義所複製的)。
aws greengrass create-group-version \ --group-id
group-id
\ --core-definition-version-arncore-definition-version-arn
\ --resource-definition-version-arnresource-definition-version-arn
\ --connector-definition-version-arnconnector-definition-version-arn
\ --function-definition-version-arnfunction-definition-version-arn
\ --subscription-definition-version-arnsubscription-definition-version-arn
複製輸出中的
Version
值。這是群組版本的 ID。您可以使用這個值來部署群組版本。
步驟 9:建立部署
將群組部署到核心裝置。
-
在核心裝置終端機,請確定 AWS IoT Greengrass 協助程式正在執行。
檢查精靈是否有在運作:
ps aux | grep -E 'greengrass.*daemon'
若輸出的
root
含有/greengrass/ggc/packages/1.11.6/bin/daemon
項目,則精靈有在運作。若要啟動協助程式:
cd /greengrass/ggc/core/ sudo ./greengrassd start
-
建立部署。
將
group-id
取代為您為群組所複製的Id
。Replace
group-version-id
與Version
您為新群組版本複製的。
aws greengrass create-deployment \ --deployment-type NewDeployment \ --group-id
group-id
\ --group-version-idgroup-version-id
-
從輸出複製
DeploymentId
。 -
取得部署狀態。
將
group-id
取代為您為群組所複製的Id
。將
deployment-id
換成您為部署所複製的DeploymentId
。
aws greengrass get-deployment-status \ --group-id
group-id
\ --deployment-iddeployment-id
如果狀態為
Success
,部署成功。如需故障診斷協助,請參閱AWS IoT Greengrass 疑難排解。
測試解決方案
-
在「」AWS IoT主控台首頁,請選擇測試。
-
適用於訂閱主題,請使用以下數值,然後選擇訂閱。Twilio 通知連接器將狀態資訊發佈到該主題。
屬性
數值
訂閱主題
twilio/message/status
MQTT 承載顯示
將承載顯示為字串
-
適用於發佈到主題,請使用以下數值,然後選擇發布叫用函數。
屬性
數值
主題
temperature/input
Message
Replace
收件人姓名
用一個名稱和recipient-phone-number
含文字訊息收件人的電話號碼。範例:+12345000000
{ "to_name": "
recipient-name
", "to_number": "recipient-phone-number
", "temperature": 31 }如果您使用的是試用帳戶,則必須將非 Twilio 收件人電話號碼新增到已驗證的電話號碼清單中。如需詳細資訊,請參閱「」驗證您的個人電話號碼
。 如果成功,收件者將收到文字訊息,主控台會顯示
success
狀態來自輸出資料。現在,將輸入訊息中的
temperature
變更為29
並發佈。因為這是小於 30, TempMonitor 函數不會觸發 Twilio 訊息。
另請參閱
-
AWS Secrets Manager命令中的AWS CLI命令參考
-
AWS Identity and Access Management(IAM) 指令中的AWS CLI命令參考
-
AWS Lambda命令中的AWS CLI命令參考
-
AWS IoT Greengrass命令中的AWS CLI命令參考