支援終止通知：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)。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Greengrass 連接器入門 (CLI)
此功能適用於 AWS IoT Greengrass Core v1.7 和更新版本。
本教學課程說明如何使用 AWS CLI 來使用連接器。
使用連接器來加速您的開發生命週期。連接器是預先建置的、可重複使用的模組，可讓您更輕鬆地與服務、通訊協定和資源互動。它們可協助您更快地將商業邏輯部署到 Greengrass 裝置。如需詳細資訊，請參閱[使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)。
在本教學課程中，您會設定和部署 [ Twilio Notifications](twilio-notifications-connector.md) 連接器。連接器接收 Twilio 訊息資訊做為輸入資料，然後觸發 Twilio 文字訊息。下圖顯示資料流程。
![\[從 Lambda 函數到 Twilio Notifications 連接器到 Twilio 的資料流程。\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/images/connectors/twilio-solution.png)
設定連接器之後，您可以建立 Lambda 函數和訂閱。
+ 此函數會評估來自溫度感應器的模擬資料。它會有條件地將 Twilio 訊息資訊發佈到 MQTT 主題。這是連接器訂閱的主題。
+ 該訂閱允許將函數發佈到主題，也允許連接器從主題接收資料。
Twilio Notifications 連接器需要 Twilio 驗證字符才能與 Twilio API 互動。字符是在 中建立 AWS Secrets Manager 並從群組資源參考的文字類型秘密。這 AWS IoT Greengrass 可讓 在 Greengrass 核心上建立秘密的本機副本，並在其中加密並提供給連接器。如需詳細資訊，請參閱[將秘密部署到 AWS IoT Greengrass 核心](secrets.md)。
本教學課程所述以下高階執行步驟：
1. [建立 Secrets Manager 秘密](#connectors-cli-create-secret)
1. [建立資源定義和版本](#connectors-cli-create-resource-definition)
1. [建立連接器定義和版本](#connectors-cli-create-connector-definition)
1. [建立 Lambda 函數部署套件](#connectors-cli-create-deployment-package)
1. [建立 Lambda 函式](#connectors-cli-create-function)
1. [建立函數定義和版本](#connectors-cli-create-function-definition)
1. [建立訂閱定義和版本](#connectors-cli-create-subscription-definition)
1. [建立群組版本](#connectors-cli-create-group-version)
1. [建立部署](#connectors-cli-create-deployment)
1. [測試解決方案](#connectors-cli-test-solution)
此教學課程需約 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](gg-gs.md)。入門教學課程也包含 AWS IoT Greengrass Core 軟體的安裝步驟。
+ AWS IoT Greengrass 核心裝置上已安裝 Python 3.7。
+ AWS IoT Greengrass 必須設定為支援本機秘密，如[秘密要求](secrets.md#secrets-reqs)中所述。
**注意**
此要求包括允許存取您的 Secrets Manager 秘密。如果您使用預設 Greengrass 服務角色，Greengrass 有權取得名稱開頭為 *greengrass-* 的秘密值。
+ Twilio 帳戶 SID、驗證字符和已啟用 Twilio 的電話號碼。在您建立 Twilio 專案後，您就可在專案儀表板上使用這些值。
**注意**
您可以使用 Twilio 試用帳戶。如果您使用試驗帳戶，則必須將非 Twilio 收件人的電話號碼新增至已驗證的電話號碼清單。如需詳細資訊，請參閱[如何使用您的 免費 Twilio 試用帳戶](https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account)。
+ AWS CLI 在您的電腦上安裝和設定 。如需詳細資訊，請參閱*AWS Command Line Interface 《 使用者指南*》中的[安裝 AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) 和[設定 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)。
此教學課程中的範例是針對 Linux 和其他以 Unix 為基礎的系統所撰寫。如果您使用的是 Windows，請參閱[指定 的參數值 AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html)，以了解語法的差異。
如果命令包含 JSON 字串，教學課程提供的範例會在單行上有 JSON。在某些系統上，使用此格式也許能讓編輯和執行命令更輕鬆。
## 步驟 1：建立 Secrets Manager 秘密
在此步驟中，您會使用 AWS Secrets Manager API 為您的 Twilio 驗證字符建立秘密。
1. 首先，建立私密。
+ 將 *twilio-auth-token* 換成您的驗證字符。
```
aws secretsmanager create-secret --name greengrass-TwilioAuthToken --secret-string twilio-auth-token
```
**注意**
根據預設，Greengrass 服務角色允許 AWS IoT Greengrass 取得名稱開頭為 *greengrass-* 的秘密值。如需詳細資訊，請參閱[私密需求](secrets.md#secrets-reqs)。
1. 從輸出複製私密的 `ARN`。您可以使用它來建立秘密資源，並設定 Twilio Notifications 連接器。
## 步驟 2：建立資源定義和版本
在此步驟中，您會使用 AWS IoT Greengrass API 來建立 Secrets Manager 秘密的秘密資源。
1. 建立包含最初版本的資源定義。
+ 將 *secret-arn* 換成您在上一步複製的私密 `ARN`。
------
#### [ 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"}}}]}'
```
------
1. 從輸出複製資源定義的 `LatestVersionArn`。您可以使用這個值，將資源定義版本新增至您部署到核心的群組版本。
## 步驟 3：建立連接器定義和版本
在此步驟中，您會設定 Twilio Notifications 連接器的參數。
1. 建立含有最初版本的連接器定義。
+ 將 *account-sid* 換成您的 Twilio 帳戶 SID。
+ 使用 *Secrets Manager 秘密的 取代 secret-arn*。 `ARN`連接器使用此 ARN 取得本機私密的值。
+ 將 *phone-number* 換成已啟用 Twilio 的電話號碼。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。
1. 從輸出複製連接器定義的 `LatestVersionArn`。您可以使用這個值，將連接器定義版本新增至您部署到核心的群組版本。
## 步驟 4：建立 Lambda 函數部署套件
若要建立 Lambda 函數，您必須先建立包含函數程式碼和相依性的 Lambda 函數*部署套件*。Greengrass Lambda 函數需要 [AWS IoT Greengrass 核心 SDK](lambda-functions.md#lambda-sdks-core) 來處理任務，例如與核心環境中的 MQTT 訊息通訊，以及存取本機秘密。本教學課程會建立 Python 函數，因此您可以在部署套件中使用 SDK 的 Python 版本。
1. 從[AWS IoT Greengrass 核心開發套件](what-is-gg.md#gg-core-sdk-download)下載頁面，將適用於 Python AWS IoT Greengrass 的核心開發套件下載至您的電腦。
1. 解壓縮下載的封裝，以取得軟體開發套件。SDK 為 `greengrasssdk` 資料夾。
1. 將以下 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))
}
```
1. 將下列項目壓縮成名為 `temp_monitor_python.zip` 的檔案。建立 ZIP 檔案時，只包含程式碼及其依存項目，而不包含資料夾。
+ **temp\$1monitor.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"}]}'
```
------
**注意**
AWS IoT Greengrass 不會使用此角色，因為 Greengrass Lambda 函數的許可是在 Greengrass 群組角色中指定。本教學課程將建立空白角色。
1. 從輸出複製 `Arn`。
1. 使用 AWS Lambda API 建立 TempMonitor 函數。以下命令假設 zip 檔是在目前的目錄。
+ 將 *role-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
```
1. 發佈函數的一個版本。
```
aws lambda publish-version --function-name TempMonitor --description 'First version'
```
1. 建立發佈版本的別名。
Greengrass 群組可以依別名 （建議） 或版本參考 Lambda 函數。使用別名可讓您更輕鬆地管理程式碼更新，因為您不必在更新函數程式碼時變更訂閱資料表或群組定義。反之，您只需將別名指向新的函數版本。
**注意**
AWS IoT Greengrass 不支援 **\$1LATEST** 版本的 Lambda 別名。
```
aws lambda create-alias --function-name TempMonitor --name GG_TempMonitor --function-version 1
```
1. 從輸出複製 `AliasArn`。當您為 設定 函數時 AWS IoT Greengrass ，以及在建立訂閱時，您會使用此值。
現在您已準備好設定 的 函數 AWS IoT Greengrass。
## 步驟 6：建立函數定義和版本
若要在 AWS IoT Greengrass 核心上使用 Lambda 函數，您可以建立以別名參考 Lambda 函數的函數定義版本，並定義群組層級組態。如需詳細資訊，請參閱[使用群組特定的組態控制 Greengrass Lambda 函數的執行](lambda-group-config.md)。
1. 建立包含最初版本的函數定義。
+ 將 *alias-arn* 換成您建立別名時所複製的 `AliasArn`。
------
#### [ 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}}]}'
```
------
1. 從輸出複製 `LatestVersionArn`。您可以使用這個值，將函數定義版本新增至您部署到核心的群組版本。
1. 從輸出複製 `Id`。稍後更新函數時，您會使用這個值。
## 步驟 7：建立訂閱定義和版本
在此步驟中，您會新增訂閱，讓 Lambda 函數將輸入資料傳送至連接器。連接器定義它所訂閱的 MQTT 主題，所以這個訂閱使用其中一個主題。這是範例函數發佈到的同一個主題。
在本教學課程中，您也會建立訂閱，允許函數接收來自 AWS IoT 的模擬溫度讀數 AWS IoT ，並允許 從連接器接收狀態資訊。
1. 建立包含最初版本的訂閱定義，而此版本包含訂閱。
+ 將 *alias-arn* 換成您為函數建立別名時所複製的 `AliasArn`。對用到它的兩個訂閱都使用此 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"}]}'
```
------
1. 從輸出複製 `LatestVersionArn`。您可以使用這個值，將訂閱定義版本新增至您部署到核心的群組版本。
## 步驟 8：建立群組版本
現在，您可以開始建立群組版本，其中包含您要部署的所有項目。若要這樣做，您需要建立群組版本來參考每個元件類型的目標版本。
首先，取得核心定義版本的群組 ID 和 ARN。建立群組版本需要這些值。
1. 獲取群組 ID 和最新群組版本：
1. 取得目標 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 (設定)** 頁面上。群組版本 IDs會顯示在群組的**部署**索引標籤上。
1. 從輸出複製目標群組的 `Id`。部署群組時，您可以使用此 ID 取得核心定義版本。
1. 從輸出複製 `LatestVersion`，這是新增至群組的最新版本 ID。您可以使用此取得核心定義版本。
1. 取得核心定義版本的 ARN：
1. 取得群組版本。在此步驟中，我們假設最新的群組版本包含核心定義版本。
+ 將 *group-id* 取代為您為群組所複製的 `Id`。
+ 將 *group-version-id* 換成您為群組所複製的 `LatestVersion`。
```
aws greengrass get-group-version \
--group-id group-id \
--group-version-id group-version-id
```
1. 從輸出複製 `CoreDefinitionVersionArn`。
1. 建立群組版本。
+ 將 *group-id* 取代為您為群組所複製的 `Id`。
+ 將 *core-definition-version-arn* 換成您為核心定義版本所複製的 `CoreDefinitionVersionArn`。
+ 將 *resource-definition-version-arn* 換成您為資源定義所複製的 `LatestVersionArn`。
+ 將 *connector-definition-version-arn* 換成您為連接器定義所複製的 `LatestVersionArn`。
+ 將 *function-definition-version-arn* 換成您為函數定義所複製的 `LatestVersionArn`。
+ 將 *subscription-definition-version-arn* 換成您為訂閱定義所複製的 `LatestVersionArn`。
```
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
```
1. 複製輸出中的 `Version` 值。這是群組版本的 ID。您可以使用這個值來部署群組版本。
## 步驟 9：建立部署
將群組部署到核心裝置。
1. 在核心裝置終端機中，確定 AWS IoT Greengrass 協助程式正在執行。
1. 檢查精靈是否有在運作：
```
ps aux | grep -E 'greengrass.*daemon'
```
若輸出的 `root` 含有 `/greengrass/ggc/packages/1.11.6/bin/daemon` 項目，則精靈有在運作。
1. 若要啟動協助程式：
```
cd /greengrass/ggc/core/
sudo ./greengrassd start
```
1. 建立 部署。
+ 將 *group-id* 取代為您為群組所複製的 `Id`。
+ 將 *group-version-id* 取代為您為新群組版本所複製的 `Version`。
```
aws greengrass create-deployment \
--deployment-type NewDeployment \
--group-id group-id \
--group-version-id group-version-id
```
1. 從輸出複製 `DeploymentId`。
1. 取得部署狀態。
+ 將 *group-id* 取代為您為群組所複製的 `Id`。
+ 將 *deployment-id* 換成您為部署所複製的 `DeploymentId`。
```
aws greengrass get-deployment-status \
--group-id group-id \
--deployment-id deployment-id
```
如果狀態為 `Success`，則部署成功。如需故障診斷協助，請參閱[故障診斷 AWS IoT Greengrass](gg-troubleshooting.md)。
## 測試解決方案
1. 在 AWS IoT 主控台首頁上，選擇**測試**。
1. 對於**訂閱主題**，請使用下列值，然後選擇**訂閱**。Twilio Notifications 連接器會將狀態資訊發佈至此主題。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-cli.html)
1. 針對**發佈至主題**，請使用下列值，然後選擇**發佈**以叫用函數。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-cli.html)
如果成功，收件人會收到文字訊息，而主控台會顯示來自[輸出資料](twilio-notifications-connector.md#twilio-notifications-connector-data-output)`success`的狀態。
現在，將輸入訊息中的 `temperature` 變更為 **29** 並發佈。由於此值小於 30，TempMonitor 函數不會觸發 Twilio 訊息。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [AWS提供的 Greengrass 連接器](connectors-list.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [AWS Secrets Manager 命令](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager)*AWS CLI 參考中的 命令*
+ 《 [AWS Identity and Access Management 命令參考》中的 (IAM)](https://docs.aws.amazon.com/cli/latest/reference/iam) *AWS CLI 命令*
+ [AWS Lambda 命令](https://docs.aws.amazon.com/cli/latest/reference/lambda)*AWS CLI 參考中的 命令*
+ [AWS IoT Greengrass 命令](https://docs.aws.amazon.com/cli/latest/reference/greengrass/index.html)*AWS CLI 參考中的 命令*