支援終止通知：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 連接器來整合服務和通訊協定
此功能適用於 AWS IoT Greengrass Core v1.7 和更新版本。
中的連接器 AWS IoT Greengrass 是預先建置的模組，可讓您更有效率地與本機基礎設施 AWS、裝置通訊協定和其他雲端服務互動。透過使用連接器，您可以花較少的時間學習新的通訊協定和 APIs並有更多時間專注於對您業務至關重要的邏輯。
下圖顯示連接器可以適應 AWS IoT Greengrass 環境的位置。
![\[連接器連接到裝置、服務和本機資源。\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/images/connectors/connectors-arch.png)
許多連接器使用 MQTT 訊息與群組中的用戶端裝置和 Greengrass Lambda 函數，或與 AWS IoT 和本機影子服務通訊。在下列範例中，Twilio Notifications 連接器會從使用者定義的 Lambda 函數接收 MQTT 訊息、使用來自秘密的本機參考 AWS Secrets Manager，並呼叫 Twilio API。
![\[從 Lambda 函數接收 MQTT 訊息並呼叫服務的連接器。\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/images/connectors/twilio-solution.png)
如需建立此解決方案的教學課程，請參閱 [Greengrass 連接器入門 (主控台)](connectors-console.md) 和 [Greengrass 連接器入門 (CLI)](connectors-cli.md)。
Greengrass 連接器可協助您擴展裝置功能或建立單一用途裝置。透過使用連接器，您可以：
+ 實作可重複使用的商業邏輯。
+ 與雲端和本機服務互動，包括 AWS 和第三方服務。
+ 擷取和處理裝置資料。
+ 使用 MQTT 主題訂閱和使用者定義的 Lambda 函數啟用device-to-device呼叫。
AWS 提供一組 Greengrass 連接器，可簡化與常見服務和資料來源的互動。這些預先建置的模組可提供記錄和診斷、補充、產業資料處理及警示和簡訊的案例。如需詳細資訊，請參閱[AWS提供的 Greengrass 連接器](connectors-list.md)。
## 需求
若要使用連接器，請謹記以下幾點：
+ 您使用的每個連接器都有您必須符合的要求。這些要求可能包括最低 AWS IoT Greengrass Core 軟體版本、裝置先決條件、必要的許可和限制。如需詳細資訊，請參閱[AWS提供的 Greengrass 連接器](connectors-list.md)。
+ Greengrass 群組只能包含指定連接器的一個已設定執行個體。不過，您可以在多個訂閱中使用執行個體。如需詳細資訊，請參閱[組態參數](#connectors-parameters)。
+ 當 Greengrass 群組的預設容器化設定為 [No container (無容器)](lambda-group-config.md#lambda-containerization-groupsettings) 時，群組中的**連接器**必須在沒有容器化的情況下執行。若要尋找支援 **No container (無容器)** 模式的連接器，請參閱 [AWS提供的 Greengrass 連接器](connectors-list.md)。
## 使用 Greengrass 連接器
連接器是一種群組元件。與其他群組元件一樣，例如用戶端裝置和使用者定義的 Lambda 函數，您可以將連接器新增至群組、設定其設定，並將它們部署到 AWS IoT Greengrass 核心。連接器在核心環境中執行。
您可以將某些連接器部署為簡單的獨立應用程式。例如，Device Defender 連接器會從核心裝置讀取系統指標，並將其傳送至 AWS IoT Device Defender 進行分析。
您可以在較大的解決方案中新增其他連接器做為建置區塊。下列範例解決方案使用 Modbus-RTU 通訊協定轉接器連接器來處理來自感應器的訊息，並使用 Twilio Notifications 連接器啟動 Twilio 訊息。
![\[從 Lambda 函數到 Modbus-RTU 通訊協定轉接器連接器到 Lambda 函數到 Twilio Notifications 連接器到 Twilio 的資料流程。\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/images/connectors/modbus-twilio-solution.png)
解決方案通常包含使用者定義的 Lambda 函數，這些函數位於連接器旁邊，並處理連接器傳送或接收的資料。在此範例中，TempMonitor 函數會從 Modbus-RTU 通訊協定轉接器接收資料、執行一些商業邏輯，然後將資料傳送至 Twilio Notifications。
若要建立和部署解決方案，請依照此一般程序：
1. 規劃高階資料流程。識別您需要使用的資料來源、資料管道、服務、通訊協定和資源。在範例解決方案中，這包括經過 Modbus RTU 通訊協定、實體 Modbus 序列埠和 Twilio 的資料。
1. 識別要在解決方案中包含的連接器，並將其新增到群組。範例解決方案使用 Modbus-RTU 通訊協定轉接器和 Twilio Notifications。為了協助尋找適用您情境的連接器並了解其個別要求，請參閱 [AWS提供的 Greengrass 連接器](connectors-list.md)。
1. 識別是否需要使用者定義的 Lambda 函數、用戶端裝置或資源，然後建立它們並將其新增至群組。這可能包括包含了商業邏輯的函數，或將資料處理成解決方案中另一個實體所需的格式。範例解決方案使用 函數傳送 Modbus RTU 請求並啟動 Twilio 通知。此外也包含 Modbus RTU 序列埠的本機裝置資源和 Twilio 驗證字符的私密資源。
**注意**
私密資源會參考來自 AWS Secrets Manager的密碼、字符和其他私密。連接器和 Lambda 函數可以使用秘密來驗證 服務和應用程式。根據預設， AWS IoT Greengrass 可以存取名稱開頭為 "*greengrass-*" 的秘密。如需詳細資訊，請參閱[將秘密部署到 AWS IoT Greengrass 核心](secrets.md)。
1. 建立訂閱以允許解決方案中的實體交換 MQTT 訊息。若訂閱中使用連接器，則連接器和訊息來源或目標必須使用連接器支援的預先定義主題語法。如需詳細資訊，請參閱[輸入和輸出](#connectors-inputs-outputs)。
1. 將群組部署至 Greengrass 核心。
如需有關建立和部署連接器的資訊，請參閱下列教學課程：
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
## 組態參數
許多連接器會提供參數讓您自訂行為或輸出。這些參數用於連接器生命週期的初始化期間、執行時間或其他時間。
參數類型和用法依連接器而有不同。例如，SNS 連接器具有設定預設 SNS 主題的參數，而 Device Defender 具有設定資料取樣率的參數。
一個群組版本可以包含多個連接器，但特定連接器一次只能有一個執行個體。這表示群組中的每個連接器都僅會有一個作用中的組態。然而，連接器執行個體可在群組中的多個訂閱中使用。例如，您可以建立訂閱，允許許多裝置將資料傳送至 Kinesis Firehose 連接器。
### 用於存取群組資源的參數
Greengrass 連接器使用群組資源存取核心裝置上的檔案系統、連接埠、周邊設備和其他本機資源。如果連接器需要存取群組資源，則會提供相關的組態參數。
群組資源包括：
+ [本機資源](access-local-resources.md)。Greengrass 核心裝置上存在的目錄、檔案、連接埠、接腳和周邊設備。
+ [機器學習資源](ml-inference.md)。在雲端中訓練並部署至核心的機器學習模型，用於本機推論。
+ [私密資源](secrets.md)。密碼、金鑰、字符或任意文字的本機加密副本 AWS Secrets Manager。連接器可以安全地存取這些本機私密，並使用它們來向服務或本機基礎設施進行驗證。
例如，Device Defender 的參數可讓您存取主機`/proc`目錄中的系統指標，而 Twilio Notifications 的參數可讓您存取本機儲存的 Twilio 身分驗證字符。
### 更新連接器參數
參數是在連接器新增到 Greengrass 群組時設定。新增連接器之後，您可以變更參數值。
+ 在主控台中：從群組組態頁面，開啟 **Connectors (連接器)**，並從連接器的內容選單選擇 **Edit (編輯)**。
**注意**
如果連接器使用的私密資源後來變更為參考不同的私密，則您必須編輯連接器的參數並確認變更。
+ 在 API 中：建立連接器的另一個版本來定義新組態。
AWS IoT Greengrass API 使用版本來管理群組。版本不可變，因此若要新增或變更群組元件，例如群組的用戶端裝置、函數和資源，您必須建立新的或更新的元件版本。然後，您可以建立和部署包含每個元件目標版本的群組版本。
變更連接器組態後，您必須部署群組，以將變更傳播至核心。
## 輸入和輸出
許多 Greengrass 連接器可藉由傳送和接收 MQTT 訊息與其他實體通訊。MQTT 通訊是由允許連接器與 Greengrass 群組中的 Lambda 函數、用戶端裝置和其他連接器，或與 AWS IoT 和本機影子服務交換資料的訂閱所控制。若要允許此通訊，您必須在連接器所屬的群組中建立訂閱。如需詳細資訊，請參閱[MQTT 簡訊工作流程中的受管訂閱](gg-sec.md#gg-msg-workflow)。
連接器可以是訊息發佈者、訊息訂閱者或兩者。每個連接器都會定義其發佈或訂閱的 MQTT 主題。這些預先定義的主題必須在連接器是訊息來源或訊息目標的訂閱中使用。如需包括為連接器設定訂閱之步驟的教學課程，請參閱 [Greengrass 連接器入門 (主控台)](connectors-console.md) 和 [Greengrass 連接器入門 (CLI)](connectors-cli.md)。
**注意**
許多連接器也有內建的通訊模式可以與雲端或本機服務互動。這些會隨著連接器而有不同，可能需要您設定參數或將許可新增到[群組角色](group-role.md)。如需連接器要求的相關資訊，請參閱 [AWS提供的 Greengrass 連接器](connectors-list.md)。
### 輸入主題
大多數連接器會接收 MQTT 主題的輸入資料。有些連接器會訂閱輸入資料的多個主題。例如，序列串流連接器支援兩個主題：
+ `serial/+/read/#`
+ `serial/+/write/#`
針對此連接器，讀取和寫入請求會傳送至對應的主題。建立訂閱時，務必使用適用於實作的主題。
前述範例中的 `+` 和 `#` 字元是萬用字元。這些萬用字元可讓訂閱者在多個主題上接收訊息，並可讓發佈者自訂他們發佈到的主題。
+ `+` 萬用字元可出現在主題階層的任意處。這可替換成一個階層項目。
例如，針對 `sensor/+/input` 主題，訊息可以發佈到 `sensor/id-123/input` 主題，但不能發佈到 `sensor/group-a/id-123/input`。
+ `#` 萬用字元只能出現在主題階層的結尾。這可替換為零或多個階層。
例合，針對 `sensor/#` 主題，訊息可以發佈到 `sensor/`、`sensor/id-123` 和 `sensor/group-a/id-123`，但不能發佈到 `sensor`。
只有在訂閱主題時，萬用字元才有效。無法將訊息發佈到包含萬用字元的主題。如需連接器輸入或輸出主題需求的詳細資訊，請參閱連接器的文件。如需詳細資訊，請參閱[AWS提供的 Greengrass 連接器](connectors-list.md)。
## 容器化支援
根據預設，大部分的連接器會在由 AWS IoT Greengrass管理之隔離執行階段環境中的 Greengrass 核心上執行。這些執行階段環境稱為*容器*，可在連接器與主機系統之間提供隔離，為主機與連接器提供更高的安全性。
不過，在某些環境中不支援此 Greengrass 容器化，例如當您 AWS IoT Greengrass 在 Docker 容器或沒有 cgroup 的較舊 Linux 核心上執行時。在這些環境中，連接器必須以 **No container (無容器)** 模式執行。若要尋找支援 **No container (無容器)** 模式的連接器，請參閱 [AWS提供的 Greengrass 連接器](connectors-list.md)。有些連接器會以此模式原生執行，而有些連接器可讓您設定隔離模式。
在支援 Greengrass 容器化的環境中，您也可以將隔離模式設定為 **No container (無容器)**，但我們建議盡可能使用 **Greengrass container (Greengrass 容器)** 模式。
**注意**
Greengrass 群組的預設容器化設定不適用於[連接器](lambda-group-config.md#lambda-containerization-groupsettings)。
## 升級連接器版本
連接器提供者可能會發佈新增功能、修正問題或改善效能的新版連接器。如需可用版本和相關變更的資訊，請參閱[每個連接器的文件](connectors-list.md)。
在 AWS IoT 主控台中，您可以檢查 Greengrass 群組中連接器的新版本。
1. 在 AWS IoT 主控台導覽窗格的**管理**下，展開 **Greengrass 裝置**，然後選擇**群組 (V1)**。
1. 在 **Greengrass 群組**下，選擇您的群組。
1. 選擇 **Connectors (連接器)** 以顯示群組中的連接器。
如果連接器有新版本，**則升級**欄中會顯示**可用**按鈕。
1. 若要升級連接器版本：
1. 在 **Connectors (連接器)** 頁面的 **Upgrade (升級)** 欄中，選擇 **Available (可用)**。**Upgrade connector (升級連接器)** 頁面隨即開啟，並顯示目前的參數設定 (若適用)。
選擇新的連接器版本，視需要定義參數，然後選擇 **Upgrade (升級)**。
1. 在 **Subscriptions (訂閱)** 頁面上，在群組中新增新訂閱，以取代使用連接器做為來源或目標的任何訂閱。然後，移除舊訂閱。
訂閱會根據版本參考連接器，因此如果您變更群組中的連接器版本，訂閱則會變成無效。
1. 從 **Actions (動作)** 功能表中，選擇 **Deploy (部署)** 以將變更部署至核心。
若要從 AWS IoT Greengrass API 升級連接器，請建立並部署包含已更新連接器和訂閱的群組版本。使用與將連接器新增至群組相同的程序。如需示範如何使用 AWS CLI 來設定和部署範例 Twilio Notifications 連接器的詳細步驟，請參閱 [Greengrass 連接器入門 (CLI)](connectors-cli.md)。
## 連接器的記錄
Greengrass 連接器包含 Lambda 函數，可將事件和錯誤寫入 Greengrass 日誌。根據您的群組設定，日誌會寫入 CloudWatch Logs、本機檔案系統或兩者。來自連接器的日誌包含對應函數的 ARN。下列範例 ARN 來自 Kinesis Firehose 連接器：
```
arn:aws:lambda:aws-region:account-id:function:KinesisFirehoseClient:1
```
預設記錄組態使用以下目錄結構，將資訊層級日誌寫入檔案系統：
```
greengrass-root/ggc/var/log/user/region/aws/function-name.log
```
如需 Greengrass 記錄的詳細資訊，請參閱 [使用 AWS IoT Greengrass 日誌監控](greengrass-logs-overview.md)。
# AWS提供的 Greengrass 連接器
AWS 提供下列支援常見 AWS IoT Greengrass 案例的連接器。如需連接器如何運作的詳細資訊，請參閱下列文件：
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [連接器入門 (主控台)](connectors-console.md) 或 [連接器入門 (CLI)](connectors-cli.md)
| 連接器 | 描述 | 支援的 Lambda 執行時間 | 支援 **No container (無容器)** 模式 |
| --- | --- | --- | --- |
| [CloudWatch 指標](cloudwatch-metrics-connector.md) | 將自訂指標發佈至 Amazon CloudWatch。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 是 |
| [Device Defender](device-defender-connector.md) | 傳送系統指標至 AWS IoT Device Defender。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 否 |
| [Docker 應用程式部署](docker-app-connector.md) | 執行 Docker Compose 檔案，以在核心裝置上啟動 Docker 應用程式。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 是 |
| [IoT Analytics](iot-analytics-connector.md) | 將資料從裝置和感應器傳送至 AWS IoT Analytics。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 是 |
| [IoT 乙太網路 IP 通訊協定轉接器](ethernet-ip-connector.md) | 從乙太網路/IP 裝置收集資料。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 是 |
| [IoT SiteWise](iot-sitewise-connector.md) | 將資料從裝置和感測器傳送至 AWS IoT SiteWise中的資產屬性。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 是 |
| [Kinesis Firehose](kinesis-firehose-connector.md) | 將資料傳送至 Amazon Data Firehose 交付串流。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 是 |
| [ML 意見回饋](ml-feedback-connector.md) | 將機器學習模型輸入發佈至雲端，並將輸出發佈至 MQTT 主題。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 否 |
| [ML 影像分類](image-classification-connector.md) | 執行本機映像分類推論服務。此連接器提供適用於多種平台的版本。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 否 |
| [ML 物件偵測](obj-detection-connector.md) | 執行本機物件偵測推論服務。此連接器提供適用於多種平台的版本。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 否 |
| [Modbus-RTU 通訊協定轉接器](modbus-protocol-adapter-connector.md) | 將請求傳送到 Modbus RTU 裝置。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 否 |
| [Modbus-TCP 通訊協定轉接器](modbus-tcp-connector.md) | 從 ModbusTCP 裝置收集資料。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 是 |
| [Raspberry Pi GPIO](raspberrypi-gpio-connector.md) | 控制 Raspberry Pi 核心裝置上的 GPIO 接腳。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 否 |
| [序列串流](serial-stream-connector.md) | 讀取和寫入核心裝置的序列埠。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 否 |
| [ServiceNow MetricBase 整合](servicenow-connector.md) | 將時間序列指標發佈到 ServiceNow MetricBase。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 是 |
| [SNS](sns-connector.md) | 傳送訊息至 Amazon SNS 主題。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 是 |
| [Splunk 整合](splunk-connector.md) | 將資料發佈到 Splunk HEC。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 是 |
| [Twilio 通知](twilio-notifications-connector.md) | 啟動 Twilio 文字或語音訊息。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-list.html) | 是 |
\$1 若要使用 Python 3.8 執行期，您必須從預設 Python 3.7 安裝資料夾建立符號連結，以連接至安裝的 Python 3.8 二進位檔。如需詳細資訊，請參閱連接器特定需求。
**注意**
建議您[升級連接器版本](connectors.md#upgrade-connector-versions)：從 Python 2.7 升級至 Python 3.7。持續支援 Python 2.7 連接器取決於 AWS Lambda 執行時間支援。如需詳細資訊，請參閱《 *AWS Lambda 開發人員指南*》中的[執行期支援政策](https://docs.aws.amazon.com/lambda/latest/dg/runtime-support-policy.html)。
# CloudWatch 指標連接器
CloudWatch Metrics [連接器](connectors.md)會將自訂指標從 Greengrass 裝置發佈至 Amazon CloudWatch。連接器提供集中式基礎設施來發佈 CloudWatch 指標，您可以使用它來監控和分析 Greengrass 核心環境，並對本機事件採取行動。如需詳細資訊，請參閱《[Amazon CloudWatch 使用者指南》中的使用 Amazon CloudWatch 指標](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html)。 *Amazon CloudWatch *
此連接器會接收指標資料當做 MQTT 訊息。連接器會批次處理位於相同命名空間中的指標，並定期將其發佈至 CloudWatch。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 5 | `arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/5` |
| 4 | `arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/4` |
| 3 | `arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/3` |
| 2 | `arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#cloudwatch-metrics-connector-changelog)。
## 要求
此連接器有下列要求：
------
#### [ Version 3 - 5 ]
+ AWS IoT Greengrass 核心軟體 v1.9.3 或更新版本。
+ 安裝在核心裝置上並新增至 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 需求。
+ 設定為允許 `cloudwatch:PutMetricData`動作的 [Greengrass 群組角色](group-role.md)，如下列範例 AWS Identity and Access Management (IAM) 政策所示。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1528133056761",
"Action": [
"cloudwatch:PutMetricData"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
如需 CloudWatch 許可的詳細資訊，請參閱《*IAM 使用者指南*》中的 [Amazon CloudWatch 許可參考](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/permissions-reference-cw.html)。
------
#### [ Versions 1 - 2 ]
+ AWS IoT Greengrass 核心軟體 v1.7 或更新版本。
+ 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 2.7 版。
+ 設定為允許 `cloudwatch:PutMetricData`動作的 [Greengrass 群組角色](group-role.md)，如下列範例 AWS Identity and Access Management (IAM) 政策所示。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1528133056761",
"Action": [
"cloudwatch:PutMetricData"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
如需 CloudWatch 許可的詳細資訊，請參閱《*IAM 使用者指南*》中的 [Amazon CloudWatch 許可參考](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/permissions-reference-cw.html)。
------
## 連接器參數
此連接器提供下列參數：
------
#### [ Versions 4 - 5 ]
`PublishInterval`
對指定的命名空間發佈批次處理指標之前等待的秒數上限。最大值為 900。若要將連接器設定為一收到指標就立刻將其發佈 (不批次處理)，請指定 0。
連接器在相同命名空間中收到 20 個指標後或在指定的間隔後，會發佈至 CloudWatch。
連接器不保證發佈事件的順序。
AWS IoT 主控台中的顯示名稱：**發佈間隔**
必要：`true`
類型：`string`
有效值：`0 - 900`
有效模式： `[0-9]|[1-9]\d|[1-9]\d\d|900`
`PublishRegion`
AWS 區域 要發佈 CloudWatch 指標的 。這個值覆寫預設 Greengrass 指標區域。只在張貼跨區域指標時才需要。
AWS IoT 主控台中的顯示名稱：**發布區域**
必要：`false`
類型：`string`
有效模式： `^$|([a-z]{2}-[a-z]+-\d{1})`
`MemorySize`
分配給連接器的記憶體 (KB)。
AWS IoT 主控台中的顯示名稱：**記憶體大小**
必要：`true`
類型：`string`
有效模式： `^[0-9]+$`
`MaxMetricsToRetain`
在所有命名空間中，由新指標取代之前在記憶體中儲存的指標數目上限。最小值為 2000。
在沒有網際網路連線且連接器開始緩衝指標來稍後發佈時，就受此限制。當緩衝區已滿時，新指標會取代最舊指標。指定命名空間中的指標只會由相同命名空間中的指標取代。
如果連接器的主機程序中斷，則不會儲存指標。例如，在群組部署或裝置重新啟動期間就可能發生這種中斷情況。
在 AWS IoT 主控台中顯示名稱：**要保留的指標上限**
必要：`true`
類型：`string`
有效模式： `^([2-9]\d{3}|[1-9]\d{4,})$`
`IsolationMode`
此連接器的[容器化](connectors.md#connector-containerization)模式。預設值為 `GreengrassContainer`，這表示連接器會在 AWS IoT Greengrass 容器內的隔離執行時間環境中執行。
群組的預設容器化設定不會套用至連接器。
在 AWS IoT 主控台中顯示名稱：**容器隔離模式**
必要：`false`
類型：`string`
有效值：`GreengrassContainer` 或 `NoContainer`
有效模式： `^NoContainer$|^GreengrassContainer$`
------
#### [ Versions 1 - 3 ]
`PublishInterval`
對指定的命名空間發佈批次處理指標之前等待的秒數上限。最大值為 900。若要將連接器設定為一收到指標就立刻將其發佈 (不批次處理)，請指定 0。
連接器在相同命名空間中收到 20 個指標後或在指定的間隔後，會發佈至 CloudWatch。
連接器不保證發佈事件的順序。
AWS IoT 主控台中的顯示名稱：**發佈間隔**
必要：`true`
類型：`string`
有效值：`0 - 900`
有效模式： `[0-9]|[1-9]\d|[1-9]\d\d|900`
`PublishRegion`
AWS 區域 要發佈 CloudWatch 指標的 。這個值覆寫預設 Greengrass 指標區域。只在張貼跨區域指標時才需要。
AWS IoT 主控台中的顯示名稱：**發布區域**
必要：`false`
類型：`string`
有效模式： `^$|([a-z]{2}-[a-z]+-\d{1})`
`MemorySize`
分配給連接器的記憶體 (KB)。
AWS IoT 主控台中的顯示名稱：**記憶體大小**
必要：`true`
類型：`string`
有效模式： `^[0-9]+$`
`MaxMetricsToRetain`
在所有命名空間中，由新指標取代之前在記憶體中儲存的指標數目上限。最小值為 2000。
在沒有網際網路連線且連接器開始緩衝指標來稍後發佈時，就受此限制。當緩衝區已滿時，新指標會取代最舊指標。指定命名空間中的指標只會由相同命名空間中的指標取代。
如果連接器的主機程序中斷，則不會儲存指標。例如，在群組部署或裝置重新啟動期間就可能發生這種中斷情況。
在 AWS IoT 主控台中顯示名稱：**要保留的指標上限**
必要：`true`
類型：`string`
有效模式： `^([2-9]\d{3}|[1-9]\d{4,})$`
------
### 建立範例連接器 (AWS CLI)
下列 CLI 命令`ConnectorDefinition`會使用包含 CloudWatch Metrics 連接器的初始版本來建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MyCloudWatchMetricsConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/4",
"Parameters": {
"PublishInterval" : "600",
"PublishRegion" : "us-west-2",
"MemorySize" : "16",
"MaxMetricsToRetain" : "2500",
"IsolationMode" : "GreengrassContainer"
}
}
]
}'
```
在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。
## 輸入資料
此連接器接受 MQTT 主題的指標，並將指標發佈至 CloudWatch。輸入訊息必須是 JSON 格式。
**訂閱中的主題篩選條件**
`cloudwatch/metric/put`
**訊息屬性**
`request`
此訊息中指標的相關資訊。
請求物件包含要發佈至 CloudWatch 的指標資料。指標值必須符合 [https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html) API 的規格。只需要 `namespace`、`metricData.metricName` 和 `metricData.value` 屬性。
必要：`true`
類型：`object`包含下列屬性：
`namespace`
此請求中指標資料的使用者定義命名空間。CloudWatch 使用命名空間做為指標資料點的容器。
您無法指定以預留字串 開頭的命名空間`AWS/`。
必要：`true`
類型：`string`
有效模式： `[^:].*`
`metricData`
指標的資料。
必要：`true`
類型：`object`包含下列屬性：
`metricName`
指標的名稱
必要：`true`
類型：`string`
`dimensions`
與指標相關聯的維度。維度提供指標及其資料的詳細資訊。一個指標可以定義最多 10 個維度。
此連接器會自動包含名為 的維度`coreName`，其中 值是核心的名稱。
必要：`false`
類型：包含下列屬性`array`的維度物件：
`name`
維度名稱。
必要：`false`
類型：`string`
`value`
維度值。
必要：`false`
類型：`string`
`timestamp`
收到指標資料的時間，以自 以來的秒數表示`Jan 1, 1970 00:00:00 UTC`。如果省略這個值，連接器會使用收到訊息的時間。
必要：`false`
類型：`timestamp`
如果您在此連接器的版本 1 和 4 之間使用 ，我們建議您從單一來源傳送多個指標時，分別擷取每個指標的時間戳記。請勿使用變數來存放時間戳記。
`value`
指標的值。
CloudWatch 會拒絕太小或太大的值。值的範圍必須在 `8.515920e-109` 到 `1.174271e+108` (Base 10) 或 `2e-360` 到 `2e360` (Base 2) 之間。不支援特殊值 (例如，`NaN`、`+Infinity`、`-Infinity`)。
必要：`true`
類型：`double`
`unit`
指標的單位。
必要：`false`
類型：`string`
有效值：`Seconds, Microseconds, Milliseconds, Bytes, Kilobytes, Megabytes, Gigabytes, Terabytes, Bits, Kilobits, Megabits, Gigabits, Terabits, Percent, Count, Bytes/Second, Kilobytes/Second, Megabytes/Second, Gigabytes/Second, Terabytes/Second, Bits/Second, Kilobits/Second, Megabits/Second, Gigabits/Second, Terabits/Second, Count/Second, None`
限制
使用此連接器時，CloudWatch [https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html) API 實施的所有限制都適用於指標。以下限制特別重要：
+ API 承載有 40 KB 限制
+ 每一 API 請求 20 個指標
+ `PutMetricData` API 每秒 150 筆交易 (TPS)
如需詳細資訊，請參閱《Amazon [CloudWatch 使用者指南》中的 CloudWatch 限制](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_limits.html)。 *Amazon CloudWatch *
**範例輸入**
```
{
"request": {
"namespace": "Greengrass",
"metricData":
{
"metricName": "latency",
"dimensions": [
{
"name": "hostname",
"value": "test_hostname"
}
],
"timestamp": 1539027324,
"value": 123.0,
"unit": "Seconds"
}
}
}
```
## 輸出資料
這個連接器會將狀態資訊發佈為輸出資料，且主題為 MQTT。
**訂閱中的主題篩選條件**
`cloudwatch/metric/put/status`
**範例輸出：成功**
回應包含指標資料的命名空間，以及 CloudWatch 回應中的 `RequestId` 欄位。
```
{
"response": {
"cloudwatch_rid":"70573243-d723-11e8-b095-75ff2EXAMPLE",
"namespace": "Greengrass",
"status":"success"
}
}
```
**範例輸出：失敗**
```
{
"response" : {
"namespace": "Greengrass",
"error": "InvalidInputException",
"error_message":"cw metric is invalid",
"status":"fail"
}
}
```
如果連接器偵測到可重試的錯誤 （例如連線錯誤），它會在下一個批次中重試發佈。
## 用量範例
使用下列高階步驟來設定範例 Python 3.7 Lambda 函數，您可以用來嘗試連接器。
**注意**
如果您使用其他 Python 執行期，則可以建立從 Python3.x 到 Python 3.7 的符號連結。
[連接器入門 (主控台)](connectors-console.md) 和 [連接器入門 (CLI)](connectors-cli.md) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。
1. 確定您符合連接器的[要求](#cloudwatch-metrics-connector-req)。
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
1. 建立並發佈 Lambda 函數，將輸入資料傳送至連接器。
將[範例程式碼](#cloudwatch-metrics-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. 新增連接器並設定其[參數](#cloudwatch-metrics-connector-param)。
1. 新增訂閱，允許連接器在支援主題篩選條件上接收[輸入資料](#cloudwatch-metrics-connector-data-input)並傳送[輸出資料](#cloudwatch-metrics-connector-data-output)。
+ 將 Lambda 函數設定為來源，將連接器設定為目標，並使用支援的輸入主題篩選條件。
+ 將連接器設為來源、將 AWS IoT Core 設為目標，並使用支援的輸出主題篩選條件。您可以使用此訂閱在 AWS IoT 主控台中檢視狀態訊息。
1. 部署群組。
1. 在 AWS IoT 主控台**的測試**頁面上，訂閱輸出資料主題，以檢視連接器的狀態訊息。Lambda 函數範例為長期函數，並在部署群組後立即開始傳送訊息。
完成測試後，您可以將 Lambda 生命週期設定為隨需 （或在 CLI `"Pinned": false`中） 並部署群組。這會讓函數停止傳送訊息。
### 範例
下列範例 Lambda 函數會將輸入訊息傳送至連接器。
```
import greengrasssdk
import time
import json
iot_client = greengrasssdk.client('iot-data')
send_topic = 'cloudwatch/metric/put'
def create_request_with_all_fields():
return {
"request": {
"namespace": "Greengrass_CW_Connector",
"metricData": {
"metricName": "Count1",
"dimensions": [
{
"name": "test",
"value": "test"
}
],
"value": 1,
"unit": "Seconds",
"timestamp": time.time()
}
}
}
def publish_basic_message():
messageToPublish = create_request_with_all_fields()
print("Message To Publish: ", messageToPublish)
iot_client.publish(topic=send_topic,
payload=json.dumps(messageToPublish))
publish_basic_message()
def lambda_handler(event, context):
return
```
## 授權
CloudWatch Metrics 連接器包含下列第三方軟體/授權：
+ [適用於 Python (Boto3) 的 AWS SDK](https://pypi.org/project/boto3/)/Apache License 2.0
+ [botocore](https://pypi.org/project/botocore/)/Apache License 2.0
+ [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License
+ [docutils](https://pypi.org/project/docutils/)/BSD 授權、GNU 一般公有授權 (GPL)、Python 軟體基金會授權、公有網域
+ [jmespath](https://pypi.org/project/jmespath/)/MIT License
+ [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0
+ [urllib3](https://pypi.org/project/urllib3/)/MIT License
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明每個版本連接器的變更。
| 版本 | 變更 |
| --- | --- |
| 5 | 修正在輸入資料中新增重複時間戳記的支援。 |
| 4 | 已新增 `IsolationMode` 參數，以設定連接器的容器化模式。 |
| 3 | 將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 |
| 2 | 可減少過多記錄的修正。 |
| 1 | 初始版本。 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
+ 《[Amazon CloudWatch 使用者指南》中的使用 Amazon CloudWatch 指標](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) *Amazon CloudWatch *
+ *Amazon CloudWatch API 參考*中的[ PutMetricData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html)
# Device Defender 連接器
Device Defender [連接器](connectors.md)會通知管理員 Greengrass 核心裝置狀態的變更。這可協助識別可能會表示裝置受損的不尋常行為。
此連接器會從核心裝置上的 `/proc`目錄讀取系統指標，然後將指標發佈至 AWS IoT Device Defender。如需指標報告詳細資訊，請參閱《 *AWS IoT 開發人員指南*》中的[裝置指標文件規格](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender-detect.html#DetectMetricsMessagesSpec)。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 3 | `arn:aws:greengrass:region::/connectors/DeviceDefender/versions/3` |
| 2 | `arn:aws:greengrass:region::/connectors/DeviceDefender/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/DeviceDefender/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#device-defender-connector-changelog)。
## 要求
此連接器有下列要求：
------
#### [ Version 3 ]
+ AWS IoT Greengrass 核心軟體 1.9.3 版或更新版本。
+ 安裝在核心裝置上並新增至 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 需求。
+ AWS IoT Device Defender 設定為使用 Detect 功能來追蹤違規。如需詳細資訊，請參閱《 *AWS IoT 開發人員指南*》中的[偵測](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender-detect.html)。
+ Greengrass 群組中指向`/proc`目錄的[本機磁碟區資源](access-local-resources.md)。資源必須使用下列屬性：
+ 來源路徑：`/proc`
+ 目的地路徑：`/host_proc` (或符合[有效模式](#param-ProcDestinationPath)的值)
+ AutoAddGroupOwner：`true`
+ 安裝在 Greengrass 核心上的 [psutil](https://pypi.org/project/psutil/) 程式庫。5.7.0 版是經過驗證，可與連接器搭配使用的最新版本。
+ 安裝在 Greengrass 核心上的 [cbor](https://pypi.org/project/cbor/) 程式庫。1.0.0 版是經過驗證，可與連接器搭配使用的最新版本。
------
#### [ Versions 1 - 2 ]
+ AWS IoT Greengrass 核心軟體 1.7 版或更新版本。
+ 核心裝置上安裝並新增至 PATH 環境變數的 [Python](https://www.python.org/) 2.7 版。
+ AWS IoT Device Defender 設定為使用 Detect 功能來追蹤違規。如需詳細資訊，請參閱《 *AWS IoT 開發人員指南*》中的[偵測](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender-detect.html)。
+ Greengrass 群組中指向`/proc`目錄的[本機磁碟區資源](access-local-resources.md)。資源必須使用下列屬性：
+ 來源路徑：`/proc`
+ 目的地路徑：`/host_proc` (或符合[有效模式](#param-ProcDestinationPath)的值)
+ AutoAddGroupOwner：`true`
+ 安裝在 Greengrass 核心上的 [psutil](https://pypi.org/project/psutil/) 程式庫。
+ 安裝在 Greengrass 核心上的 [cbor](https://pypi.org/project/cbor/) 程式庫。
------
## 連接器參數
此連接器提供下列參數：
`SampleIntervalSeconds`
蒐集和報告指標每個週期之間的秒數。最低值為 300 秒 (5 分鐘)。
在 AWS IoT 主控台中顯示名稱：**指標報告間隔**
必要： `true`
類型：`string`
有效模式： `^[0-9]*(?:3[0-9][0-9]|[4-9][0-9]{2}|[1-9][0-9]{3,})$`
`ProcDestinationPath-ResourceId`
`/proc` 磁碟區資源的 ID。
此連接器已授予資源的唯讀存取權。
AWS IoT 主控台中的顯示名稱：**/proc 目錄的資源**
必要： `true`
類型：`string`
有效模式： `[a-zA-Z0-9_-]+`
`ProcDestinationPath`
`/proc` 磁碟區資源的目的地路徑。
在 AWS IoT 主控台中顯示名稱：**/proc 資源的目的地路徑**
必要： `true`
類型：`string`
有效模式： `\/[a-zA-Z0-9_-]+`
### 建立範例連接器 (AWS CLI)
下列 CLI 命令會使用包含 Device Defender 連接器的`ConnectorDefinition`初始版本建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MyDeviceDefenderConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/DeviceDefender/versions/3",
"Parameters": {
"SampleIntervalSeconds": "600",
"ProcDestinationPath": "/host_proc",
"ProcDestinationPath-ResourceId": "my-proc-resource"
}
}
]
}'
```
**注意**
此連接器中的 Lambda 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。
在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。
## 輸入資料
此連接器不接受 MQTT 訊息做為輸入資料。
## 輸出資料
此連接器會將安全指標發佈至 AWS IoT Device Defender ，做為輸出資料。
**訂閱中的主題篩選條件**
`$aws/things/+/defender/metrics/json`
這是 AWS IoT Device Defender 預期的主題語法。連接器會將 `+` 萬用字元換成裝置名稱 (例如，`$aws/things/thing-name/defender/metrics/json`)。
**範例輸出**
如需指標報告詳細資訊，請參閱《 *AWS IoT 開發人員指南*》中的[裝置指標文件規格](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender-detect.html#DetectMetricsMessagesSpec)。
```
{
"header": {
"report_id": 1529963534,
"version": "1.0"
},
"metrics": {
"listening_tcp_ports": {
"ports": [
{
"interface": "eth0",
"port": 24800
},
{
"interface": "eth0",
"port": 22
},
{
"interface": "eth0",
"port": 53
}
],
"total": 3
},
"listening_udp_ports": {
"ports": [
{
"interface": "eth0",
"port": 5353
},
{
"interface": "eth0",
"port": 67
}
],
"total": 2
},
"network_stats": {
"bytes_in": 1157864729406,
"bytes_out": 1170821865,
"packets_in": 693092175031,
"packets_out": 738917180
},
"tcp_connections": {
"established_connections":{
"connections": [
{
"local_interface": "eth0",
"local_port": 80,
"remote_addr": "192.168.0.1:8000"
},
{
"local_interface": "eth0",
"local_port": 80,
"remote_addr": "192.168.0.1:8000"
}
],
"total": 2
}
}
}
}
```
## 授權
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明每個連接器版本中的變更。
| 版本 | 變更 |
| --- | --- |
| 3 | 將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 |
| 2 | 可減少過多記錄的修正。 |
| 1 | 初始版本。 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
+ 《 *AWS IoT 開發人員指南*》中的 [Device Defender](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender.html)
# Docker 應用程式部署連接器
Greengrass Docker 應用程式部署連接器可讓您更輕鬆地在 AWS IoT Greengrass 核心上執行 Docker 映像。連接器使用 Docker Compose 從 `docker-compose.yml` 檔案啟動多容器 Docker 應用程式。具體而言，連接器會執行 `docker-compose` 命令來管理單一核心裝置上的 Docker 容器。如需詳細資訊，請參閱 Docker 文件中的 [Docker Compose 概觀](https://docs.docker.com/compose/)。連接器可以存取存放在 Docker 容器登錄檔中的 Docker 映像，例如 Amazon Elastic Container Registry (Amazon ECR)、Docker Hub 和私有 Docker 信任登錄檔。
部署 Greengrass 群組之後，連接器會提取最新的映像並啟動 Docker 容器。它會執行 `docker-compose pull`和 `docker-compose up`命令。然後，連接器會將命令的狀態發佈至[輸出 MQTT 主題](#docker-app-connector-data-output)。它也會記錄有關執行 Docker 容器的狀態資訊。這可讓您在 Amazon CloudWatch 中監控應用程式日誌。如需詳細資訊，請參閱[使用 AWS IoT Greengrass 日誌監控](greengrass-logs-overview.md)。每次 Greengrass 協助程式重新啟動時，連接器也會啟動 Docker 容器。可在核心上執行的 Docker 容器數量取決於您的硬體。
Docker 容器須在核心設備上的 Greengrass 網域外執行，因此無法存取核心的處理程序間通訊 (IPC)。不過，您可以使用 Greengrass 元件設定一些通訊通道，例如本機 Lambda 函數。如需詳細資訊，請參閱[與 Docker 容器通訊](#docker-app-connector-communicating)。
您可以使用連接器來處理在核心裝置上託管 Web 伺服器或 MySQL 伺服器等案例。Docker 應用程式中的本機服務可以互相通訊，也能和本機環境中的其他程序以及雲端服務通訊。例如，您可以在核心上執行 Web 伺服器，將請求從 Lambda 函數傳送至雲端中的 Web 服務。
此連接器會以[無容器](lambda-group-config.md#no-container-mode)隔離模式執行，因此您可以將其部署到在沒有 Greengrass 容器化的情況下執行的 Greengrass 群組。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 7 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/7` |
| 6 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/6` |
| 5 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/5` |
| 4 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/4` |
| 3 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/3` |
| 2 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#docker-app-connector-changelog)。
## 要求
此連接器有下列要求：
+ AWS IoT Greengrass 核心軟體 v1.10 或更新版本。
**注意**
OpenWrt 發行版本不支援此連接器。
+ 安裝在核心裝置上並新增至 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 需求。
+ Greengrass 核心上至少要有 36 MB RAM，以供連接器監控執行 Docker 容器。總記憶體需求取決於核心上執行的 Docker 容器數目。
+ 安裝在 Greengrass 核心上的 [Docker Engine](https://docs.docker.com/install/) 1.9.1 或更新版本。19.0.3 版是經過驗證，可與連接器搭配使用的最新版本。
`docker` 可執行檔必須位於 `/usr/bin` 或 `/usr/local/bin` 目錄中。
**重要**
建議您安裝登入資料存放區，以保護 Docker 登入資料的本機複本。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。
如需在 Amazon Linux 發行版本上安裝 Docker 的詳細資訊，請參閱《Amazon *Elastic Container Service *[開發人員指南》中的 Amazon ECS 的 Docker 基本概念](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/docker-basics.html)。
+ 安裝在 Greengrass 核心上的 [Docker Compose](https://docs.docker.com/compose/install/)。`docker-compose` 可執行檔必須位於 `/usr/bin` 或 `/usr/local/bin` 目錄中。
下列 Docker Compose 版本經過驗證，可與連接器搭配使用。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/docker-app-connector.html)
+ 存放在 Amazon Simple Storage Service (Amazon S3`docker-compose.yml`) 中的單一 Docker Compose 檔案 （例如 )。格式必須與安裝在核心上的 Docker Compose 版本相容。在您的核心上使用該文件前，請先測試該文件。如果您在部署 Greengrass 群組後才編輯檔案，則必須重新部署群組，以更新核心上的本機複本。
+ 具有呼叫本機 Docker 協助程式之權限的 Linux 使用者，以及寫入儲存 Compose 檔案本機複本的目錄。如需詳細資訊，請參閱[在核心上設定 Docker 使用者](#docker-app-connector-linux-user)。
+ 已將 [Greengrass 群組角色](group-role.md)設定為允許在包含 Compose 檔案的 S3 儲存貯體上執行 `s3:GetObject` 動作。此許可會顯示在下列範例 IAM 政策中。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowAccessToComposeFileS3Bucket",
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::bucket-name/*"
}
]
}
```
------
**注意**
如果您的 S3 儲存貯體已啟用版本控制，則必須設定 角色以允許 `s3:GetObjectVersion`動作。如需詳細資訊，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
+ 如果您的 Docker Compose 檔案參考存放在 Amazon ECR 中的 Docker 映像，則 [Greengrass 群組角色](group-role.md)會設定為允許下列項目：
+ `ecr:GetDownloadUrlForLayer` Amazon ECR 儲存庫上包含 Docker 映像的 和 `ecr:BatchGetImage`動作。
+ 您資源上的 `ecr:GetAuthorizationToken` 動作。
儲存庫必須與連接器位於相同的 AWS 帳戶 和 AWS 區域 。
**重要**
群組角色中的許可可由 Greengrass 群組中的所有 Lambda 函數和連接器擔任。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。
這些權限會顯示在下列範例政策中。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowGetEcrRepositories",
"Effect": "Allow",
"Action": [
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage"
],
"Resource": [
"arn:aws:ecr:us-east-1:123456789012:repository/repository-name"
]
},
{
"Sid": "AllowGetEcrAuthToken",
"Effect": "Allow",
"Action": "ecr:GetAuthorizationToken",
"Resource": "*"
}
]
}
```
------
如需詳細資訊，請參閱《[Amazon ECR 使用者指南》中的 Amazon ECR 儲存庫政策範例](https://docs.aws.amazon.com/AmazonECR/latest/userguide/RepositoryPolicyExamples.html)。 **
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
+ 如果您的 Docker Compose 檔案從 [AWS Marketplace](https://aws.amazon.com/marketplace) 中參考 Docker 影像，則連接器也會有下列需求：
+ 您必須訂閱 AWS Marketplace 容器產品。如需詳細資訊，請參閱《 *AWS Marketplace 訂閱者指南*》中的[尋找和訂閱容器產品](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-finding-and-subscribing-to-container-products.html)。
+ AWS IoT Greengrass 必須設定為支援本機秘密，如[秘密要求](secrets.md#secrets-reqs)中所述。連接器只會使用此功能從 擷取您的秘密 AWS Secrets Manager，而不是存放秘密。
+ 您必須在 Secrets Manager 中為儲存 Compose 檔案中參考之 Docker 映像的每個 AWS Marketplace 登錄檔建立秘密。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。
+ 如果您的 Docker Compose 檔案參考 Amazon ECR 以外的登錄檔中私有儲存庫的 Docker 映像，例如 Docker Hub，連接器也具有下列需求：
+ AWS IoT Greengrass 必須設定為支援本機秘密，如[秘密要求](secrets.md#secrets-reqs)中所述。連接器只會使用此功能從 擷取您的秘密 AWS Secrets Manager，而不是存放秘密。
+ 您必須在 Secrets Manager 中為儲存 Compose 檔案中參考之 Docker 映像的每個私有儲存庫建立秘密。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。
+ 部署包含此連接器的 Greengrass 群組時，必須執行 Docker 協助程式。
### 從私有儲存庫存取 Docker 影像
如果您使用登入資料來存取 Docker 影像，則必須允許連接器存取它們。此作法取決於 Docker 影像的位置。
對於存放 Amazon ECR 的 Docker 映像，您授予在 Greengrass 群組角色中取得授權字符的許可。如需詳細資訊，請參閱[要求](#docker-app-connector-req)。
對於存放在其他私有儲存庫或登錄檔中的 Docker 映像，您必須在 中建立秘密 AWS Secrets Manager ，以存放您的登入資訊。這包括您訂閱的 Docker 映像 AWS Marketplace。為每個儲存庫建立一個秘密。如果您在 Secrets Manager 中更新秘密，則變更會在您下次部署群組時傳播至核心。
**注意**
Secrets Manager 是一項服務，可用來在 中安全地存放和管理登入資料、金鑰和其他秘密 AWS 雲端。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[什麼是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。
每個秘密都必須包含下列金鑰：
| 金鑰 | 值 |
| --- | --- |
| `username` | 用來存取儲存庫或登錄檔的使用者名稱。 |
| `password` | 用來存取儲存庫或登錄的密碼。 |
| `registryUrl` | 登錄檔的端點。這必須符合 Compose 檔案中對應的登錄檔 URL。 |
**注意**
若要允許 根據預設 AWS IoT Greengrass 存取秘密，秘密的名稱必須以 *greengrass-* 開頭。否則，您的 Greengrass 服務角色必須授與存取權。如需詳細資訊，請參閱[允許 AWS IoT Greengrass 取得秘密值](secrets.md#secrets-config-service-role)。
**從 AWS Marketplace取得 Docker 影像的登入資訊**
1. 使用 `aws ecr get-login-password`命令 AWS Marketplace 從 取得 Docker 映像的密碼。如需詳細資訊，請參閱《 *AWS CLI 命令參考*》中的 [get-login-password](https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login.html)。
```
aws ecr get-login-password
```
1. 擷取 Docker 映像的登錄 URL。開啟 AWS Marketplace 網站，並開啟容器產品啟動頁面。在**容器映像**下，選擇**檢視容器映像詳細資訊**以尋找使用者名稱和登錄 URL。
使用擷取的使用者名稱、密碼和登錄檔 URL，為儲存 Compose 檔案中參考之 Docker 映像的每個 AWS Marketplace 登錄檔建立秘密。
**建立秘密 (主控台)**
在 AWS Secrets Manager 主控台中，選擇**其他類型的秘密**。在 **Specify the key/value pairs to be stored for this secret (指定此秘密要儲存的索引鍵/值組)** 下，新增 `username`、`password` 和 `registryUrl` 的列。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[建立基本秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)。
![\[用使用者名稱、密碼和註冊庫 URL 金鑰建立一個秘密。\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/images/connectors/secret-docker-trusted-registry.png)
**建立秘密 (CLI)**
在 中 AWS CLI，使用 Secrets Manager `create-secret`命令，如下列範例所示。如需詳細資訊，請參閱《 *AWS CLI 命令參考*》中的 [create-secret](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/create-secret.html)。
```
aws secretsmanager create-secret --name greengrass-MySecret --secret-string [{"username":"Mary_Major"},{"password":"abc123xyz456"},{"registryUrl":"https://docker.io"}]
```
**重要**
您有責任保護儲存 Docker Compose 檔案的 `DockerComposeFileDestinationPath` 目錄以及私有儲存庫的 Docker 影像登入資料的安全。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。
## Parameters
此連接器提供下列參數：
------
#### [ Version 7 ]
`DockerComposeFileS3Bucket`
包含 Docker Compose 檔案的 S3 儲存貯體名稱。當您建立儲存貯體時，請務必遵循 *Amazon Simple Storage Service 使用者指南*中所述[的儲存貯體名稱規則](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。
在 AWS IoT 主控台中顯示名稱：**S3 中的 Docker Compose 檔案**
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`true`
類型：`string`
有效模式 `[a-zA-Z0-9\\-\\.]{3,63}`
`DockerComposeFileS3Key`
Amazon S3 中 Docker Compose 檔案的物件金鑰。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[物件金鑰和中繼資料](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`true`
類型：`string`
有效模式 `.+`
`DockerComposeFileS3Version`
Amazon S3 中 Docker Compose 檔案的物件版本。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`false`
類型：`string`
有效模式 `.+`
`DockerComposeFileDestinationPath`
用來儲存 Docker Compose 檔案複本的本機目錄絕對路徑。這必須是現有目錄。`DockerUserId` 的指定使用者必須具有在此目錄中建立檔案的權限。如需詳細資訊，請參閱[在 AWS IoT Greengrass 核心上設定 Docker 使用者](#docker-app-connector-linux-user)。
儲存 Docker Compose 檔案的目錄以及私有儲存庫的 Docker 影像登入資料的安全。您有責任保護此目錄。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。
在 AWS IoT 主控台中顯示名稱：**本機 Compose 檔案的目錄路徑**
必要：`true`
類型：`string`
有效模式 `\/.*\/?`
範例：`/home/username/myCompose`
`DockerUserId`
連接器用於執行的 Linux 使用者 UID。此使用者必須屬於核心裝置上的 `docker` Linux 群組，並具有 `DockerComposeFileDestinationPath` 目錄的寫入權限。如需詳細資訊，請參閱[在核心上設定 Docker 使用者](#docker-app-connector-linux-user)。
我們建議您除非必要，避免以 root 身分執行。如果您指定根使用者，則必須允許 Lambda 函數以根身分在 AWS IoT Greengrass 核心上執行。如需詳細資訊，請參閱[執行 Lambda 函數做為根](lambda-group-config.md#lambda-running-as-root)。
在 AWS IoT 主控台中顯示名稱：**Docker 使用者 ID**
必要：`false`
類型：`string`
有效模式： `^[0-9]{1,5}$`
`AWSSecretsArnList`
中秘密的 Amazon Resource Name (ARNs)， AWS Secrets Manager 其中包含用於存取私有儲存庫中 Docker 映像的登入資訊。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。
在 AWS IoT 主控台中顯示名稱：**私有儲存庫的登入資料**
必要：`false`。此參數需要存取儲存在私有儲存庫中的 Docker 影像。
類型： `array` 的 `string`
有效模式： `[( ?,? ?"(arn:(aws(-[a-z]+)):secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:([a-zA-Z0-9\]+/)[a-zA-Z0-9/_+=,.@-]+-[a-zA-Z0-9]+)")]`
`DockerContainerStatusLogFrequency`
連接器記錄有關核心上 Docker 容器執行狀態資訊的頻率 (秒)。預設值為 300 秒 (5 分鐘)。
AWS IoT 主控台中的顯示名稱：**記錄頻率**
必要：`false`
類型：`string`
有效模式： `^[1-9]{1}[0-9]{0,3}$`
`ForceDeploy`
指出是否因為上次部署的不當清除而使 Docker 部署失敗。預設值為 `False`。
在 AWS IoT 主控台中顯示名稱：**強制部署**
必要：`false`
類型：`string`
有效模式： `^(true|false)$`
`DockerPullBeforeUp`
指出部署器是否應在執行 `docker-compose pull` 之前執行 `docker-compose up`以進行下拉式行為。 pull-down-up 預設值為 `True`。
在 AWS IoT 主控台中顯示名稱：**Docker Pull Before Up**
必要：`false`
類型：`string`
有效模式： `^(true|false)$`
`StopContainersOnNewDeployment`
指出連接器在 GGC 停止時是否應停止 Docker Deployer 受管 Docker 容器 （在部署新群組或核心關閉時，GGC 會停止）。預設值為 `True`。
在 AWS IoT 主控台中顯示名稱：**Docker 在新部署時停止**
我們建議將此參數設定為預設值`True`。的 參數`False`會導致您的 Docker 容器在終止 AWS IoT Greengrass 核心或啟動新部署後繼續執行。如果您將此參數設定為 `False`，則必須確保在`docker-compose`服務名稱變更或新增時，視需要維護 Docker 容器。
如需詳細資訊，請參閱 `docker-compose` compose 檔案文件。
必要：`false`
類型：`string`
有效模式： `^(true|false)$`
`DockerOfflineMode`
指出在離線 AWS IoT Greengrass 啟動時是否使用現有的 Docker Compose 檔案。預設值為 `False`。
必要：`false`
類型：`string`
有效模式： `^(true|false)$`
------
#### [ Version 6 ]
`DockerComposeFileS3Bucket`
包含 Docker Compose 檔案的 S3 儲存貯體名稱。當您建立儲存貯體時，請務必遵循 *Amazon Simple Storage Service 使用者指南*中所述[的儲存貯體名稱規則](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。
在 AWS IoT 主控台中顯示名稱：**S3 中的 Docker Compose 檔案**
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`true`
類型：`string`
有效模式 `[a-zA-Z0-9\\-\\.]{3,63}`
`DockerComposeFileS3Key`
Amazon S3 中 Docker Compose 檔案的物件金鑰。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[物件金鑰和中繼資料](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`true`
類型：`string`
有效模式 `.+`
`DockerComposeFileS3Version`
Amazon S3 中 Docker Compose 檔案的物件版本。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`false`
類型：`string`
有效模式 `.+`
`DockerComposeFileDestinationPath`
用來儲存 Docker Compose 檔案複本的本機目錄絕對路徑。這必須是現有目錄。`DockerUserId` 的指定使用者必須具有在此目錄中建立檔案的權限。如需詳細資訊，請參閱[在 AWS IoT Greengrass 核心上設定 Docker 使用者](#docker-app-connector-linux-user)。
儲存 Docker Compose 檔案的目錄以及私有儲存庫的 Docker 影像登入資料的安全。您有責任保護此目錄。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。
在 AWS IoT 主控台中顯示名稱：**本機 Compose 檔案的目錄路徑**
必要：`true`
類型：`string`
有效模式 `\/.*\/?`
範例：`/home/username/myCompose`
`DockerUserId`
連接器用於執行的 Linux 使用者 UID。此使用者必須屬於核心裝置上的 `docker` Linux 群組，並具有 `DockerComposeFileDestinationPath` 目錄的寫入權限。如需詳細資訊，請參閱[在核心上設定 Docker 使用者](#docker-app-connector-linux-user)。
我們建議您除非必要，避免以 root 身分執行。如果您指定根使用者，則必須允許 Lambda 函數以根身分在 AWS IoT Greengrass 核心上執行。如需詳細資訊，請參閱[執行 Lambda 函數做為根](lambda-group-config.md#lambda-running-as-root)。
在 AWS IoT 主控台中顯示名稱：**Docker 使用者 ID**
必要：`false`
類型：`string`
有效模式： `^[0-9]{1,5}$`
`AWSSecretsArnList`
中秘密的 Amazon Resource Name (ARNs)， AWS Secrets Manager 其中包含用於存取私有儲存庫中 Docker 映像的登入資訊。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。
AWS IoT 主控台中的顯示名稱：**私有儲存庫的登入資料**
必要：`false`。此參數需要存取儲存在私有儲存庫中的 Docker 影像。
類型： `array` 的 `string`
有效模式： `[( ?,? ?"(arn:(aws(-[a-z]+)):secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:([a-zA-Z0-9\]+/)[a-zA-Z0-9/_+=,.@-]+-[a-zA-Z0-9]+)")]`
`DockerContainerStatusLogFrequency`
連接器記錄有關核心上 Docker 容器執行狀態資訊的頻率 (秒)。預設值為 300 秒 (5 分鐘)。
在 AWS IoT 主控台中顯示名稱：**記錄頻率**
必要：`false`
類型：`string`
有效模式： `^[1-9]{1}[0-9]{0,3}$`
`ForceDeploy`
指出是否因為上次部署的不當清除而使 Docker 部署失敗。預設值為 `False`。
在 AWS IoT 主控台中顯示名稱：**強制部署**
必要：`false`
類型：`string`
有效模式： `^(true|false)$`
`DockerPullBeforeUp`
指出部署器是否應在執行 `docker-compose pull` 之前執行 `docker-compose up`以進行下拉式行為。 pull-down-up 預設值為 `True`。
AWS IoT 主控台中的顯示名稱：**Docker Pull Before Up**
必要：`false`
類型：`string`
有效模式： `^(true|false)$`
`StopContainersOnNewDeployment`
指出連接器在 GGC 停止時 （建立新群組部署時，或核心關閉時），是否應停止 Docker Deployer 受管 Docker 容器。預設值為 `True`。
在 AWS IoT 主控台中顯示名稱：在**新部署時停止 Docker**
我們建議將此參數設定為預設值`True`。的 參數`False`會導致您的 Docker 容器在終止 AWS IoT Greengrass 核心或啟動新部署後繼續執行。如果您將此參數設定為 `False`，則必須確保在`docker-compose`服務名稱變更或新增時，視需要維護 Docker 容器。
如需詳細資訊，請參閱 `docker-compose` compose 檔案文件。
必要：`false`
類型：`string`
有效模式： `^(true|false)$`
------
#### [ Version 5 ]
`DockerComposeFileS3Bucket`
包含 Docker Compose 檔案的 S3 儲存貯體名稱。當您建立儲存貯體時，請務必遵循 *Amazon Simple Storage Service 使用者指南*中所述[的儲存貯體名稱規則](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。
在 AWS IoT 主控台中顯示名稱：**S3 中的 Docker Compose 檔案**
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`true`
類型：`string`
有效模式 `[a-zA-Z0-9\\-\\.]{3,63}`
`DockerComposeFileS3Key`
Amazon S3 中 Docker Compose 檔案的物件金鑰。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[物件金鑰和中繼資料](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`true`
類型：`string`
有效模式 `.+`
`DockerComposeFileS3Version`
Amazon S3 中 Docker Compose 檔案的物件版本。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`false`
類型：`string`
有效模式 `.+`
`DockerComposeFileDestinationPath`
用來儲存 Docker Compose 檔案複本的本機目錄絕對路徑。這必須是現有目錄。`DockerUserId` 的指定使用者必須具有在此目錄中建立檔案的權限。如需詳細資訊，請參閱[在 AWS IoT Greengrass 核心上設定 Docker 使用者](#docker-app-connector-linux-user)。
儲存 Docker Compose 檔案的目錄以及私有儲存庫的 Docker 影像登入資料的安全。您有責任保護此目錄。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。
在 AWS IoT 主控台中顯示名稱：**本機 Compose 檔案的目錄路徑**
必要：`true`
類型：`string`
有效模式 `\/.*\/?`
範例：`/home/username/myCompose`
`DockerUserId`
連接器用於執行的 Linux 使用者 UID。此使用者必須屬於核心裝置上的 `docker` Linux 群組，並具有 `DockerComposeFileDestinationPath` 目錄的寫入權限。如需詳細資訊，請參閱[在核心上設定 Docker 使用者](#docker-app-connector-linux-user)。
我們建議您除非必要，避免以 root 身分執行。如果您指定根使用者，則必須允許 Lambda 函數以根身分在 AWS IoT Greengrass 核心上執行。如需詳細資訊，請參閱[執行 Lambda 函數做為根](lambda-group-config.md#lambda-running-as-root)。
在 AWS IoT 主控台中顯示名稱：**Docker 使用者 ID**
必要：`false`
類型：`string`
有效模式： `^[0-9]{1,5}$`
`AWSSecretsArnList`
中秘密的 Amazon Resource Name (ARNs)， AWS Secrets Manager 其中包含用於存取私有儲存庫中 Docker 映像的登入資訊。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。
AWS IoT 主控台中的顯示名稱：**私有儲存庫的登入資料**
必要：`false`。此參數需要存取儲存在私有儲存庫中的 Docker 影像。
類型： `array` 的 `string`
有效模式： `[( ?,? ?"(arn:(aws(-[a-z]+)):secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:([a-zA-Z0-9\]+/)[a-zA-Z0-9/_+=,.@-]+-[a-zA-Z0-9]+)")]`
`DockerContainerStatusLogFrequency`
連接器記錄有關核心上 Docker 容器執行狀態資訊的頻率 (秒)。預設值為 300 秒 (5 分鐘)。
在 AWS IoT 主控台中顯示名稱：**記錄頻率**
必要：`false`
類型：`string`
有效模式： `^[1-9]{1}[0-9]{0,3}$`
`ForceDeploy`
指出是否因為上次部署的不當清除而使 Docker 部署失敗。預設值為 `False`。
AWS IoT 主控台中的顯示名稱：**強制部署**
必要：`false`
類型：`string`
有效模式： `^(true|false)$`
`DockerPullBeforeUp`
指出部署器是否應在執行 `docker-compose pull` 之前執行 `docker-compose up`以進行下拉式行為。 pull-down-up 預設值為 `True`。
在 AWS IoT 主控台中顯示名稱：**Docker Pull Before Up**
必要：`false`
類型：`string`
有效模式： `^(true|false)$`
------
#### [ Versions 2 - 4 ]
`DockerComposeFileS3Bucket`
包含 Docker Compose 檔案的 S3 儲存貯體名稱。當您建立儲存貯體時，請務必遵循 *Amazon Simple Storage Service 使用者指南*中所述[的儲存貯體名稱規則](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。
在 AWS IoT 主控台中顯示名稱：**S3 中的 Docker Compose 檔案**
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`true`
類型：`string`
有效模式 `[a-zA-Z0-9\\-\\.]{3,63}`
`DockerComposeFileS3Key`
Amazon S3 中 Docker Compose 檔案的物件金鑰。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[物件金鑰和中繼資料](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`true`
類型：`string`
有效模式 `.+`
`DockerComposeFileS3Version`
Amazon S3 中 Docker Compose 檔案的物件版本。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`false`
類型：`string`
有效模式 `.+`
`DockerComposeFileDestinationPath`
用來儲存 Docker Compose 檔案複本的本機目錄絕對路徑。這必須是現有目錄。`DockerUserId` 的指定使用者必須具有在此目錄中建立檔案的權限。如需詳細資訊，請參閱[在 AWS IoT Greengrass 核心上設定 Docker 使用者](#docker-app-connector-linux-user)。
儲存 Docker Compose 檔案的目錄以及私有儲存庫的 Docker 影像登入資料的安全。您有責任保護此目錄。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。
在 AWS IoT 主控台中顯示名稱：**本機 Compose 檔案的目錄路徑**
必要：`true`
類型：`string`
有效模式 `\/.*\/?`
範例：`/home/username/myCompose`
`DockerUserId`
連接器用於執行的 Linux 使用者 UID。此使用者必須屬於核心裝置上的 `docker` Linux 群組，並具有 `DockerComposeFileDestinationPath` 目錄的寫入權限。如需詳細資訊，請參閱[在核心上設定 Docker 使用者](#docker-app-connector-linux-user)。
我們建議您除非必要，避免以 root 身分執行。如果您指定根使用者，則必須允許 Lambda 函數以根身分在 AWS IoT Greengrass 核心上執行。如需詳細資訊，請參閱[執行 Lambda 函數做為根](lambda-group-config.md#lambda-running-as-root)。
在 AWS IoT 主控台中顯示名稱：**Docker 使用者 ID**
必要：`false`
類型：`string`
有效模式： `^[0-9]{1,5}$`
`AWSSecretsArnList`
中秘密的 Amazon Resource Name (ARNs)， AWS Secrets Manager 其中包含用於存取私有儲存庫中 Docker 映像的登入資訊。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。
AWS IoT 主控台中的顯示名稱：**私有儲存庫的登入資料**
必要：`false`。此參數需要存取儲存在私有儲存庫中的 Docker 影像。
類型： `array` 的 `string`
有效模式： `[( ?,? ?"(arn:(aws(-[a-z]+)):secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:([a-zA-Z0-9\]+/)[a-zA-Z0-9/_+=,.@-]+-[a-zA-Z0-9]+)")]`
`DockerContainerStatusLogFrequency`
連接器記錄有關核心上 Docker 容器執行狀態資訊的頻率 (秒)。預設值為 300 秒 (5 分鐘)。
AWS IoT 主控台中的顯示名稱：**記錄頻率**
必要：`false`
類型：`string`
有效模式： `^[1-9]{1}[0-9]{0,3}$`
`ForceDeploy`
指出是否因為上次部署的不當清除而使 Docker 部署失敗。預設值為 `False`。
AWS IoT 主控台中的顯示名稱：**強制部署**
必要：`false`
類型：`string`
有效模式： `^(true|false)$`
------
#### [ Version 1 ]
`DockerComposeFileS3Bucket`
包含 Docker Compose 檔案的 S3 儲存貯體名稱。當您建立儲存貯體時，請務必遵循 *Amazon Simple Storage Service 使用者指南*中所述[的儲存貯體名稱規則](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。
在 AWS IoT 主控台中顯示名稱：**S3 中的 Docker Compose 檔案**
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`true`
類型：`string`
有效模式 `[a-zA-Z0-9\\-\\.]{3,63}`
`DockerComposeFileS3Key`
Amazon S3 中 Docker Compose 檔案的物件金鑰。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[物件金鑰和中繼資料](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`true`
類型：`string`
有效模式 `.+`
`DockerComposeFileS3Version`
Amazon S3 中 Docker Compose 檔案的物件版本。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。
在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。
必要：`false`
類型：`string`
有效模式 `.+`
`DockerComposeFileDestinationPath`
用來儲存 Docker Compose 檔案複本的本機目錄絕對路徑。這必須是現有目錄。`DockerUserId` 的指定使用者必須具有在此目錄中建立檔案的權限。如需詳細資訊，請參閱[在 AWS IoT Greengrass 核心上設定 Docker 使用者](#docker-app-connector-linux-user)。
儲存 Docker Compose 檔案的目錄以及私有儲存庫的 Docker 影像登入資料的安全。您有責任保護此目錄。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。
在 AWS IoT 主控台中顯示名稱：**本機 Compose 檔案的目錄路徑**
必要：`true`
類型：`string`
有效模式 `\/.*\/?`
範例：`/home/username/myCompose`
`DockerUserId`
連接器用於執行的 Linux 使用者 UID。此使用者必須屬於核心裝置上的 `docker` Linux 群組，並具有 `DockerComposeFileDestinationPath` 目錄的寫入權限。如需詳細資訊，請參閱[在核心上設定 Docker 使用者](#docker-app-connector-linux-user)。
我們建議您除非必要，避免以 root 身分執行。如果您指定根使用者，則必須允許 Lambda 函數以根身分在 AWS IoT Greengrass 核心上執行。如需詳細資訊，請參閱[執行 Lambda 函數做為根](lambda-group-config.md#lambda-running-as-root)。
在 AWS IoT 主控台中顯示名稱：**Docker 使用者 ID**
必要：`false`
類型：`string`
有效模式： `^[0-9]{1,5}$`
`AWSSecretsArnList`
中秘密的 Amazon Resource Name (ARNs)， AWS Secrets Manager 其中包含用於存取私有儲存庫中 Docker 映像的登入資訊。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。
AWS IoT 主控台中的顯示名稱：**私有儲存庫的登入資料**
必要：`false`。此參數需要存取儲存在私有儲存庫中的 Docker 影像。
類型： `array` 的 `string`
有效模式： `[( ?,? ?"(arn:(aws(-[a-z]+)):secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:([a-zA-Z0-9\]+/)[a-zA-Z0-9/_+=,.@-]+-[a-zA-Z0-9]+)")]`
`DockerContainerStatusLogFrequency`
連接器記錄有關核心上 Docker 容器執行狀態資訊的頻率 (秒)。預設值為 300 秒 (5 分鐘)。
在 AWS IoT 主控台中顯示名稱：**記錄頻率**
必要：`false`
類型：`string`
有效模式： `^[1-9]{1}[0-9]{0,3}$`
------
### 建立範例連接器 (AWS CLI)
下列 CLI 命令`ConnectorDefinition`會使用包含 Greengrass Docker 應用程式部署連接器的初始版本來建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MyDockerAppplicationDeploymentConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/5",
"Parameters": {
"DockerComposeFileS3Bucket": "amzn-s3-demo-bucket",
"DockerComposeFileS3Key": "production-docker-compose.yml",
"DockerComposeFileS3Version": "123",
"DockerComposeFileDestinationPath": "/home/username/myCompose",
"DockerUserId": "1000",
"AWSSecretsArnList": "[\"arn:aws:secretsmanager:region:account-id:secret:greengrass-secret1-hash\",\"arn:aws:secretsmanager:region:account-id:secret:greengrass-secret2-hash\"]",
"DockerContainerStatusLogFrequency": "30",
"ForceDeploy": "True",
"DockerPullBeforeUp": "True"
}
}
]
}'
```
**注意**
此連接器中的 Lambda 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。
## 輸入資料
此連接器不需要或接受輸入資料。
## 輸出資料
此連接器將 `docker-compose up` 命令的狀態發佈為輸出資料。
**訂閱中的主題篩選條件**
`dockerapplicationdeploymentconnector/message/status`
**範例輸出：成功**
```
{
"status":"success",
"GreengrassDockerApplicationDeploymentStatus":"Successfully triggered docker-compose up",
"S3Bucket":"amzn-s3-demo-bucket",
"ComposeFileName":"production-docker-compose.yml",
"ComposeFileVersion":"123"
}
```
**範例輸出：失敗**
```
{
"status":"fail",
"error_message":"description of error",
"error":"InvalidParameter"
}
```
錯誤類型可以是 `InvalidParameter` 或 `InternalError`。
## 在 AWS IoT Greengrass 核心上設定 Docker 使用者
Greengrass Docker 應用程式部署連接器會以您為 `DockerUserId` 參數指定的使用者身分執行。如果您未指定值，連接器會以 `ggc_user` 為身分執行，這也是預設 Greengrass 存取身分。
若要允許連接器與 Docker 協助程式互動，Docker 使用者必須屬於核心上的 `docker` Linux 群組。Docker 使用者也必須具有 `DockerComposeFileDestinationPath` 目錄的寫入權限。這是連接器儲存本機 `docker-compose.yml` 檔案和 Docker 登入資料的位置。
**注意**
建議您建立 Linux 使用者，不要使用預設值 `ggc_user`。否則，Greengrass 群組中的任何 Lambda 函數都可以存取 Compose 檔案和 Docker 登入資料。
我們建議您除非必要，避免以 root 身分執行。如果您指定根使用者，則必須允許 Lambda 函數以根身分在 AWS IoT Greengrass 核心上執行。如需詳細資訊，請參閱[執行 Lambda 函數做為根](lambda-group-config.md#lambda-running-as-root)。
1. 建立使用者。您可以執行 `useradd` 命令，並包含選用的 `-u` 選項來指派 UID。例如：
```
sudo useradd -u 1234 user-name
```
1. 將使用者新增至核心上的 `docker` 群組。例如：
```
sudo usermod -aG docker user-name
```
如需詳細資訊 (包括如何建立 `docker` 群組)，請參閱 Docker 文件中 [Manage Docker as a non-root user](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user) (以非根使用者身分管理 Docker)。
1. 授予使用者寫入 `DockerComposeFileDestinationPath` 參數指定目錄的權限。例如：
1. 將使用者設定為目錄的擁有者。這個範例會使用步驟 1 中的 UID。
```
chown 1234 docker-compose-file-destination-path
```
1. 將讀取和寫入權限提供給擁有者。
```
chmod 700 docker-compose-file-destination-path
```
如需詳細資訊，請參閱 Linux 基礎文件中的 [How To Manage File And Folder Permissions In Linux](https://www.linux.com/tutorials/how-manage-file-and-folder-permissions-linux/) (如何管理 Linux 中的檔案及資料夾權限)。
1. 如果您在建立使用者時未指派 UID，或者，您使用現有使用者，請執行 `id` 命令以查詢 UID。
```
id -u user-name
```
您可以使用 UID 來設定連接器的 `DockerUserId` 參數。
## 用量資訊
當您使用 Greengrass Docker 應用程式部署連接器時，您應該注意下列實作特定的使用資訊。
+ **已修正專案名稱的字首。**連接器會在它啟動的 Docker 容器名稱前加上 `greengrassdockerapplicationdeployment` 字首。連接器在其執行的 `docker-compose` 指令中使用此字首做為專案名稱。
+ **記錄行為。**連接器會將狀態資訊和疑難排解資訊寫入日誌檔案。您可以設定 AWS IoT Greengrass 將日誌傳送至 CloudWatch Logs，並在本機寫入日誌。如需詳細資訊，請參閱[連接器的記錄](connectors.md#connectors-logging)。這是連接器本機記錄檔的路徑：
```
/greengrass-root/ggc/var/log/user/region/aws/DockerApplicationDeployment.log
```
您必須具有 root 權限才能存取本機日誌。
+ **更新 Docker 映像。**Docker 會快取核心裝置上的影像。如果您更新 Docker 影像，並想將變更傳播到核心裝置，請務必變更 Compose 檔案中的影像標籤。部署 Greengrass 群組之後，變更就會生效。
+ **清除操作的 10 分鐘逾時。**當 Greengrass 協助程式在重新啟動期間停止時，會啟動 `docker-compose down`命令。`docker-compose down` 啟動 後，所有 Docker 容器最多有 10 分鐘的時間來執行任何清除操作。如果未在 10 分鐘內完成清除，您必須手動清除剩餘的容器。如需詳細資訊，請參閱 Docker CLI 文件中的 [docker rm](https://docs.docker.com/engine/reference/commandline/rm/)。
+ **執行 Docker 命令。**若要對問題進行疑難排解，可以在核心裝置的終端機視窗中執行 Docker 命令。例如，執行下列命令以查看連接器啟動的 Docker 容器：
```
docker ps --filter name="greengrassdockerapplicationdeployment"
```
+ **預留資源 ID。**連接器會使用其在 Greengrass 群組中建立的 Greengrass 資源 `DOCKER_DEPLOYER_SECRET_RESOURCE_RESERVED_ID_index` ID。資源 ID 在群組中不得重複，因此請勿指派可能與此保留資源 ID 衝突的資源 ID。
+ **離線模式。**當您將`DockerOfflineMode`組態參數設定為 時`True`，Docker 連接器可以*離線模式*操作。當 Greengrass 群組部署在核心裝置離線時重新啟動，且連接器無法建立與 Amazon S3 或 Amazon ECR 的連線以擷取 Docker Compose 檔案時，就會發生這種情況。
啟用離線模式時，連接器會嘗試下載 Compose 檔案，並像在正常重新啟動時一樣執行`docker login`命令。如果這些嘗試失敗，則連接器會在使用 `DockerComposeFileDestinationPath` 參數指定的資料夾中尋找本機儲存的 Compose 檔案。如果本機 Compose 檔案存在，則連接器會遵循正常的`docker-compose`命令順序，並從本機映像提取 。如果 Compose 檔案或本機映像不存在，則連接器會失敗。在離線模式下， `ForceDeploy`和 `StopContainersOnNewDeployment` 參數的行為保持不變。
## 與 Docker 容器通訊
AWS IoT Greengrass 支援 Greengrass 元件和 Docker 容器之間的下列通訊管道：
+ Greengrass Lambda 函數可以使用 REST APIs 與 Docker 容器中的程序通訊。您可以在開啟連接埠的 Docker 容器中設定伺服器。Lambda 函數可以與此連接埠上的容器通訊。
+ Docker 容器中的處理程序可以透過本機 Greengrass 訊息中介裝置交換 MQTT 訊息。您可以在 Greengrass 群組中將 Docker 容器設定為用戶端裝置，然後建立訂閱，以允許容器與群組中的 Greengrass Lambda 函數、用戶端裝置和其他連接器通訊，或與 AWS IoT 和本機影子服務通訊。如需詳細資訊，請參閱[設定與 Docker 容器的 MQTT 通訊](#docker-app-connector-mqtt-communication)。
+ Greengrass Lambda 函數可以更新共用檔案，以將資訊傳遞至 Docker 容器。您可以使用 Compose 檔案綁定掛載 Docker 容器的共用檔案路徑。
### 設定與 Docker 容器的 MQTT 通訊
您可以將 Docker 容器設定為用戶端裝置，並將其新增至 Greengrass 群組。然後，您可以建立訂閱，以允許 Docker 容器和 Greengrass 元件或 AWS IoT之間的 MQTT 通訊。在下列程序中，您會建立訂閱，允許 Docker 容器裝置接收來自本機陰影服務的陰影更新訊息。您可以遵循此模式來建立其他訂閱。
**注意**
此程序假設您已建立 Greengrass 群組和 Greengrass 核心 (v1.10 或更新版本）。如需建立 Greengrass 群組和核心的詳細資訊，請參閱 [入門 AWS IoT Greengrass](gg-gs.md)。
**將 Docker 容器設定為用戶端裝置，並將其新增至 Greengrass 群組**
1. 在核心裝置上建立資料夾，以存放用於驗證 Greengrass 裝置的憑證和金鑰。
檔案路徑必須掛載在您要啟動的 Docker 容器上。下面的程式碼片段顯示了如何在您的 Compose 檔案中掛載文件路徑。在此範例中，*path-to-device-certs* 代表您在此步驟中建立的資料夾。
```
version: '3.3'
services:
myService:
image: user-name/repo:image-tag
volumes:
- /path-to-device-certs/:/path-accessible-in-container
```
1. 在 AWS IoT 主控台導覽窗格的**管理**下，展開 **Greengrass 裝置**，然後選擇**群組 (V1)**。
1. 選擇目標群組。
1. 在群組組態頁面上，選擇**用戶端裝置**，然後選擇**關聯**。
1. 在**將用戶端裝置與此群組模型建立關聯**中，選擇**建立新 AWS IoT 物件**。
**建立物件**頁面會在新標籤中開啟。
1. 在**建立物件**頁面上，選擇**建立單一物件**，然後選擇**下一步**。
1. 在**指定物件屬性**頁面上，輸入裝置的名稱，然後選擇**下一步**。
1. 在**設定裝置憑證**頁面上，選擇**下一步**。
1. 在**將政策連接至憑證**頁面上，執行下列其中一項操作：
+ 選取授予用戶端裝置所需許可的現有政策，然後選擇**建立物件**。
模態開啟，您可以在其中下載裝置用來連線至 和 核心的憑證 AWS 雲端 和金鑰。
+ 建立並連接授予用戶端裝置許可的新政策。請執行下列操作：
1. 選擇**建立政策**。
**Create policy (建立政策)** 頁面隨即在新標籤中開啟。
1. 在 **Create policy (建立政策)** 頁面上，執行下列動作：
1. 針對**政策名稱**，輸入描述政策的名稱，例如 **GreengrassV1ClientDevicePolicy**。
1. 在**政策陳述**式索引標籤**的政策文件**下，選擇 **JSON**。
1. 輸入下列政策文件。此政策可讓用戶端裝置探索 Greengrass 核心，並在所有 MQTT 主題上進行通訊。如需如何限制此政策存取的資訊，請參閱 [的裝置身分驗證和授權 AWS IoT Greengrass](device-auth.md)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Subscribe",
"iot:Connect",
"iot:Receive"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"greengrass:*"
],
"Resource": [
"*"
]
}
]
}
```
------
1. 選擇 **Create (建立)** 以建立政策。
1. 返回瀏覽器索引標籤，開啟**附加政策至憑證**頁面。請執行下列操作：
1. 在**政策**清單中，選取您建立的政策，例如 **GreengrassV1ClientDevicePolicy**。
如果您沒有看到政策，請選擇重新整理按鈕。
1. 選擇 **Create thing** (建立物件)。
模態開啟，您可以在其中下載裝置用來連線至 和 核心的憑證 AWS 雲端 和金鑰。
1. 在**下載憑證和金鑰**模態中，下載裝置的憑證。
**重要**
選擇**完成**之前，請下載安全資源。
請執行下列操作：
1. 針對**裝置憑證**，選擇**下載**以下載裝置憑證。
1. 針對**公有金鑰檔案**，選擇**下載**以下載憑證的公有金鑰。
1. 針對**私有金鑰檔案**，選擇**下載**以下載憑證的私有金鑰檔案。
1. 檢閱《 *AWS IoT 開發人員指南*》中的[伺服器身分驗證](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html)，然後選擇適當的根 CA 憑證。我們建議您使用 Amazon Trust Services (ATS) 端點和 ATS 根 CA 憑證。在**根 CA 憑證**下，選擇根 CA 憑證的**下載**。
1. 選擇**完成**。
請記下裝置憑證和金鑰檔案名稱中常見的憑證 ID。供稍後使用。
1. 將憑證和金鑰複製到您在步驟 1 中建立的資料夾。
接下來，在群組中建立訂閱。在此範例中，您可以建立訂閱讓 Docker 容器裝置接收來自本機陰影服務的 MQTT 訊息。
**注意**
陰影文件的大小上限為 8 KB。如需詳細資訊，請參閱《 *AWS IoT 開發人員指南*》中的[AWS IoT 配額](https://docs.aws.amazon.com/iot/latest/developerguide/limits-iot.html)。
**建立訂閱，允許 Docker 容器裝置接收來自本機陰影服務的 MQTT 訊息**
1. 在群組組態頁面上，選擇**訂閱**索引標籤，然後選擇**新增訂閱**。
1. 在 **Select your source and target (選擇您的來源和目標)** 頁面設定來源和目標，如下所示：
1. 在 **Select a source (選取來源)** 中，選擇 **Services (服務)**，然後選擇 **Local Shadow Service (本機陰影服務)**。
1. 在 **Select a target (選取目標)**，選擇 **Devices (裝置)**，然後選擇您的裝置。
1. 選擇**下一步**。
1. 在**使用主題篩選資料**頁面上，針對**主題篩選**，選擇 **\$1aws/things/*MyDockerDevice*/shadow/update/accepted**，然後選擇**下一步**。將 *MyDockerDevice* 取代為您先前建立的裝置名稱。
1. 選擇**完成**。
在您在 Compose 檔案中參考的 Docker 影像中，加入下列程式碼片段。這是 Greengrass 裝置程式碼。另外，請在 Docker 容器中新增程式碼，以啟動容器內的 Greengrass 設備。它可以在影像中或獨立的執行緒中，以個別程序來執行。
```
import os
import sys
import time
import uuid
from AWSIoTPythonSDK.core.greengrass.discovery.providers import DiscoveryInfoProvider
from AWSIoTPythonSDK.exception.AWSIoTExceptions import DiscoveryInvalidRequestException
from AWSIoTPythonSDK.MQTTLib import AWSIoTMQTTClient
# Replace thingName with the name you registered for the Docker device.
thingName = "MyDockerDevice"
clientId = thingName
# Replace host with the IoT endpoint for your &AWS-account;.
host = "myPrefix.iot.region.amazonaws.com"
# Replace topic with the topic where the Docker container subscribes.
topic = "$aws/things/MyDockerDevice/shadow/update/accepted"
# Replace these paths based on the download location of the certificates for the Docker container.
rootCAPath = "/path-accessible-in-container/AmazonRootCA1.pem"
certificatePath = "/path-accessible-in-container/certId-certificate.pem.crt"
privateKeyPath = "/path-accessible-in-container/certId-private.pem.key"
# Discover Greengrass cores.
discoveryInfoProvider = DiscoveryInfoProvider()
discoveryInfoProvider.configureEndpoint(host)
discoveryInfoProvider.configureCredentials(rootCAPath, certificatePath, privateKeyPath)
discoveryInfoProvider.configureTimeout(10) # 10 seconds.
GROUP_CA_PATH = "./groupCA/"
MQTT_QOS = 1
discovered = False
groupCA = None
coreInfo = None
try:
# Get discovery info from AWS IoT.
discoveryInfo = discoveryInfoProvider.discover(thingName)
caList = discoveryInfo.getAllCas()
coreList = discoveryInfo.getAllCores()
# Use first discovery result.
groupId, ca = caList[0]
coreInfo = coreList[0]
# Save the group CA to a local file.
groupCA = GROUP_CA_PATH + groupId + "_CA_" + str(uuid.uuid4()) + ".crt"
if not os.path.exists(GROUP_CA_PATH):
os.makedirs(GROUP_CA_PATH)
groupCAFile = open(groupCA, "w")
groupCAFile.write(ca)
groupCAFile.close()
discovered = True
except DiscoveryInvalidRequestException as e:
print("Invalid discovery request detected!")
print("Type: %s" % str(type(e)))
print("Error message: %s" % str(e))
print("Stopping...")
except BaseException as e:
print("Error in discovery!")
print("Type: %s" % str(type(e)))
print("Error message: %s" % str(e))
print("Stopping...")
myAWSIoTMQTTClient = AWSIoTMQTTClient(clientId)
myAWSIoTMQTTClient.configureCredentials(groupCA, privateKeyPath, certificatePath)
# Try to connect to the Greengrass core.
connected = False
for connectivityInfo in coreInfo.connectivityInfoList:
currentHost = connectivityInfo.host
currentPort = connectivityInfo.port
myAWSIoTMQTTClient.configureEndpoint(currentHost, currentPort)
try:
myAWSIoTMQTTClient.connect()
connected = True
except BaseException as e:
print("Error in connect!")
print("Type: %s" % str(type(e)))
print("Error message: %s" % str(e))
if connected:
break
if not connected:
print("Cannot connect to core %s. Exiting..." % coreInfo.coreThingArn)
sys.exit(-2)
# Handle the MQTT message received from GGShadowService.
def customCallback(client, userdata, message):
print("Received an MQTT message")
print(message)
# Subscribe to the MQTT topic.
myAWSIoTMQTTClient.subscribe(topic, MQTT_QOS, customCallback)
# Keep the process alive to listen for messages.
while True:
time.sleep(1)
```
## 安全注意事項
當您使用 Greengrass Docker 應用程式部署連接器時，請注意下列安全考量。
**Docker Compose 檔案的本機儲存區**
連接器會將 Compose 檔案的複本儲存在為 `DockerComposeFileDestinationPath` 參數指定的目錄中。
您有責任保護此目錄。您應該使用檔案系統權限來限制目錄的存取。
**Docker 登入資料的本機儲存區**
如果您的 Docker 影像儲存在私有儲存庫中，連接器會將您的 Docker 登入資料儲存在為 `DockerComposeFileDestinationPath` 參數指定的目錄中。
您有責任保護這些登入資料。例如，安裝 Docker Engine 時，應在核心裝置上使用 [credential-helper](https://docs.docker.com/engine/reference/commandline/login/#credentials-store)。
**從可信任來源安裝 Docker Engine**
您有責任從可信任來源安裝 Docker Engine。此連接器使用核心裝置上的 Docker 協助程式，存取您的 Docker 資產並管理 Docker 容器。
**Greengrass 群組角色權限的範圍**
您在 Greengrass 群組角色中新增的許可，可由 Greengrass 群組中的所有 Lambda 函數和連接器擔任。此連接器需要存取儲存 S3 儲存貯體中的 Docker Compose 檔案。如果您的 Docker 映像存放在 Amazon ECR 中的私有儲存庫中，它也需要存取您的 Amazon ECR 授權字符。
## 授權
Greengrass Docker 應用程式部署連接器包含下列第三方軟體/授權：
+ [適用於 Python (Boto3) 的 AWS SDK](https://pypi.org/project/boto3/)/Apache License 2.0
+ [botocore](https://pypi.org/project/botocore/)/Apache License 2.0
+ [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License
+ [docutils](https://pypi.org/project/docutils/)/BSD 授權、GNU 一般公有授權 (GPL)、Python 軟體基金會授權、公有網域
+ [jmespath](https://pypi.org/project/jmespath/)/MIT License
+ [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0
+ [urllib3](https://pypi.org/project/urllib3/)/MIT License
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明每個版本連接器的變更。
| 版本 | 變更 |
| --- | --- |
| 7 | 新增`DockerOfflineMode`以在離線 AWS IoT Greengrass 啟動時使用現有的 Docker Compose 檔案。已實作`docker login`命令的重試。支援 32 位元 UIDs。 |
| 6 | 新增`StopContainersOnNewDeployment`以在進行新部署或 GGC 停止時覆寫容器清除。更安全的關機和啟動機制。YAML 驗證錯誤修正。 |
| 5 | 映像會在執行 之前提取`docker-compose down`。 |
| 4 | 新增pull-before-up行為以更新 Docker 映像。 |
| 3 | 修正了尋找環境變數的問題。 |
| 2 | 新增 `ForceDeploy` 參數。 |
| 1 | 初始版本。 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
# IoT Analytics 連接器
**警告**
此連接器已進入*延長生命週期階段*，且 AWS IoT Greengrass 不會發佈提供現有功能、增強功能、安全修補程式或錯誤修正的更新。如需詳細資訊，請參閱[AWS IoT Greengrass Version 1 維護政策](maintenance-policy.md)。
IoT Analytics 連接器會將本機裝置資料傳送至 AWS IoT Analytics。您可以使用此連接器做為中央中樞，從 Greengrass 核心裝置上的感應器和[連接的用戶端裝置](what-is-gg.md#greengrass-devices)收集資料。連接器會將資料傳送至目前 AWS 帳戶 和 區域中的 AWS IoT Analytics 頻道。它可以將資料傳送到預設目的地管道和動態指定的管道。
**注意**
AWS IoT Analytics 是一種全受管服務，可讓您收集、存放、處理和查詢 IoT 資料。在 中 AWS IoT Analytics，可以進一步分析和處理資料。例如，您可以用於訓練機器學習模型來監控機器運作狀況，或測試新的建模策略。如需詳細資訊，請參閱*AWS IoT Analytics 《 使用者指南*》中的[什麼是 AWS IoT Analytics？](https://docs.aws.amazon.com/iotanalytics/latest/userguide/welcome.html)。
連接器接受[輸入 MQTT 主題](#iot-analytics-connector-data-input)上的有格式和無格式資料。它支援兩種預先定義的主題，目的地管道為指定的內嵌。它也可以接收[在訂閱中配置的](connectors.md#connectors-inputs-outputs)客戶定義主題訊息。這可用於從發佈至固定主題的用戶端裝置路由訊息，或從資源受限的裝置處理非結構化或堆疊相依資料。
此連接器使用 [https://docs.aws.amazon.com/iotanalytics/latest/userguide/api.html#cli-iotanalytics-batchputmessage](https://docs.aws.amazon.com/iotanalytics/latest/userguide/api.html#cli-iotanalytics-batchputmessage) API 將資料 （以 JSON 或 base64 編碼字串的形式） 傳送至目的地頻道。連接器可將原始資料處理為符合 API 要求的格式。連接器會依管道佇列緩衝輸入的訊息，並以非同步方式處理批次。它提供參數，讓您控制佇列和批次處理行為，以及限制記憶體用量。例如，您可以設定最大佇列大小、批次間隔、記憶體大小和作用中管道的數量。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 4 | `arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/4` |
| 3 | `arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/3` |
| 2 | `arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#iot-analytics-connector-changelog)。
## 要求
此連接器有下列要求：
------
#### [ Version 3 - 4 ]
+ AWS IoT Greengrass 核心軟體 v1.9.3 或更新版本。
+ 安裝在核心裝置上並新增至 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 需求。
+ 此連接器只能在同時[AWS IoT Analytics](https://docs.aws.amazon.com/general/latest/gr/iot-analytics.html)支援 [AWS IoT Greengrass](https://docs.aws.amazon.com/general/latest/gr/greengrass.html)和 的 Amazon Web Services 區域中使用。
+ 建立並設定所有相關 AWS IoT Analytics 實體和工作流程。實體包含頻道、管道、資料存放區和資料集。如需詳細資訊，請參閱*AWS IoT Analytics 《 使用者指南*》中的 [AWS CLI](https://docs.aws.amazon.com/iotanalytics/latest/userguide/getting-started.html)或 [主控台](https://docs.aws.amazon.com/iotanalytics/latest/userguide/quickstart.html)程序。
**注意**
目的地 AWS IoT Analytics 頻道必須使用相同的 帳戶，且與此 AWS 區域 連接器位於相同的 中。
+ [Greengrass 群組角色](group-role.md)設定為允許對目的地頻道執行 `iotanalytics:BatchPutMessage`動作，如下列範例 IAM 政策所示。頻道必須位於目前的 AWS 帳戶 和 區域中。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1528133056761",
"Action": [
"iotanalytics:BatchPutMessage"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iotanalytics:us-east-1:123456789012:channel/channel_1_name",
"arn:aws:iotanalytics:us-east-1:123456789012:channel/channel_2_name"
]
}
]
}
```
------
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
------
#### [ Versions 1 - 2 ]
+ AWS IoT Greengrass 核心軟體 v1.7 或更新版本。
+ 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 2.7 版。
+ 此連接器只能在同時[AWS IoT Analytics](https://docs.aws.amazon.com/general/latest/gr/iot-analytics.html)支援 [AWS IoT Greengrass](https://docs.aws.amazon.com/general/latest/gr/greengrass.html)和 的 Amazon Web Services 區域中使用。
+ 建立並設定所有相關 AWS IoT Analytics 實體和工作流程。實體包含頻道、管道、資料存放區和資料集。如需詳細資訊，請參閱*AWS IoT Analytics 《 使用者指南*》中的 [AWS CLI](https://docs.aws.amazon.com/iotanalytics/latest/userguide/getting-started.html)或 [主控台](https://docs.aws.amazon.com/iotanalytics/latest/userguide/quickstart.html)程序。
**注意**
目的地 AWS IoT Analytics 頻道必須使用相同的 帳戶，且與此 AWS 區域 連接器位於相同的 中。
+ 設定為允許對目的地頻道`iotanalytics:BatchPutMessage`執行動作的 [Greengrass 群組角色](group-role.md)，如下列範例 IAM 政策所示。頻道必須位於目前的 AWS 帳戶 和 區域中。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1528133056761",
"Action": [
"iotanalytics:BatchPutMessage"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iotanalytics:us-east-1:123456789012:channel/channel_1_name",
"arn:aws:iotanalytics:us-east-1:123456789012:channel/channel_2_name"
]
}
]
}
```
------
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
------
## Parameters
`MemorySize`
配置給此連接器的記憶體數量 (KB)。
AWS IoT 主控台中的顯示名稱：**記憶體大小**
必要：`true`
類型：`string`
有效模式： `^[0-9]+$`
`PublishRegion`
AWS 區域 AWS IoT Analytics 頻道建立所在的 。使用與連接器相同的區域。
這也必須與[群組角色](#iot-analytics-connector-req)中指定的管道所在區域相同。
AWS IoT 主控台中的顯示名稱：**發布區域**
必要：`false`
類型：`string`
有效模式： `^$|([a-z]{2}-[a-z]+-\\d{1})`
`PublishInterval`
將一批接收資料發佈到其中的間隔 （以秒為單位） AWS IoT Analytics。
在 AWS IoT 主控台中顯示名稱：**發佈間隔**
必要：`false`
類型：`string`
預設值：`1`
有效模式： `$|^[0-9]+$`
`IotAnalyticsMaxActiveChannels`
連接器主動監看的 AWS IoT Analytics 頻道數量上限。此數值必須大於 0，且至少等於您希望連接器在特定時間發佈的目標頻道數。
您可以使用此參數，透過限制連接器在特定時間可以管理的佇列總數，藉以限制記憶體用量。佇列中所有訊息皆傳送後，該佇列就會刪除。
AWS IoT 主控台中的顯示名稱：**作用中頻道的數量上限**
必要：`false`
類型：`string`
預設值：`50`
有效模式： `^$|^[1-9][0-9]*$`
`IotAnalyticsQueueDropBehavior`
管道佇列已滿時，從佇列拋棄訊息的行為。
AWS IoT 主控台中的顯示名稱：**佇列捨棄行為**
必要：`false`
類型：`string`
有效值：`DROP_NEWEST` 或 `DROP_OLDEST`
預設值：`DROP_NEWEST`
有效模式： `^DROP_NEWEST$|^DROP_OLDEST$`
`IotAnalyticsQueueSizePerChannel`
訊息提交或拋棄前，在 (每個管道) 記憶體中保留的最大訊息數。此數值必須大於 0。
AWS IoT 主控台中的顯示名稱：**每個通道的佇列大小上限**
必要：`false`
類型：`string`
預設值：`2048`
有效模式： `^$|^[1-9][0-9]*$`
`IotAnalyticsBatchSizePerChannel`
一個批次請求中要傳送到 AWS IoT Analytics 頻道的訊息數量上限。此數值必須大於 0。
在 AWS IoT 主控台中顯示名稱：**每個頻道要批次處理的訊息數量上限**
必要：`false`
類型：`string`
預設值：`5`
有效模式： `^$|^[1-9][0-9]*$`
`IotAnalyticsDefaultChannelName`
此連接器用於傳送至客戶定義輸入主題之訊息的 AWS IoT Analytics 頻道名稱。
AWS IoT 主控台中的顯示名稱：**預設頻道名稱**
必要：`false`
類型：`string`
有效模式： `^[a-zA-Z0-9_]$`
`IsolationMode`
此連接器的[容器化](connectors.md#connector-containerization)模式。預設值為 `GreengrassContainer`，這表示連接器會在 AWS IoT Greengrass 容器內的隔離執行時間環境中執行。
群組的預設容器化設定不會套用至連接器。
在 AWS IoT 主控台中顯示名稱：**容器隔離模式**
必要：`false`
類型：`string`
有效值：`GreengrassContainer` 或 `NoContainer`
有效模式： `^NoContainer$|^GreengrassContainer$`
### 建立範例連接器 (AWS CLI)
下列 CLI 命令`ConnectorDefinition`會使用包含 IoT Analytics 連接器的初始版本來建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MyIoTAnalyticsApplication",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/3",
"Parameters": {
"MemorySize": "65535",
"PublishRegion": "us-west-1",
"PublishInterval": "2",
"IotAnalyticsMaxActiveChannels": "25",
"IotAnalyticsQueueDropBehavior": "DROP_OLDEST",
"IotAnalyticsQueueSizePerChannel": "1028",
"IotAnalyticsBatchSizePerChannel": "5",
"IotAnalyticsDefaultChannelName": "my_channel"
}
}
]
}'
```
**注意**
此連接器中的 Lambda 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。
在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。
## 輸入資料
此連接器根據預先定義和客戶定義的 MQTT 主題接受資料。發佈者可以是用戶端裝置、Lambda 函數或其他連接器。
預先定義的主題
連接器支援以下兩個結構化 MQTT 主題，讓發佈方內嵌指定頻道名稱。
+ `iotanalytics/channels/+/messages/put` 主題的[格式化訊息](#iot-analytics-connector-data-input-json)。這些輸入訊息中的 IoT 資料，必須格式化為 JSON 或 base64 編碼字串。
+ 有關 `iotanalytics/channels/+/messages/binary/put` 主題的非格式化訊息。在此主題接收到的輸入訊息皆視為二元資料，可包含任何資料類型。
若要發佈到預先定義的主題，請將 `+` 萬用字元改為管道名稱。例如：
```
iotanalytics/channels/my_channel/messages/put
```
客戶定義的主題
連接器支援 `#` 主題的語法，可接受您在訂閱中配置的任何 MQTT 主題中的輸入訊息。我們建議您指定主題路徑，而不是在訂閱中僅使用`#`萬用字元。這些訊息會傳送到您為連接器指定的預設頻道。
客戶定義主題上的輸入訊息視為二元資料。此類資料可使用任何訊息格式，並包含任何資料類型。您可以使用客戶定義的主題，從發佈至固定主題的裝置路由訊息。您也可以使用它們來接受來自用戶端裝置的輸入資料，這些用戶端裝置無法將資料處理為格式化訊息，以傳送至連接器。
如需更多關於訂閱和 MQTT 主題的資訊，請參閱 [輸入和輸出](connectors.md#connectors-inputs-outputs)。
群組角色必須允許所有目標管道上的 `iotanalytics:BatchPutMessage` 動作。如需詳細資訊，請參閱[要求](#iot-analytics-connector-req)。
**主題篩選條件：** `iotanalytics/channels/+/messages/put`
使用此主題將格式化訊息傳送至連接器，並動態指定目的地頻道。此主題也可讓您指定 ID，在回應輸出中傳回。連接器會驗證所傳送傳出`BatchPutMessage`請求中每個訊息的 IDs 是唯一的 AWS IoT Analytics。ID 重複的訊息會遭到拋棄。
傳送到此主題的輸入資料必須使用下列訊息格式。
**訊息屬性**
`request`
傳送至指定管道的資料。
必要：`true`
類型：`object`包含下列屬性：
`message`
JSON 或 base64 編碼字串的裝置或感應器資料。
必要：`true`
類型：`string`
`id`
請求的任意 ID。此屬性用於將輸入請求映射到輸出回應。當指定時，回應物件中的 `id` 屬性會設為這個值。如果省略此屬性，連接器會產生 ID。
必要：`false`
類型：`string`
有效模式： `.*`
**範例輸入**
```
{
"request": {
"message" : "{\"temp\":23.33}"
},
"id" : "req123"
}
```
**主題篩選條件：** `iotanalytics/channels/+/messages/binary/put`
使用此主題將無格式訊息傳送至連接器，並動態指定目的地頻道。
連接器資料不剖析此主題接收到的輸入訊息。它會將其視為二元資料。在傳送訊息到 之前 AWS IoT Analytics，連接器會編碼並格式化它們以符合 `BatchPutMessage` API 要求：
+ 連接器 base64 編碼原始資料，並將編碼的酬載加入傳出的 `BatchPutMessage` 請求。
+ 連接器會為每個輸入訊息產生和指派 ID。
**注意**
連接器的回應輸出不包含這些輸入訊息的 ID 相關性。
**訊息屬性**
無。
**主題篩選條件：** `#`
使用此主題將任何訊息格式傳送至預設管道。當您的用戶端裝置發佈至固定主題，或您想要將資料從無法以連接器[支援的訊息格式](#iot-analytics-connector-data-input-json)處理資料的用戶端裝置傳送到預設頻道時，這特別有用。
您可以在您建立的訂閱中定義主題語法，以將此連接器連接到資料來源。我們建議您指定主題路徑，而不是在訂閱中僅使用`#`萬用字元。
連接器資料不剖析發佈至此輸入主題的訊息。所有輸入訊息視為二元資料。在傳送訊息到 之前 AWS IoT Analytics，連接器會編碼並格式化它們以符合 `BatchPutMessage` API 要求：
+ 連接器 base64 編碼原始資料，並將編碼的酬載加入傳出的 `BatchPutMessage` 請求。
+ 連接器會為每個輸入訊息產生和指派 ID。
**注意**
連接器的回應輸出不包含這些輸入訊息的 ID 相關性。
**訊息屬性**
無。
## 輸出資料
這個連接器會將狀態資訊發佈為輸出資料，且主題為 MQTT。此資訊包含 AWS IoT Analytics 為其接收和傳送的每個輸入訊息傳回的回應 AWS IoT Analytics。
**訂閱中的主題篩選條件**
`iotanalytics/messages/put/status`
**範例輸出：成功**
```
{
"response" : {
"status" : "success"
},
"id" : "req123"
}
```
**範例輸出：失敗**
```
{
"response" : {
"status" : "fail",
"error" : "ResourceNotFoundException",
"error_message" : "A resource with the specified name could not be found."
},
"id" : "req123"
}
```
如果連接器偵測到可重試的錯誤 （例如連線錯誤），它會在下一個批次中重試發佈。指數退避由 AWS SDK 處理。因可重試錯誤而失敗的請求會加回管道佇列末端，依據 `IotAnalyticsQueueDropBehavior` 參數進一步發佈。
## 用量範例
使用以下高階步驟來設定範例 Python 3.7 Lambda 函數，您可以用來嘗試連接器。
**注意**
如果您使用其他 Python 執行期，則可以建立從 Python3.x 到 Python 3.7 的符號連結。
[連接器入門 (主控台)](connectors-console.md) 和 [連接器入門 (CLI)](connectors-cli.md) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。
1. 確定您符合連接器的[要求](#iot-analytics-connector-req)。
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
1. 建立並發佈 Lambda 函數，將輸入資料傳送至連接器。
將[範例程式碼](#iot-analytics-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. 新增連接器並設定其[參數](#iot-analytics-connector-param)。
1. 新增訂閱，允許連接器在支援主題篩選條件上接收[輸入資料](#iot-analytics-connector-data-input)並傳送[輸出資料](#iot-analytics-connector-data-output)。
+ 將 Lambda 函數設定為來源，將連接器設定為目標，並使用支援的輸入主題篩選條件。
+ 將連接器設為來源、將 AWS IoT Core 設為目標，並使用支援的輸出主題篩選條件。您可以使用此訂閱在 AWS IoT 主控台中檢視狀態訊息。
1. 部署群組。
1. 在 AWS IoT 主控台**的測試**頁面上，訂閱輸出資料主題，以檢視連接器的狀態訊息。Lambda 函數範例為長期函數，並在部署群組後立即開始傳送訊息。
完成測試後，您可以將 Lambda 生命週期設定為隨需 （或在 CLI `"Pinned": false`中） 並部署群組。這會讓函數停止傳送訊息。
### 範例
下列範例 Lambda 函數會將輸入訊息傳送至連接器。
```
import greengrasssdk
import time
import json
iot_client = greengrasssdk.client('iot-data')
send_topic = 'iotanalytics/channels/my_channel/messages/put'
def create_request_with_all_fields():
return {
"request": {
"message" : "{\"temp\":23.33}"
},
"id" : "req_123"
}
def publish_basic_message():
messageToPublish = create_request_with_all_fields()
print("Message To Publish: ", messageToPublish)
iot_client.publish(topic=send_topic,
payload=json.dumps(messageToPublish))
publish_basic_message()
def lambda_handler(event, context):
return
```
## 限制
此連接器受下列限制的約束。
+ 適用於 Python (Boto3) 的 AWS SDK 為 AWS IoT Analytics [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/iotanalytics.html#IoTAnalytics.Client.batch_put_message](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/iotanalytics.html#IoTAnalytics.Client.batch_put_message)動作施加的所有限制。
+ AWS IoT Analytics [ BatchPutMessage](https://docs.aws.amazon.com/iotanalytics/latest/userguide/api.html#cli-iotanalytics-batchputmessage) API 實施的所有配額。如需詳細資訊，請參閱《 AWS IoT Analytics 》中的適用於 的 [ Service Quotas](https://docs.aws.amazon.com/general/latest/gr/iot-analytics.html#limits_iot_analytics)*AWS 一般參考*。
+ 每個管道每秒 100,000 個訊息。
+ 每個批次 100 則訊息。
+ 每則訊息 128 KB。
這個 API 使用管道名稱 (而非管道 ARN)，因此不支援跨區域或跨帳戶管道傳送資料。
+ 核心強制實施的所有配額 AWS IoT Greengrass 。如需詳細資訊，請參閱 中 AWS IoT Greengrass 核心的 [ Service Quotas](https://docs.aws.amazon.com/general/latest/gr/greengrass.html#limits_greengrass)*AWS 一般參考*。
以下配額可能特別適用：
+ 裝置傳送的訊息大小上限為 128 KB。
+ Greengrass 核心路由器中的訊息佇列大小上限為 2.5 MB。
+ 主題字串的長度上限為 256 位元組的 UTF-8 編碼字元。
## 授權
IoT Analytics 連接器包含下列第三方軟體/授權：
+ [適用於 Python (Boto3) 的 AWS SDK](https://pypi.org/project/boto3/)/Apache License 2.0
+ [botocore](https://pypi.org/project/botocore/)/Apache License 2.0
+ [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License
+ [docutils](https://pypi.org/project/docutils/)/BSD 授權、GNU 一般公有授權 (GPL)、Python 軟體基金會授權、公有網域
+ [jmespath](https://pypi.org/project/jmespath/)/MIT License
+ [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0
+ [urllib3](https://pypi.org/project/urllib3/)/MIT License
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明每個版本連接器的變更。
| 版本 | 變更 |
| --- | --- |
| 4 | 新增 `IsolationMode` 參數以設定連接器的容器化模式。 |
| 3 | 將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 |
| 2 | 可減少過多記錄的修正。 |
| 1 | 初始版本。 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
+ *AWS IoT Analytics 使用者指南*中的[什麼是 AWS IoT Analytics？](https://docs.aws.amazon.com/iotanalytics/latest/userguide/welcome.html)
# IoT 乙太網路 IP 通訊協定轉接器連接器
IoT 乙太網路 IP 通訊協定轉接器[連接器](connectors.md)會使用乙太網路/IP 通訊協定從本機裝置收集資料。您可以使用此連接器從多個裝置收集資料，並將其發佈至`StreamManager`訊息串流。
您也可以將此連接器與 IoT SiteWise 連接器和 IoT SiteWise 閘道搭配使用。您的閘道必須提供連接器的組態。如需詳細資訊，請參閱 IoT SiteWise 使用者指南中的[設定乙太網路/IP (EIP) 來源](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/configure-eip-source.html)。
**注意**
此連接器以[無容器](lambda-group-config.md#no-container-mode)隔離模式執行，因此您可以將其部署到在 Docker 容器中執行的 AWS IoT Greengrass 群組。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 2 （建議） | `arn:aws:greengrass:region::/connectors/IoTEIPProtocolAdaptor/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/IoTEIPProtocolAdaptor/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#ethernet-ip-connector-changelog)。
## 要求
此連接器有下列要求：
------
#### [ Version 1 and 2 ]
+ AWS IoT Greengrass 核心軟體 1.10.2 版或更新版本。
+ AWS IoT Greengrass 群組上已啟用串流管理員。
+ 安裝在核心裝置上並新增至`PATH`環境變數的 Java 8。
+ 至少 256 MB 的額外 RAM。此需求是 AWS IoT Greengrass 核心記憶體需求以外的需求。
**注意**
此連接器僅適用於下列區域：
cn-north-1
ap-southeast-1
ap-southeast-2
eu-central-1
eu-west-1
us-east-1
us-west-2
------
## 連接器參數
此連接器支援下列參數：
`LocalStoragePath`
IoT SiteWise 連接器可寫入持久性資料的 AWS IoT Greengrass 主機目錄。預設目錄為 `/var/sitewise`。
AWS IoT 主控台中的顯示名稱：**本機儲存路徑**
必要： `false`
類型：`string`
有效模式： `^\s*$|\/.`
`ProtocolAdapterConfiguration`
連接器從 收集資料或連線的一組乙太網路/IP 收集器組態。這可以是空白清單。
AWS IoT 主控台中的顯示名稱：**通訊協定轉接器組態**
必要： `true`
類型：格式正確的 JSON 字串，定義一組支援的意見回饋組態。
以下是 的範例`ProtocolAdapterConfiguration`：
```
{
"sources": [
{
"type": "EIPSource",
"name": "TestSource",
"endpoint": {
"ipAddress": "52.89.2.42",
"port": 44818
},
"destination": {
"type": "StreamManager",
"streamName": "MyOutput_Stream",
"streamBufferSize": 10
},
"destinationPathPrefix": "EIPSource_Prefix",
"propertyGroups": [
{
"name": "DriveTemperatures",
"scanMode": {
"type": "POLL",
"rate": 10000
},
"tagPathDefinitions": [
{
"type": "EIPTagPath",
"path": "arrayREAL[0]",
"dstDataType": "double"
}
]
}
]
}
]
}
```
### 建立範例連接器 (AWS CLI)
下列 CLI 命令`ConnectorDefinition`會使用包含 IoT 乙太網路 IP 通訊協定轉接器連接器的初始版本來建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version
'{
"Connectors": [
{
"Id": "MyIoTEIPProtocolConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/IoTEIPProtocolAdaptor/versions/2",
"Parameters": {
"ProtocolAdaptorConfiguration": "{ \"sources\": [{ \"type\": \"EIPSource\", \"name\": \"Source1\", \"endpoint\": { \"ipAddress\": \"54.245.77.218\", \"port\": 44818 }, \"destinationPathPrefix\": \"EIPConnector_Prefix\", \"propertyGroups\": [{ \"name\": \"Values\", \"scanMode\": { \"type\": \"POLL\", \"rate\": 2000 }, \"tagPathDefinitions\": [{ \"type\": \"EIPTagPath\", \"path\": \"arrayREAL[0]\", \"dstDataType\": \"double\" }]}]}]}",
"LocalStoragePath": "/var/MyIoTEIPProtocolConnectorState"
}
}
]
}'
```
**注意**
此連接器中的 Lambda 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。
## 輸入資料
此連接器不接受 MQTT 訊息做為輸入資料。
## 輸出資料
此連接器會將資料發佈至 `StreamManager`。您必須設定目的地訊息串流。輸出訊息的結構如下：
```
{
"alias": "string",
"messages": [
{
"name": "string",
"value": boolean|double|integer|string,
"timestamp": number,
"quality": "string"
}
]
}
```
## 授權
IoT 乙太網路 IP 通訊協定轉接器連接器包含下列第三方軟體/授權：
+ [Ethernet/IP 用戶端](https://github.com/digitalpetri/ethernet-ip/blob/master/LICENSE)
+ [MapDB](https://github.com/jankotek/mapdb/blob/master/LICENSE.txt)
+ [斯德羅](https://github.com/jankotek/elsa/blob/master/LICENSE.txt)
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明連接器每個版本中的變更。
| 版本 | 改變 | 日期 |
| --- | --- | --- |
| 2 | 此版本包含錯誤修正。 | 2021 年 12 月 23 日 |
| 1 | 初始版本。 | 2020 年 12 月 15 日 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
# IoT SiteWise 連接器
IoT SiteWise 連接器會將本機裝置和設備資料傳送至其中的資產屬性 AWS IoT SiteWise。您可以使用此連接器從多個 OPC-UA 伺服器收集資料，並將其發佈至 IoT SiteWise。連接器會將資料傳送至目前 AWS 帳戶 和區域中的資產屬性。
**注意**
IoT SiteWise 是一項全受管服務，可從工業裝置和設備收集、處理和視覺化資料。您可以設定資產屬性，以處理從此連接器傳送至資產測量內容的原始資料。例如，您可以定義一個將裝置的攝氏溫度資料點轉換為華氏溫度的轉換屬性，或者定義計算每小時平均溫度的指標屬性。如需詳細資訊，請參閱《 AWS IoT SiteWise使用者指南**》中的[什麼是AWS IoT SiteWise ？](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/)。
連接器使用從 OPC-UA 伺服器傳送的 OPC-UA 資料串流路徑，將資料傳送至 IoT SiteWise。例如，資料串流路徑 `/company/windfarm/3/turbine/7/temperature` 可能代表 3 號風力發電廠 7 號渦輪機的溫度感應器。如果 AWS IoT Greengrass 核心失去與網際網路的連線，連接器會快取資料，直到成功連線至 為止 AWS 雲端。您可以設定用於快取資料的最大磁碟緩衝區大小。如果快取大小超過磁碟緩衝區大小上限，則連接器會捨棄佇列中最舊的資料。
設定和部署 IoT SiteWise 連接器之後，您可以在 [IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)中新增閘道和 OPC-UA 來源。在主控台中設定來源時，您可以篩選或加上 IoT SiteWise 連接器傳送的 OPC-UA 資料串流路徑。如需完成設定閘道和來源的指示，請參閱*AWS IoT SiteWise 《 使用者指南*》中的[新增閘道](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/configure-gateway.html#add-gateway)。
IoT SiteWise 只會從您已映射至 IoT SiteWise 資產測量屬性的資料串流接收資料。若要將資料串流對應至資產屬性，您可以將屬性的別名設定為和 OPC-UA 資料串流路徑相同。若要了解如何定義資產模型和建立資產，請參閱*AWS IoT SiteWise 《 使用者指南*》中的[建立工業資產的模型](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/industrial-asset-models)。
**備註**
您可以使用串流管理員，從 OPC-UA 伺服器以外的來源將資料上傳至 IoT SiteWise。串流管理員也提供可自訂的持久性和頻寬管理支援。如需詳細資訊，請參閱[管理 AWS IoT Greengrass 核心上的資料串流](stream-manager.md)。
此連接器以[無容器](lambda-group-config.md#no-container-mode)隔離模式執行，因此您可以將其部署到在 Docker 容器中執行的 Greengrass 群組。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 12 （建議） | `arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/12` |
| 11 | `arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/11` |
| 10 | `arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/10` |
| 9 | `arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/9` |
| 8 | `arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/8` |
| 7 | `arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/7` |
| 6 | `arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/6` |
| 5 | `arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/5` |
| 4 | `arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/4` |
| 3 | `arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/3` |
| 2 | `arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#iot-sitewise-connector-changelog)。
## 要求
此連接器有下列要求：
------
#### [ Version 9, 10, 11, and 12 ]
**重要**
此版本推出新需求： AWS IoT Greengrass Core 軟體 v1.10.2 和[串流管理員](stream-manager.md)。
+ AWS IoT Greengrass 核心軟體 v1.10.2。
+ 已在 Greengrass 群組上啟用[串流管理員](stream-manager.md)。
+ Java 8 已安裝在核心裝置上並已新增至 PATH 環境變數。
+ 此連接器只能在同時支援 [AWS IoT Greengrass](https://docs.aws.amazon.com/general/latest/gr/greengrass.html)和 [IoT SiteWise](https://docs.aws.amazon.com/general/latest/gr/iot-sitewise.html) 的 Amazon Web Services 區域中使用。
+ 新增至 Greengrass 群組角色的 IAM 政策。此角色允許 AWS IoT Greengrass 群組存取目標根資產及其子系上的 `iotsitewise:BatchPutAssetPropertyValue`動作，如下列範例所示。您可以從`Condition`政策中移除 ，以允許連接器存取所有 IoT SiteWise 資產。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
}
]
}
```
------
如需詳細資訊，請參閱《[IAM 使用者指南》中的新增和移除 IAM 政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。 **
------
#### [ Versions 6, 7, and 8 ]
**重要**
此版本推出新需求： AWS IoT Greengrass Core 軟體 v1.10.0 和[串流管理員](stream-manager.md)。
+ AWS IoT Greengrass 核心軟體 v1.10.0。
+ 已在 Greengrass 群組上啟用[串流管理員](stream-manager.md)。
+ Java 8 已安裝在核心裝置上並已新增至 PATH 環境變數。
+ 此連接器只能在同時支援 [AWS IoT Greengrass](https://docs.aws.amazon.com/general/latest/gr/greengrass.html)和 [IoT SiteWise](https://docs.aws.amazon.com/general/latest/gr/iot-sitewise.html) 的 Amazon Web Services 區域中使用。
+ 新增至 Greengrass 群組角色的 IAM 政策。此角色允許 AWS IoT Greengrass 群組存取目標根資產及其子系上的 `iotsitewise:BatchPutAssetPropertyValue`動作，如下列範例所示。您可以從`Condition`政策中移除 ，以允許連接器存取所有 IoT SiteWise 資產。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
}
]
}
```
------
如需詳細資訊，請參閱《[IAM 使用者指南》中的新增和移除 IAM 政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。 **
------
#### [ Version 5 ]
+ AWS IoT Greengrass 核心軟體 v1.9.4。
+ Java 8 已安裝在核心裝置上並已新增至 PATH 環境變數。
+ 此連接器只能在同時支援 [AWS IoT Greengrass](https://docs.aws.amazon.com/general/latest/gr/greengrass.html)和 [IoT SiteWise](https://docs.aws.amazon.com/general/latest/gr/iot-sitewise.html) 的 Amazon Web Services 區域中使用。
+ 新增至 Greengrass 群組角色的 IAM 政策。此角色允許 AWS IoT Greengrass 群組存取目標根資產及其子系上的 `iotsitewise:BatchPutAssetPropertyValue`動作，如下列範例所示。您可以從`Condition`政策中移除 ，以允許連接器存取所有 IoT SiteWise 資產。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
}
]
}
```
------
如需詳細資訊，請參閱《[IAM 使用者指南》中的新增和移除 IAM 政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。 **
------
#### [ Version 4 ]
+ AWS IoT Greengrass 核心軟體 v1.10.0。
+ Java 8 已安裝在核心裝置上並已新增至 PATH 環境變數。
+ 此連接器只能在同時支援 [AWS IoT Greengrass](https://docs.aws.amazon.com/general/latest/gr/greengrass.html)和 [IoT SiteWise](https://docs.aws.amazon.com/general/latest/gr/iot-sitewise.html) 的 Amazon Web Services 區域中使用。
+ 新增至 Greengrass 群組角色的 IAM 政策。此角色允許 AWS IoT Greengrass 群組存取目標根資產及其子系上的 `iotsitewise:BatchPutAssetPropertyValue`動作，如下列範例所示。您可以從`Condition`政策中移除 ，以允許連接器存取所有 IoT SiteWise 資產。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
}
]
}
```
------
如需詳細資訊，請參閱《[IAM 使用者指南》中的新增和移除 IAM 政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。 **
------
#### [ Version 3 ]
+ AWS IoT Greengrass 核心軟體 v1.9.4。
+ Java 8 已安裝在核心裝置上並已新增至 PATH 環境變數。
+ 此連接器只能在同時支援 [AWS IoT Greengrass](https://docs.aws.amazon.com/general/latest/gr/greengrass.html)和 [IoT SiteWise](https://docs.aws.amazon.com/general/latest/gr/iot-sitewise.html) 的 Amazon Web Services 區域中使用。
+ 新增至 Greengrass 群組角色的 IAM 政策。此角色允許 AWS IoT Greengrass 群組存取目標根資產及其子系上的 `iotsitewise:BatchPutAssetPropertyValue`動作，如下列範例所示。您可以從`Condition`政策中移除 ，以允許連接器存取所有 IoT SiteWise 資產。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
}
]
}
```
------
如需詳細資訊，請參閱《[IAM 使用者指南》中的新增和移除 IAM 政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。 **
------
#### [ Versions 1 and 2 ]
+ AWS IoT Greengrass 核心軟體 v1.9.4。
+ Java 8 已安裝在核心裝置上並已新增至 PATH 環境變數。
+ 此連接器只能在同時支援 [AWS IoT Greengrass](https://docs.aws.amazon.com/general/latest/gr/greengrass.html)和 [IoT SiteWise](https://docs.aws.amazon.com/general/latest/gr/iot-sitewise.html) 的 Amazon Web Services 區域中使用。
+ 新增至 Greengrass 群組角色的 IAM 政策，允許存取目標根資產及其子系上的 和 AWS IoT Core `iotsitewise:BatchPutAssetPropertyValue`動作，如下列範例所示。您可以從`Condition`政策中移除 ，以允許連接器存取所有 IoT SiteWise 資產。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"iot:Connect",
"iot:DescribeEndpoint",
"iot:Publish",
"iot:Receive",
"iot:Subscribe"
],
"Resource": "*"
}
]
}
```
------
如需詳細資訊，請參閱《 IAM 使用者指南》**中的[新增和移除 IAM 身分許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。
------
## Parameters
------
#### [ Versions 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, and 12 ]
`SiteWiseLocalStoragePath`
IoT SiteWise 連接器可寫入持久性資料的 AWS IoT Greengrass 主機目錄。預設為 `/var/sitewise`。
AWS IoT 主控台中的顯示名稱：**本機儲存路徑**
必要：`false`
類型：`string`
有效模式： `^\s*$|\/.`
`AWSSecretsArnList`
中的秘密清單 AWS Secrets Manager ，其中每個都包含 OPC-UA 使用者名稱和密碼金鑰/值對。每個秘密都必須是金鑰/值對類型的秘密。
在 AWS IoT 主控台中顯示名稱：**OPC-UA 使用者名稱/密碼秘密的 ARNs 清單**
必要：`false`
類型：`JsonArrayOfStrings`
有效模式： `\[( ?,? ?\"(arn:(aws(-[a-z]+)*):secretsmanager:[a-z0-9\\-]+:[0-9]{12}:secret:([a-zA-Z0-9\\\\]+\/)*[a-zA-Z0-9\/_+=,.@\\-]+-[a-zA-Z0-9]+)*\")*\]`
`MaximumBufferSize`
IoT SiteWise 磁碟用量的大小上限，以 GB 為單位。預設為 10GB。
AWS IoT 主控台中的顯示名稱：**磁碟緩衝區大小上限**
必要：`false`
類型：`string`
有效模式： `^\s*$|[0-9]+`
------
#### [ Version 1 ]
`SiteWiseLocalStoragePath`
IoT SiteWise 連接器可寫入持久性資料的 AWS IoT Greengrass 主機目錄。預設為 `/var/sitewise`。
AWS IoT 主控台中的顯示名稱：**本機儲存路徑**
必要：`false`
類型：`string`
有效模式： `^\s*$|\/.`
`SiteWiseOpcuaUserIdentityTokenSecretArn`
中 AWS Secrets Manager 包含 OPC-UA 使用者名稱和密碼金鑰值對的秘密。此秘密必須是索引鍵/值組類型的秘密。
在 AWS IoT 主控台中顯示名稱：**OPC-UA 使用者名稱/密碼秘密的 ARN**
必要：`false`
類型：`string`
有效模式： `^$|arn:(aws(-[a-z]+)*):secretsmanager:[a-z0-9\\-]+:[0-9]{12}:secret:([a-zA-Z0-9\\\\]+/)*[a-zA-Z0-9/_+=,.@\\-]+-[a-zA-Z0-9]+`
`SiteWiseOpcuaUserIdentityTokenSecretArn-ResourceId`
AWS IoT Greengrass 群組中參考 OPC-UA 使用者名稱和密碼秘密的秘密資源。
在 AWS IoT 主控台中顯示名稱：**OPC-UA 使用者名稱/密碼秘密資源**
必要：`false`
類型：`string`
有效模式： `^$|.+`
`MaximumBufferSize`
IoT SiteWise 磁碟用量的 GB 大小上限。預設為 10GB。
AWS IoT 主控台中的顯示名稱：**磁碟緩衝區大小上限**
必要：`false`
類型：`string`
有效模式： `^\s*$|[0-9]+`
------
### 建立範例連接器 (AWS CLI)
下列 AWS CLI 命令`ConnectorDefinition`會使用包含 IoT SiteWise 連接器的初始版本來建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MyIoTSiteWiseConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/11"
}
]
}'
```
**注意**
此連接器中的 Lambda 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。
在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。
## 輸入資料
此連接器不接受 MQTT 訊息做為輸入資料。
## 輸出資料
此連接器不會將 MQTT 訊息發佈為輸出資料。
## 限制
此連接器受以下 IoT SiteWise 施加的所有限制的約束，包括以下內容。如需詳細資訊，請參閱《》中的[AWS IoT SiteWise 端點和配額](https://docs.aws.amazon.com/general/latest/gr/iot-sitewise.html)*AWS 一般參考*。
+ 每個閘道的數量上限 AWS 帳戶。
+ 每個閘道的 OPC-UA 來源數目上限。
+ 每個 存放的timestamp-quality-value(TQV) 資料點的最大速率 AWS 帳戶。
+ 每個資產屬性儲存的 TQV 資料點最大速率。
## 授權
------
#### [ Version 9, 10, 11, and 12 ]
IoT SiteWise 連接器包含下列第三方軟體/授權：
+ [MapDB](https://github.com/jankotek/mapdb/blob/master/LICENSE.txt)
+ [埃爾森](https://github.com/jankotek/elsa/blob/master/LICENSE.txt)
+ [Eclipse Milo](https://github.com/eclipse/milo/blob/maintenance/0.2/LICENSE)
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
------
#### [ Versions 6, 7, and 8 ]
IoT SiteWise 連接器包含下列第三方軟體/授權：
+ [Milo](https://github.com/eclipse/milo/) / EDL 1.0
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
------
#### [ Versions 1, 2, 3, 4, and 5 ]
IoT SiteWise 連接器包含下列第三方軟體/授權：
+ [Milo](https://github.com/eclipse/milo/) / EDL 1.0
+ [Chronicle-Queue](https://github.com/OpenHFT/Chronicle-Queue) / Apache License 2.0
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
------
## 變更記錄
下表說明每個版本的連接器的變更。
| 版本 | 改變 | Date |
| --- | --- | --- |
| 12 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/iot-sitewise-connector.html) | 2021 年 12 月 22 日 |
| 11 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/iot-sitewise-connector.html) | 2021 年 3 月 24 日 |
| 10 | 設定為`StreamManager`在來源連線中斷並重新建立時改善處理。當沒有可用`ServerTimestamp`時，此版本也接受 OPC-UA `SourceTimestamp` 值與 。 | 2021 年 1 月 22 日 |
| 9 | 為自訂 Greengrass `StreamManager` 串流目的地、OPC-UA 不動作帶、自訂掃描模式和自訂掃描速率啟動支援。也包括在從 IoT SiteWise 閘道進行組態更新期間改善的效能。 | 2020 年 12 月 15 日 |
| 8 | 改善連接器遇到間歇性網路連線時的穩定性。 | 2020 年 11 月 19 日 |
| 7 | 修正閘道指標的問題。 | 2020 年 8 月 14 日 |
| 6 | 新增對 CloudWatch 指標和自動探索新 OPC-UA 標籤的支援。此版本需要[串流管理員](stream-manager.md)和 AWS IoT Greengrass Core 軟體 v1.10.0 或更高版本。 | 2020 年 4 月 29 日 |
| 5 | 修正 AWS IoT Greengrass Core 軟體 v1.9.4 的相容性問題。 | 2020 年 2 月 12 日 |
| 4 | 已修正 OPC-UA 伺服器重新連線的問題。 | 2020 年 2 月 7 日 |
| 3 | 移除 `iot:*` 許可需求。 | 2019 年 12 月 17 日 |
| 2 | 新增 OPC-UA 秘密資源的支援。 | 2019 年 12 月 10 日 |
| 1 | 初始版本。 | 2019 年 12 月 2 日 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
+ 請參閱*AWS IoT SiteWise 《 使用者指南*》中的下列主題：
+ [什麼是 AWS IoT SiteWise？](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/)
+ [使用閘道](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/gateway-connector.html)
+ [Gateway CloudWatch 指標](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/monitor-cloudwatch-metrics.html#gateway-metrics)
+ [疑難排解 IoT SiteWise 閘道](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/troubleshooting.html#troubleshooting-gateway)
# Kinesis Firehose
Kinesis Firehose [連接器](connectors.md)會透過 Amazon Data Firehose 交付串流將資料發佈至目的地，例如 Amazon S3、Amazon Redshift 或 Amazon OpenSearch Service。
此連接器是 Kinesis 交付串流的資料生產者。它會接收 MQTT 主題上的輸入資料，然後將資料傳送到指定的交付串流。然後，交付串流會將資料記錄傳送到設定的目的地 (例如，S3 儲存貯體)。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 5 | `arn:aws:greengrass:region::/connectors/KinesisFirehose/versions/5` |
| 4 | `arn:aws:greengrass:region::/connectors/KinesisFirehose/versions/4` |
| 3 | `arn:aws:greengrass:region::/connectors/KinesisFirehose/versions/3` |
| 2 | `arn:aws:greengrass:region::/connectors/KinesisFirehose/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/KinesisFirehose/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#kinesis-firehose-connector-changelog)。
## 要求
此連接器有下列要求：
------
#### [ Version 4 - 5 ]
+ AWS IoT Greengrass 核心軟體 v1.9.3 或更新版本。
+ 安裝在核心裝置上並新增至 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 需求。
+ 設定的 Kinesis 交付串流。如需詳細資訊，請參閱[《Amazon Kinesis Firehose 開發人員指南》中的建立 Amazon Data Firehose 交付串流](https://docs.aws.amazon.com/firehose/latest/dev/basic-create.html)。 *Amazon Kinesis Firehose *
+ [Greengrass 群組角色](group-role.md)設定為允許目標交付串流上的 `firehose:PutRecord`和 `firehose:PutRecordBatch`動作，如下列範例 IAM 政策所示。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"Stmt1528133056761",
"Action":[
"firehose:PutRecord",
"firehose:PutRecordBatch"
],
"Effect":"Allow",
"Resource":[
"arn:aws:firehose:us-east-1:123456789012:deliverystream/stream-name"
]
}
]
}
```
------
此連接器可讓您動態覆寫輸入訊息承載中的預設交付串流。如果您的實作使用此功能，IAM 政策應包含所有目標串流做為資源。您可以為資源授予細微或條件式存取 (例如，使用萬用字元 \$1 命名配置)。
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
------
#### [ Versions 2 - 3 ]
+ AWS IoT Greengrass 核心軟體 v1.7 或更新版本。
+ 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 2.7 版。
+ 設定的 Kinesis 交付串流。如需詳細資訊，請參閱[《Amazon Kinesis Firehose 開發人員指南》中的建立 Amazon Data Firehose 交付串流](https://docs.aws.amazon.com/firehose/latest/dev/basic-create.html)。 *Amazon Kinesis Firehose *
+ 設定為允許目標交付串流上 `firehose:PutRecord`和 `firehose:PutRecordBatch`動作的 [Greengrass 群組角色](group-role.md)，如下列範例 IAM 政策所示。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"Stmt1528133056761",
"Action":[
"firehose:PutRecord",
"firehose:PutRecordBatch"
],
"Effect":"Allow",
"Resource":[
"arn:aws:firehose:us-east-1:123456789012:deliverystream/stream-name"
]
}
]
}
```
------
此連接器可讓您動態覆寫輸入訊息承載中的預設交付串流。如果您的實作使用此功能，IAM 政策應包含所有目標串流做為資源。您可以為資源授予細微或條件式存取 (例如，使用萬用字元 \$1 命名配置)。
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
------
#### [ Version 1 ]
+ AWS IoT Greengrass 核心軟體 v1.7 或更新版本。
+ 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 2.7 版。
+ 設定的 Kinesis 交付串流。如需詳細資訊，請參閱[《Amazon Kinesis Firehose 開發人員指南》中的建立 Amazon Data Firehose 交付串流](https://docs.aws.amazon.com/firehose/latest/dev/basic-create.html)。 *Amazon Kinesis Firehose *
+ 設定為允許對目標交付串流`firehose:PutRecord`執行動作的 [Greengrass 群組角色](group-role.md)，如下列範例 IAM 政策所示。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"Stmt1528133056761",
"Action":[
"firehose:PutRecord"
],
"Effect":"Allow",
"Resource":[
"arn:aws:firehose:us-east-1:123456789012:deliverystream/stream-name"
]
}
]
}
```
------
此連接器可讓您動態覆寫輸入訊息承載中的預設交付串流。如果您的實作使用此功能，IAM 政策應包含所有目標串流做為資源。您可以為資源授予細微或條件式存取 (例如，使用萬用字元 \$1 命名配置)。
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
------
## 連接器參數
此連接器提供下列參數：
------
#### [ Versions 5 ]
`DefaultDeliveryStreamArn`
要傳送資料之預設 Firehose 交付串流的 ARN。輸入訊息承載中的 `delivery_stream_arn` 屬性可以覆寫目的地串流。
群組角色必須允許所有目標交付串流上的適當動作。如需詳細資訊，請參閱[要求](#kinesis-firehose-connector-req)。
在 AWS IoT 主控台中顯示名稱：**預設交付串流 ARN**
必要：`true`
類型：`string`
有效模式： `arn:aws:firehose:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):deliverystream/([a-zA-Z0-9_\-.]+)$`
`DeliveryStreamQueueSize`
同樣交付串流的新記錄遭拒絕前，記憶體中保留的記錄數上限。最小值為 2000。
在 AWS IoT 主控台中顯示名稱：**要緩衝的記錄數目上限 （每個串流）**
必要：`true`
類型：`string`
有效模式： `^([2-9]\\d{3}|[1-9]\\d{4,})$`
`MemorySize`
配置給此連接器的記憶體數量 (KB)。
AWS IoT 主控台中的顯示名稱：**記憶體大小**
必要：`true`
類型：`string`
有效模式： `^[0-9]+$`
`PublishInterval`
將記錄發佈至 Firehose 的間隔 （以秒為單位）。若要停止批次處理，請將此數值設為 0。
在 AWS IoT 主控台中顯示名稱：**發佈間隔**
必要：`true`
類型：`string`
有效值：`0 - 900`
有效模式： `[0-9]|[1-9]\\d|[1-9]\\d\\d|900`
`IsolationMode`
此連接器的[容器化](connectors.md#connector-containerization)模式。預設值為 `GreengrassContainer`，這表示連接器會在 AWS IoT Greengrass 容器內的隔離執行時間環境中執行。
群組的預設容器化設定不會套用至連接器。
AWS IoT 主控台中的顯示名稱：**容器隔離模式**
必要：`false`
類型：`string`
有效值：`GreengrassContainer` 或 `NoContainer`
有效模式： `^NoContainer$|^GreengrassContainer$`
------
#### [ Versions 2 - 4 ]
`DefaultDeliveryStreamArn`
要傳送資料之預設 Firehose 交付串流的 ARN。輸入訊息承載中的 `delivery_stream_arn` 屬性可以覆寫目的地串流。
群組角色必須允許所有目標交付串流上的適當動作。如需詳細資訊，請參閱[要求](#kinesis-firehose-connector-req)。
在 AWS IoT 主控台中顯示名稱：**預設交付串流 ARN**
必要：`true`
類型：`string`
有效模式： `arn:aws:firehose:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):deliverystream/([a-zA-Z0-9_\-.]+)$`
`DeliveryStreamQueueSize`
同樣交付串流的新記錄遭拒絕前，記憶體中保留的記錄數上限。最小值為 2000。
在 AWS IoT 主控台中顯示名稱：**要緩衝的記錄數量上限 （每個串流）**
必要：`true`
類型：`string`
有效模式： `^([2-9]\\d{3}|[1-9]\\d{4,})$`
`MemorySize`
配置給此連接器的記憶體數量 (KB)。
AWS IoT 主控台中的顯示名稱：**記憶體大小**
必要：`true`
類型：`string`
有效模式： `^[0-9]+$`
`PublishInterval`
將記錄發佈至 Firehose 的間隔 （以秒為單位）。若要停止批次處理，請將此數值設為 0。
AWS IoT 主控台中的顯示名稱：**發佈間隔**
必要：`true`
類型：`string`
有效值：`0 - 900`
有效模式： `[0-9]|[1-9]\\d|[1-9]\\d\\d|900`
------
#### [ Version 1 ]
`DefaultDeliveryStreamArn`
要傳送資料之預設 Firehose 交付串流的 ARN。輸入訊息承載中的 `delivery_stream_arn` 屬性可以覆寫目的地串流。
群組角色必須允許所有目標交付串流上的適當動作。如需詳細資訊，請參閱[要求](#kinesis-firehose-connector-req)。
在 AWS IoT 主控台中顯示名稱：**預設交付串流 ARN**
必要：`true`
類型：`string`
有效模式： `arn:aws:firehose:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):deliverystream/([a-zA-Z0-9_\-.]+)$`
------
**Example**
**建立連接器範例 (AWS CLI)**
下列 CLI 命令`ConnectorDefinition`會使用包含連接器的初始版本來建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MyKinesisFirehoseConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/KinesisFirehose/versions/5",
"Parameters": {
"DefaultDeliveryStreamArn": "arn:aws:firehose:region:account-id:deliverystream/stream-name",
"DeliveryStreamQueueSize": "5000",
"MemorySize": "65535",
"PublishInterval": "10",
"IsolationMode" : "GreengrassContainer"
}
}
]
}'
```
在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。
## 輸入資料
此連接器接受 MQTT 主題上的串流內容，然後將內容傳送到目標交付串流。它接受兩種輸入資料：
+ `kinesisfirehose/message` 主題上的 JSON 資料。
+ `kinesisfirehose/message/binary/#` 主題上的二進位資料。
------
#### [ Versions 2 - 5 ]
**主題篩選條件：** `kinesisfirehose/message`
使用此主題傳送包含 JSON 資料的訊息。
**訊息屬性**
`request`
要傳送到交付串流和目標交付串流 (如果與預設串流不同) 的資料。
必要：`true`
類型：`object`包含下列屬性：
`data`
要傳送到交付串流的資料。
必要：`true`
類型：`string`
`delivery_stream_arn`
目標 Kinesis 交付串流的 ARN。包含此屬性來覆寫預設的交付串流。
必要：`false`
類型：`string`
有效模式： `arn:aws:firehose:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):deliverystream/([a-zA-Z0-9_\-.]+)$`
`id`
請求的任意 ID。此屬性用於將輸入請求映射到輸出回應。當指定時，回應物件中的 `id` 屬性會設為這個值。如果您不使用此功能，您可以省略此屬性或指定空白字串。
必要：`false`
類型：`string`
有效模式： `.*`
**範例輸入**
```
{
"request": {
"delivery_stream_arn": "arn:aws:firehose:region:account-id:deliverystream/stream2-name",
"data": "Data to send to the delivery stream."
},
"id": "request123"
}
```
**主題篩選條件：** `kinesisfirehose/message/binary/#`
使用此主題傳送包含二進位資料的訊息。連接器不剖析二進位資料。資料會依現狀串流。
若要將輸入請求映射到輸出回應，請將訊息主題中的 `#` 萬用字元換成任意請求 ID。例如，如果您將訊息發佈到 `kinesisfirehose/message/binary/request123`，回應物件中的 `id` 屬性會設為 `request123`。
如果您不想將請求映射到回應，您可以將訊息發佈到 `kinesisfirehose/message/binary/`。請務必包含結尾的斜線。
------
#### [ Version 1 ]
**主題篩選條件：** `kinesisfirehose/message`
使用此主題傳送包含 JSON 資料的訊息。
**訊息屬性**
`request`
要傳送到交付串流和目標交付串流 (如果與預設串流不同) 的資料。
必要：`true`
類型：`object`包含下列屬性：
`data`
要傳送到交付串流的資料。
必要：`true`
類型：`string`
`delivery_stream_arn`
目標 Kinesis 交付串流的 ARN。包含此屬性來覆寫預設的交付串流。
必要：`false`
類型：`string`
有效模式： `arn:aws:firehose:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):deliverystream/([a-zA-Z0-9_\-.]+)$`
`id`
請求的任意 ID。此屬性用於將輸入請求映射到輸出回應。當指定時，回應物件中的 `id` 屬性會設為這個值。如果您不使用此功能，您可以省略此屬性或指定空白字串。
必要：`false`
類型：`string`
有效模式： `.*`
**範例輸入**
```
{
"request": {
"delivery_stream_arn": "arn:aws:firehose:region:account-id:deliverystream/stream2-name",
"data": "Data to send to the delivery stream."
},
"id": "request123"
}
```
**主題篩選條件：** `kinesisfirehose/message/binary/#`
使用此主題傳送包含二進位資料的訊息。連接器不剖析二進位資料。資料會依現狀串流。
若要將輸入請求映射到輸出回應，請將訊息主題中的 `#` 萬用字元換成任意請求 ID。例如，如果您將訊息發佈到 `kinesisfirehose/message/binary/request123`，回應物件中的 `id` 屬性會設為 `request123`。
如果您不想將請求映射到回應，您可以將訊息發佈到 `kinesisfirehose/message/binary/`。請務必包含結尾的斜線。
------
## 輸出資料
這個連接器會將狀態資訊發佈為輸出資料，且主題為 MQTT。
------
#### [ Versions 2 - 5 ]
**訂閱中的主題篩選條件**
`kinesisfirehose/message/status`
**範例輸出**
回應中包含批次中所傳送之各筆資料記錄的狀態。
```
{
"response": [
{
"ErrorCode": "error",
"ErrorMessage": "test error",
"id": "request123",
"status": "fail"
},
{
"firehose_record_id": "xyz2",
"id": "request456",
"status": "success"
},
{
"firehose_record_id": "xyz3",
"id": "request890",
"status": "success"
}
]
}
```
如果連接器偵測到可重試的錯誤 （例如連線錯誤），它會在下一個批次中重試發佈。指數退避由 AWS SDK 處理。因可重試錯誤而失敗的請求會加回佇列末端，進一步發佈。
------
#### [ Version 1 ]
**訂閱中的主題篩選條件**
`kinesisfirehose/message/status`
**範例輸出：成功**
```
{
"response": {
"firehose_record_id": "1lxfuuuFomkpJYzt/34ZU/r8JYPf8Wyf7AXqlXm",
"status": "success"
},
"id": "request123"
}
```
**範例輸出：失敗**
```
{
"response" : {
"error": "ResourceNotFoundException",
"error_message": "An error occurred (ResourceNotFoundException) when calling the PutRecord operation: Firehose test1 not found under account 123456789012.",
"status": "fail"
},
"id": "request123"
}
```
------
## 用量範例
使用下列高階步驟來設定範例 Python 3.7 Lambda 函數，您可以用來嘗試連接器。
**注意**
如果您使用其他 Python 執行期，則可以建立從 Python3.x 到 Python 3.7 的符號連結。
[連接器入門 (主控台)](connectors-console.md) 和 [連接器入門 (CLI)](connectors-cli.md) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。
1. 確定您符合連接器的[要求](#kinesis-firehose-connector-req)。
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
1. 建立並發佈 Lambda 函數，將輸入資料傳送至連接器。
將[範例程式碼](#kinesis-firehose-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. 新增連接器並設定其[參數](#kinesis-firehose-connector-param)。
1. 新增訂閱，允許連接器在支援主題篩選條件上接收 [JSON 輸入資料](#kinesis-firehose-connector-data-input)並傳送[輸出資料](#kinesis-firehose-connector-data-output)。
+ 將 Lambda 函數設定為來源，將連接器設定為目標，並使用支援的輸入主題篩選條件。
+ 將連接器設為來源、將 AWS IoT Core 設為目標，並使用支援的輸出主題篩選條件。您可以使用此訂閱在 AWS IoT 主控台中檢視狀態訊息。
1. 部署群組。
1. 在 AWS IoT 主控台**的測試**頁面上，訂閱輸出資料主題，以檢視連接器的狀態訊息。Lambda 函數範例為長期函數，並在部署群組後立即開始傳送訊息。
完成測試後，您可以將 Lambda 生命週期設定為隨需 （或在 CLI `"Pinned": false`中） 並部署群組。這會讓函數停止傳送訊息。
### 範例
下列範例 Lambda 函數會將輸入訊息傳送至連接器。此訊息包含 JSON 資料。
```
import greengrasssdk
import time
import json
iot_client = greengrasssdk.client('iot-data')
send_topic = 'kinesisfirehose/message'
def create_request_with_all_fields():
return {
"request": {
"data": "Message from Firehose Connector Test"
},
"id" : "req_123"
}
def publish_basic_message():
messageToPublish = create_request_with_all_fields()
print("Message To Publish: ", messageToPublish)
iot_client.publish(topic=send_topic,
payload=json.dumps(messageToPublish))
publish_basic_message()
def lambda_handler(event, context):
return
```
## 授權
Kinesis Firehose 連接器包含下列第三方軟體/授權：
+ [適用於 Python (Boto3) 的 AWS SDK](https://pypi.org/project/boto3/)/Apache License 2.0
+ [botocore](https://pypi.org/project/botocore/)/Apache License 2.0
+ [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License
+ [docutils](https://pypi.org/project/docutils/)/BSD 授權、GNU 一般公有授權 (GPL)、Python 軟體基金會授權、公有網域
+ [jmespath](https://pypi.org/project/jmespath/)/MIT License
+ [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0
+ [urllib3](https://pypi.org/project/urllib3/)/MIT License
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明每個版本連接器的變更。
| 版本 | 變更 |
| --- | --- |
| 5 | 已新增 `IsolationMode` 參數，以設定連接器的容器化模式。 |
| 4 | 將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 |
| 3 | 修正以降低過多記錄，以及其他次要錯誤修正。 |
| 2 | 新增支援以指定間隔將批次資料記錄傳送至 Firehose。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/kinesis-firehose-connector.html) |
| 1 | 初始版本。 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
+ 《[Amazon Kinesis 開發人員指南》中的什麼是 Amazon Kinesis Data Firehose？](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) *Amazon Kinesis *
# ML 回饋連接器
**警告**
此連接器已進入*延長的生命週期階段*，而且 AWS IoT Greengrass 不會發行提供現有功能、增強功能、安全修補程式或錯誤修正的更新。如需詳細資訊，請參閱[AWS IoT Greengrass Version 1 維護政策](maintenance-policy.md)。
ML Feedback 連接器可讓您更輕鬆地存取機器學習 (ML) 模型資料，以進行模型重新訓練和分析。連接器：
+ 將 ML 模型使用的輸入資料 （範例） 上傳至 Amazon S3。模型輸入可以採用任何格式，例如影像、JSON 或音訊。在範例上傳至雲端之後，您可以使用它們來重新訓練模型，以改善其預測的精確性和準確性。例如，您可以使用 [SageMaker AI Ground Truth](https://docs.aws.amazon.com/sagemaker/latest/dg/sms.html) 來標記範例，並使用 [SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/whatis.html) 來重新訓練模型。
+ 以 MQTT 訊息形式發佈模型的預測結果。這可讓您即時監控和分析模型的推論品質。您也可以存放預測結果，並使用它們來分析隨時間變化的趨勢。
+ 將範例上傳和範例資料的指標發佈至 Amazon CloudWatch。
若要設定此連接器，請以 JSON 格式描述支援的*意見回饋組態*。意見回饋組態定義屬性，例如目的地 Amazon S3 儲存貯體、內容類型和[抽樣策略](#ml-feedback-connector-sampling-strategies)。(抽樣策略用來決定要上傳哪些範例。)
您可以在下列案例中使用 ML Feedback 連接器：
+ 使用使用者定義的 Lambda 函數。您的本機推論 Lambda 函數使用 AWS IoT Greengrass Machine Learning SDK 來叫用此連接器，並傳入目標意見回饋組態、模型輸入和模型輸出 （預測結果）。如需範例，請參閱 [用量範例](#ml-feedback-connector-usage)。
+ 使用 [ML Image Classification 連接器](image-classification-connector.md) (v2)。若要搭配 ML Image Classification 連接器使用此連接器，請設定 ML Image Classification 連接器的 `MLFeedbackConnectorConfigId` 參數。
+ 使用 [ML 物件偵測連接器](obj-detection-connector.md)。若要搭配 ML 物件偵測連接器使用此連接器，請設定 ML 物件偵測連接器的 `MLFeedbackConnectorConfigId` 參數。
**ARN**：`arn:aws:greengrass:region::/connectors/MLFeedback/versions/1`
## 要求
此連接器有下列要求：
+ AWS IoT Greengrass 核心軟體 1.9.3 版或更新版本。
+ 安裝在核心裝置上並新增至 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 需求。
+ 一或多個 Amazon S3 儲存貯體。您使用的儲存貯體數量取決於您的取樣策略。
+ [Greengrass 群組角色](group-role.md)設定為允許對目的地 Amazon S3 儲存貯體中的物件`s3:PutObject`執行動作，如下列範例 IAM 政策所示。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:PutObject",
"Resource": [
"arn:aws:s3:::bucket-name/*"
]
}
]
}
```
------
政策應該包含所有目的地儲存貯體做為資源。您可以為資源授予細微或條件式存取 (例如，使用萬用字元 \$1 命名配置)。
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
+ 已將 [CloudWatch Metrics 連接器](cloudwatch-metrics-connector.md)新增至 Greengrass 群組並設定。只有在您想要使用指標報告功能時，才需要此項目。
+ 需要[AWS IoT Greengrass Machine Learning SDK](lambda-functions.md#lambda-sdks-ml) 1.1.0 版才能與此連接器互動。
## Parameters
`FeedbackConfigurationMap`
連接器可用來將範例上傳至 Amazon S3 的一組或多個意見回饋組態。意見回饋組態會定義目的地儲存貯體、內容類型和[抽樣策略](#ml-feedback-connector-sampling-strategies)之類的屬性。叫用此連接器時，呼叫 Lambda 函數或連接器會指定目標意見回饋組態。
AWS IoT 主控台中的顯示名稱：**意見回饋組態映射**
必要：`true`
類型：格式正確的 JSON 字串，定義一組支援的意見回饋組態。如需範例，請參閱 [FeedbackConfigurationMap 範例](#ml-feedback-connector-feedbackconfigmap)。
意見回饋組態物件的 ID 具有下列要求。
ID：
+ 在組態物件之間必須是唯一的。
+ 開頭必須為字母或數字。可以包含大小寫字母、數字與連字號。
+ 長度必須為 2 到 63 個字元。
必要：`true`
類型：`string`
有效模式： `^[a-zA-Z0-9][a-zA-Z0-9-]{1,62}$`
範例：`MyConfig0`、`config-a`、`12id`
意見回饋組態物件的內文包含下列屬性。
`s3-bucket-name`
目的地 Amazon S3 儲存貯體的名稱。
群組角色必須允許在所有目的地儲存貯體上執行 `s3:PutObject` 動作。如需詳細資訊，請參閱[要求](#ml-feedback-connector-req)。
必要：`true`
類型：`string`
有效模式： `^[a-z0-9\.\-]{3,63}$`
`content-type`
要上傳之範例的內容類型。個別意見回饋組態的所有內容必須是相同類型。
必要：`true`
類型：`string`
範例：`image/jpeg`、`application/json`、`audio/ogg`
`s3-prefix`
用於所上傳範例的金鑰前綴。前綴類似於目錄名稱。它可讓您將類似的資料存放在儲存貯體的相同目錄下。如需詳細資訊，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[物件金鑰和中繼資料](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。
必要：`false`
類型：`string`
`file-ext`
用於所上傳範例的副檔名。必須是內容類型的有效副檔名。
必要：`false`
類型：`string`
範例：`jpg`、`json`、`ogg`
`sampling-strategy`
用來篩選要上傳之範例的[抽樣策略](#ml-feedback-connector-sampling-strategies)。如果省略，連接器會嘗試上傳它收到的所有範例。
必要：`false`
類型：格式正確的 JSON 字串，其中包含下列屬性。
`strategy-name`
抽樣策略的名稱。
必要：`true`
類型：`string`
有效值：`RANDOM_SAMPLING`、`LEAST_CONFIDENCE`、`MARGIN` 或 `ENTROPY`
`rate`
[隨機](#ml-feedback-connector-sampling-strategies-random)取樣策略的速率。
必要：`true`如果 `strategy-name`為 `RANDOM_SAMPLING`。
類型：`number`
有效值：`0.0 - 1.0`
`threshold`
[最低可信度](#ml-feedback-connector-sampling-strategies-least-confidence)、[邊界](#ml-feedback-connector-sampling-strategies-margin)或[熵](#ml-feedback-connector-sampling-strategies-entropy)取樣策略的閾值。
必要：`true`如果 `strategy-name`是 `LEAST_CONFIDENCE`、 `MARGIN`或 `ENTROPY`。
類型：`number`
有效值：
+ `0.0 - 1.0`，適用於 `LEAST_CONFIDENCE` 或 `MARGIN` 策略。
+ `0.0 - no limit`，適用於 `ENTROPY` 策略。
`RequestLimit`
連接器一次可處理的請求數量上限。
您可以使用此參數來限制連接器同時處理的要求數量，以限制記憶體消耗。超過此限制的請求會被忽略。
AWS IoT 主控台中的顯示名稱：**請求限制**
必要：`false`
類型：`string`
有效值：`0 - 999`
有效模式： `^$|^[0-9]{1,3}$`
### 建立範例連接器 (AWS CLI)
下列 CLI 命令`ConnectorDefinition`會使用包含 ML Feedback 連接器的初始版本來建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MyMLFeedbackConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/MLFeedback/versions/1",
"Parameters": {
"FeedbackConfigurationMap": "{ \"RandomSamplingConfiguration\": { \"s3-bucket-name\": \"my-aws-bucket-random-sampling\", \"content-type\": \"image/png\", \"file-ext\": \"png\", \"sampling-strategy\": { \"strategy-name\": \"RANDOM_SAMPLING\", \"rate\": 0.5 } }, \"LeastConfidenceConfiguration\": { \"s3-bucket-name\": \"my-aws-bucket-least-confidence-sampling\", \"content-type\": \"image/png\", \"file-ext\": \"png\", \"sampling-strategy\": { \"strategy-name\": \"LEAST_CONFIDENCE\", \"threshold\": 0.4 } } }",
"RequestLimit": "10"
}
}
]
}'
```
### FeedbackConfigurationMap 範例
以下是 `FeedbackConfigurationMap` 參數的擴展範例值。此範例包含數個使用不同取樣策略的意見回饋組態。
```
{
"ConfigID1": {
"s3-bucket-name": "my-aws-bucket-random-sampling",
"content-type": "image/png",
"file-ext": "png",
"sampling-strategy": {
"strategy-name": "RANDOM_SAMPLING",
"rate": 0.5
}
},
"ConfigID2": {
"s3-bucket-name": "my-aws-bucket-margin-sampling",
"content-type": "image/png",
"file-ext": "png",
"sampling-strategy": {
"strategy-name": "MARGIN",
"threshold": 0.4
}
},
"ConfigID3": {
"s3-bucket-name": "my-aws-bucket-least-confidence-sampling",
"content-type": "image/png",
"file-ext": "png",
"sampling-strategy": {
"strategy-name": "LEAST_CONFIDENCE",
"threshold": 0.4
}
},
"ConfigID4": {
"s3-bucket-name": "my-aws-bucket-entropy-sampling",
"content-type": "image/png",
"file-ext": "png",
"sampling-strategy": {
"strategy-name": "ENTROPY",
"threshold": 2
}
},
"ConfigID5": {
"s3-bucket-name": "my-aws-bucket-no-sampling",
"s3-prefix": "DeviceA",
"content-type": "application/json"
}
}
```
### 抽樣策略
連接器支援四種抽樣策略，這些抽樣策略會決定是否要上傳已傳遞至連接器的範例。範例是模型用於預測的離散資料執行個體。您可以使用取樣策略來篩選出最有可能提高模型準確性的範例。
`RANDOM_SAMPLING`
根據提供的速率隨機上傳範例。如果隨機產生的值小於此速率，它會上傳範例。速率越高，上傳的範例越多。
此策略會忽略任何提供的模型預測。
`LEAST_CONFIDENCE`
上傳其最大可信度機率低於所提供閾值的範例。
範例案例：
閾值：`.6`
模型預測：`[.2, .2, .4, .2]`
最大可信度機率：`.4`
結果：
使用範例，因為最大可信度機率 (`.4`) <= 閾值 (`.6`)。
`MARGIN`
如果前兩個可信度機率之間的邊界落在所提供閾值內，則上傳範例。邊界是前兩個機率之間的差異。
範例案例：
閾值：`.02`
模型預測：`[.3, .35, .34, .01]`
前兩個可信度機率：`[.35, .34]`
邊界：`.01` (`.35 - .34`)
結果：
使用範例，因為邊界1 (`.01`) <= 閾值 (`.02`)。
`ENTROPY`
上傳其熵大於所提供閾值的範例。使用模型預測的標準化熵。
範例案例：
閾值：`0.75`
模型預測：`[.5, .25, .25]`
預測的熵：`1.03972`
結果：
使用範例：因為熵 (`1.03972`) > 閾值 (`0.75`)。
## 輸入資料
使用者定義的 Lambda 函數使用 AWS IoT Greengrass Machine Learning SDK 中的 `feedback`用戶端`publish`函數來叫用連接器。如需範例，請參閱 [用量範例](#ml-feedback-connector-usage)。
**注意**
此連接器不接受 MQTT 訊息做為輸入資料。
`publish` 函數採用下列引數：
ConfigId
目標意見回饋組態的 ID。這必須符合 ML 意見回饋連接器的 [FeedbackConfigurationMap](#ml-feedback-connector-param) 參數中定義的意見回饋組態 ID。
必要： true
類型：字串
ModelInput
傳遞至模型以進行推論的輸入資料。除非根據取樣策略將此輸入資料篩選掉， 否則會使用目標組態來上傳此輸入資料。
必要： true
類型：位元組
ModelPrediction
來自模型的預測結果。結果類型可以是字典或清單。例如，ML Image Classification 連接器的預測結果是機率清單 （例如 `[0.25, 0.60, 0.15]`)。此資料會發佈至 `/feedback/message/prediction` 主題。
必要： true
類型：字典或`float`值清單
中繼資料
客戶定義的應用程式特定中繼資料，其會附加至上傳的範例並發佈至 `/feedback/message/prediction` 主題。連接器也會將具有時間戳記值的 `publish-ts` 金鑰插入至中繼資料。
必要：false
類型：字典
範例：`{"some-key": "some value"}`
## 輸出資料
此連接器會將資料發佈至三個 MQTT 主題：
+ 在 `feedback/message/status` 主題上來自連接器的狀態資訊。
+ `feedback/message/prediction` 主題上的預測結果。
+ `cloudwatch/metric/put` 主題上以 CloudWatch 為目標的指標。
您必須設定訂閱，以允許連接器在 MQTT 主題上進行通訊。如需詳細資訊，請參閱[輸入和輸出](connectors.md#connectors-inputs-outputs)。
**主題篩選條件：** `feedback/message/status`
使用此主題來監控範例上傳和所捨棄範例的狀態。每次收到請求時，連接器就會發佈至此主題。
**範例輸出：範例上傳成功**
```
{
"response": {
"status": "success",
"s3_response": {
"ResponseMetadata": {
"HostId": "IOWQ4fDEXAMPLEQM+ey7N9WgVhSnQ6JEXAMPLEZb7hSQDASK+Jd1vEXAMPLEa3Km",
"RetryAttempts": 1,
"HTTPStatusCode": 200,
"RequestId": "79104EXAMPLEB723",
"HTTPHeaders": {
"content-length": "0",
"x-amz-id-2": "lbbqaDVFOhMlyU3gRvAX1ZIdg8P0WkGkCSSFsYFvSwLZk3j7QZhG5EXAMPLEdd4/pEXAMPLEUqU=",
"server": "AmazonS3",
"x-amz-expiration": "expiry-date=\"Wed, 17 Jul 2019 00:00:00 GMT\", rule-id=\"OGZjYWY3OTgtYWI2Zi00ZDllLWE4YmQtNzMyYzEXAMPLEoUw\"",
"x-amz-request-id": "79104EXAMPLEB723",
"etag": "\"b9c4f172e64458a5fd674EXAMPLE5628\"",
"date": "Thu, 11 Jul 2019 00:12:50 GMT",
"x-amz-server-side-encryption": "AES256"
}
},
"bucket": "greengrass-feedback-connector-data-us-west-2",
"ETag": "\"b9c4f172e64458a5fd674EXAMPLE5628\"",
"Expiration": "expiry-date=\"Wed, 17 Jul 2019 00:00:00 GMT\", rule-id=\"OGZjYWY3OTgtYWI2Zi00ZDllLWE4YmQtNzMyYzEXAMPLEoUw\"",
"key": "s3-key-prefix/UUID.file_ext",
"ServerSideEncryption": "AES256"
}
},
"id": "5aaa913f-97a3-48ac-5907-18cd96b89eeb"
}
```
連接器會將 `bucket`和 `key` 欄位新增至來自 Amazon S3 的回應。如需 Amazon S3 回應的詳細資訊，請參閱《*Amazon Simple Storage Service API 參考*》中的 [PUT 物件](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html#RESTObjectPUT-responses)。
**範例輸出：由於取樣策略而捨棄的範例**
```
{
"response": {
"status": "sample_dropped_by_strategy"
},
"id": "4bf5aeb0-d1e4-4362-5bb4-87c05de78ba3"
}
```
**範例輸出：範例上傳失敗**
失敗狀態包含錯誤訊息做為 `error_message` 值，以及例外類別做為 `error` 值。
```
{
"response": {
"status": "fail",
"error_message": "[RequestId: 4bf5aeb0-d1e4-4362-5bb4-87c05de78ba3] Failed to upload model input data due to exception. Model prediction will not be published. Exception type: NoSuchBucket, error: An error occurred (NoSuchBucket) when calling the PutObject operation: The specified bucket does not exist",
"error": "NoSuchBucket"
},
"id": "4bf5aeb0-d1e4-4362-5bb4-87c05de78ba3"
}
```
**範例輸出：由於請求限制而請求調節**
```
{
"response": {
"status": "fail",
"error_message": "Request limit has been reached (max request: 10 ). Dropping request.",
"error": "Queue.Full"
},
"id": "4bf5aeb0-d1e4-4362-5bb4-87c05de78ba3"
}
```
**主題篩選條件：** `feedback/message/prediction`
使用此主題，根據上傳的範例資料接聽預測。這可讓您即時分析您的模型效能。只有當資料成功上傳至 Amazon S3 時，模型預測才會發佈至此主題。在此主題發佈的訊息採用 JSON 格式。它們包含所上傳資料物件的連結、模型的預測，以及請求中包含的中繼資料。
您也可以存放預測結果，並使用它們來報告和分析隨時間變化的趨勢。趨勢可提供寶貴的洞見。例如，*隨著時間準確度降低*趨勢可協助您決定是否需要重新訓練模型。
**範例輸出**
```
{
"source-ref": "s3://greengrass-feedback-connector-data-us-west-2/s3-key-prefix/UUID.file_ext",
"model-prediction": [
0.5,
0.2,
0.2,
0.1
],
"config-id": "ConfigID2",
"metadata": {
"publish-ts": "2019-07-11 00:12:48.816752"
}
}
```
您可以設定 [IoT Analytics 連接器](iot-analytics-connector.md)來訂閱此主題，並將資訊傳送至 AWS IoT Analytics 以進行進一步或歷史分析。
**主題篩選條件：** `cloudwatch/metric/put`
這是用來將指標發佈至 CloudWatch 的輸出主題。此功能需要您安裝和設定 [CloudWatch 指標連接器](cloudwatch-metrics-connector.md)。
指標包括：
+ 上傳的範例數量。
+ 上傳的範例大小。
+ 從 上傳到 Amazon S3 的錯誤數目。
+ 根據抽樣策略捨棄的範例數量。
+ 已調節的請求數目。
**範例輸出：資料範例的大小 (在實際上傳之前發佈)**
```
{
"request": {
"namespace": "GreengrassFeedbackConnector",
"metricData": {
"value": 47592,
"unit": "Bytes",
"metricName": "SampleSize"
}
}
}
```
**範例輸出：範例上傳成功**
```
{
"request": {
"namespace": "GreengrassFeedbackConnector",
"metricData": {
"value": 1,
"unit": "Count",
"metricName": "SampleUploadSuccess"
}
}
}
```
**範例輸出：範例上傳成功，並發佈預測結果**
```
{
"request": {
"namespace": "GreengrassFeedbackConnector",
"metricData": {
"value": 1,
"unit": "Count",
"metricName": "SampleAndPredictionPublished"
}
}
}
```
**範例輸出：範例上傳失敗**
```
{
"request": {
"namespace": "GreengrassFeedbackConnector",
"metricData": {
"value": 1,
"unit": "Count",
"metricName": "SampleUploadFailure"
}
}
}
```
**範例輸出：由於取樣策略而捨棄的範例**
```
{
"request": {
"namespace": "GreengrassFeedbackConnector",
"metricData": {
"value": 1,
"unit": "Count",
"metricName": "SampleNotUsed"
}
}
}
```
**範例輸出：由於請求限制而請求調節**
```
{
"request": {
"namespace": "GreengrassFeedbackConnector",
"metricData": {
"value": 1,
"unit": "Count",
"metricName": "ErrorRequestThrottled"
}
}
}
```
## 用量範例
下列範例是使用者定義的 Lambda 函數，使用[AWS IoT Greengrass Machine Learning SDK](lambda-functions.md#lambda-sdks-ml) 將資料傳送至 ML Feedback 連接器。
**注意**
您可以從 AWS IoT Greengrass [下載頁面](what-is-gg.md#gg-ml-sdk-download)下載 AWS IoT Greengrass Machine Learning SDK。
```
import json
import logging
import os
import sys
import greengrass_machine_learning_sdk as ml
client = ml.client('feedback')
try:
feedback_config_id = os.environ["FEEDBACK_CONFIG_ID"]
model_input_data_dir = os.environ["MODEL_INPUT_DIR"]
model_prediction_str = os.environ["MODEL_PREDICTIONS"]
model_prediction = json.loads(model_prediction_str)
except Exception as e:
logging.info("Failed to open environment variables. Failed with exception:{}".format(e))
sys.exit(1)
try:
with open(os.path.join(model_input_data_dir, os.listdir(model_input_data_dir)[0]), 'rb') as f:
content = f.read()
except Exception as e:
logging.info("Failed to open model input directory. Failed with exception:{}".format(e))
sys.exit(1)
def invoke_feedback_connector():
logging.info("Invoking feedback connector.")
try:
client.publish(
ConfigId=feedback_config_id,
ModelInput=content,
ModelPrediction=model_prediction
)
except Exception as e:
logging.info("Exception raised when invoking feedback connector:{}".format(e))
sys.exit(1)
invoke_feedback_connector()
def function_handler(event, context):
return
```
## 授權
ML 意見回饋連接器包含下列第三方軟體/授權：
+ [適用於 Python (Boto3) 的 AWS SDK](https://pypi.org/project/boto3/)/Apache License 2.0
+ [botocore](https://pypi.org/project/botocore/)/Apache License 2.0
+ [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License
+ [docutils](https://pypi.org/project/docutils/)/BSD 授權、GNU 一般公有授權 (GPL)、Python 軟體基金會授權、公有網域
+ [jmespath](https://pypi.org/project/jmespath/)/MIT License
+ [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0
+ [urllib3](https://pypi.org/project/urllib3/)/MIT License
+ [six](https://github.com/benjaminp/six)/MIT
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
# ML 影像分類連接器
**警告**
此連接器已進入*延長的生命週期階段*，而且 AWS IoT Greengrass 不會發行提供現有功能、增強功能、安全修補程式或錯誤修正的更新。如需詳細資訊，請參閱[AWS IoT Greengrass Version 1 維護政策](maintenance-policy.md)。
ML Image Classification [連接器](connectors.md)提供在 AWS IoT Greengrass 核心上執行的機器學習 (ML) 推論服務。此本機推論服務會使用由 SageMaker AI 影像分類演算法訓練的模型來執行影像分類。
使用者定義的 Lambda 函數使用 AWS IoT Greengrass Machine Learning SDK 向本機推論服務提交推論請求。此服務在本機執行推論，並傳回輸入映像屬於特定類別的機率。
AWS IoT Greengrass 提供下列版本的此連接器，可用於多個平台。
------
#### [ Version 2 ]
| 連接器 | 描述和 ARN |
| --- | --- |
| ML 影像分類 Aarch64 JTX2 | 適用於 NVIDIA Jetson TX2 的映像分類推論服務。支援 GPU 加速。 **ARN**：`arn:aws:greengrass:region::/connectors/ImageClassificationAarch64JTX2/versions/2` |
| ML 影像分類 x86\$164 | 適用於 x86\$164 平台的映像分類推論服務。 **ARN**：`arn:aws:greengrass:region::/connectors/ImageClassificationx86-64/versions/2` |
| ML 影像分類 ARMv7 | 適用於 ARMv7 平台的影像分類推論服務。 **ARN**：`arn:aws:greengrass:region::/connectors/ImageClassificationARMv7/versions/2` |
------
#### [ Version 1 ]
| 連接器 | 描述和 ARN |
| --- | --- |
| ML 影像分類 Aarch64 JTX2 | 適用於 NVIDIA Jetson TX2 的映像分類推論服務。支援 GPU 加速。 **ARN**：`arn:aws:greengrass:region::/connectors/ImageClassificationAarch64JTX2/versions/1` |
| ML 影像分類 x86\$164 | 適用於 x86\$164 平台的映像分類推論服務。 **ARN**：`arn:aws:greengrass:region::/connectors/ImageClassificationx86-64/versions/1` |
| ML 影像分類 Armv7 | 適用於 Armv7 平台的映像分類推論服務。 **ARN**：`arn:aws:greengrass:region::/connectors/ImageClassificationARMv7/versions/1` |
------
如需版本變更的詳細資訊，請參閱 [Changelog](#image-classification-connector-changelog)。
## 要求
這些連接器有下列要求：
------
#### [ Version 2 ]
+ AWS IoT Greengrass 核心軟體 1.9.3 版或更新版本。
+ 安裝在核心裝置上並新增至 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 需求。
+ 對安裝在核心裝置上的 Apache MXNet 架構的相依性。如需詳細資訊，請參閱[在 AWS IoT Greengrass 核心上安裝 MXNet 相依性](#image-classification-connector-config)。
+ Greengrass 群組中參考 SageMaker AI 模型來源的 [ML 資源](ml-inference.md#ml-resources)。此模型必須由 SageMaker AI 影像分類演算法訓練。如需詳細資訊，請參閱《*Amazon SageMaker AI 開發人員指南*》中的[映像分類演算法](https://docs.aws.amazon.com/sagemaker/latest/dg/image-classification.html)。
+ [ML Feedback 連接器](ml-feedback-connector.md)已新增至 Greengrass 群組並設定。只有在您想要使用連接器上傳模型輸入資料，並將預測發佈至 MQTT 主題時，才需要此項目。
+ 設定為允許對目標訓練任務`sagemaker:DescribeTrainingJob`執行動作的 [Greengrass 群組角色](group-role.md)，如下列範例 IAM 政策所示。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sagemaker:DescribeTrainingJob"
],
"Resource": "arn:aws:sagemaker:us-east-1:123456789012:training-job/training-job-name"
}
]
}
```
------
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
您可以為資源授予細微或條件式存取 (例如，使用萬用字元 \$1 命名配置)。如果您未來變更目標訓練任務，請務必更新群組角色。
+ 需要[AWS IoT Greengrass Machine Learning SDK](lambda-functions.md#lambda-sdks-ml) 1.1.0 版才能與此連接器互動。
------
#### [ Version 1 ]
+ AWS IoT Greengrass 核心軟體 1.7 版或更新版本。
+ 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 2.7 版。
+ 對安裝在核心裝置上的 Apache MXNet 架構的相依性。如需詳細資訊，請參閱[在 AWS IoT Greengrass 核心上安裝 MXNet 相依性](#image-classification-connector-config)。
+ Greengrass 群組中參考 SageMaker AI 模型來源的 [ML 資源](ml-inference.md#ml-resources)。此模型必須由 SageMaker AI 影像分類演算法訓練。如需詳細資訊，請參閱《*Amazon SageMaker AI 開發人員指南*》中的[映像分類演算法](https://docs.aws.amazon.com/sagemaker/latest/dg/image-classification.html)。
+ 設定為允許對目標訓練任務執行 `sagemaker:DescribeTrainingJob`動作的 [Greengrass 群組角色](group-role.md)，如下列範例 IAM 政策所示。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sagemaker:DescribeTrainingJob"
],
"Resource": "arn:aws:sagemaker:us-east-1:123456789012:training-job/training-job-name"
}
]
}
```
------
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
您可以為資源授予細微或條件式存取 (例如，使用萬用字元 \$1 命名配置)。如果您未來變更目標訓練任務，請務必更新群組角色。
+ 需要[AWS IoT Greengrass Machine Learning SDK](lambda-functions.md#lambda-sdks-ml) 1.0.0 版或更新版本，才能與此連接器互動。
------
## 連接器參數
這些連接器提供下列參數。
------
#### [ Version 2 ]
`MLModelDestinationPath`
Lambda 環境中 ML 資源的絕對本機路徑。這是指定給機器學習資源的目的地路徑。
如果是在主控台建立機器學習資源，則這是本機路徑。
AWS IoT 主控台中的顯示名稱：**模型目的地路徑**
必要：`true`
類型：`string`
有效模式： `.+`
`MLModelResourceId`
參考來源模型的機器學習資源 ID。
在 AWS IoT 主控台中顯示名稱：**SageMaker 任務 ARN 資源**
必要：`true`
類型：`string`
有效模式： `[a-zA-Z0-9:_-]+`
`MLModelSageMakerJobArn`
代表 SageMaker AI 模型來源的 SageMaker AI 訓練任務 ARN。模型必須由 SageMaker AI 影像分類演算法訓練。
在 AWS IoT 主控台中顯示名稱：**SageMaker 任務 ARN**
必要：`true`
類型：`string`
有效模式： `^arn:aws:sagemaker:[a-zA-Z0-9-]+:[0-9]+:training-job/[a-zA-Z0-9][a-zA-Z0-9-]+$`
`LocalInferenceServiceName`
本機推論服務的名稱。使用者定義的 Lambda 函數透過將名稱傳遞至 AWS IoT Greengrass Machine Learning SDK 的 `invoke_inference_service`函數來叫用服務。如需範例，請參閱 [用量範例](#image-classification-connector-usage)。
AWS IoT 主控台中的顯示名稱：**本機推論服務名稱**
必要：`true`
類型：`string`
有效模式： `[a-zA-Z0-9][a-zA-Z0-9-]{1,62}`
`LocalInferenceServiceTimeoutSeconds`
推論請求終止之前的時間 (以秒為單位)。最小值為 1。
AWS IoT 主控台中的顯示名稱：**逾時 （秒）**
必要：`true`
類型：`string`
有效模式： `[1-9][0-9]*`
`LocalInferenceServiceMemoryLimitKB`
服務可存取的記憶體數量 (KB)。最小值為 1。
AWS IoT 主控台中的顯示名稱：**記憶體限制 (KB)**
必要：`true`
類型：`string`
有效模式： `[1-9][0-9]*`
`GPUAcceleration`
CPU 或 GPU (加速) 運算環境。此屬性僅適用於 ML Image Classification Aarch64 JTX2 連接器。
AWS IoT 主控台中的顯示名稱：**GPU 加速**
必要：`true`
類型：`string`
有效值：`CPU` 或 `GPU`
`MLFeedbackConnectorConfigId`
用來上傳模型輸入資料的意見回饋組態 ID。這必須符合針對 [ML 意見回饋連接器](ml-feedback-connector.md)定義的意見回饋組態 ID。
只有在您想要使用 ML 意見回饋連接器上傳模型輸入資料，並將預測發佈至 MQTT 主題時，才需要此參數。
在 AWS IoT 主控台中顯示名稱：**ML Feedback 連接器組態 ID**
必要：`false`
類型：`string`
有效模式： `^$|^[a-zA-Z0-9][a-zA-Z0-9-]{1,62}$`
------
#### [ Version 1 ]
`MLModelDestinationPath`
Lambda 環境中 ML 資源的絕對本機路徑。這是指定給機器學習資源的目的地路徑。
如果是在主控台建立機器學習資源，則這是本機路徑。
AWS IoT 主控台中的顯示名稱：**模型目的地路徑**
必要：`true`
類型：`string`
有效模式： `.+`
`MLModelResourceId`
參考來源模型的機器學習資源 ID。
在 AWS IoT 主控台中顯示名稱：**SageMaker 任務 ARN 資源**
必要：`true`
類型：`string`
有效模式： `[a-zA-Z0-9:_-]+`
`MLModelSageMakerJobArn`
代表 SageMaker AI 模型來源的 SageMaker AI 訓練任務 ARN。模型必須由 SageMaker AI 影像分類演算法訓練。
在 AWS IoT 主控台中顯示名稱：**SageMaker 任務 ARN**
必要：`true`
類型：`string`
有效模式： `^arn:aws:sagemaker:[a-zA-Z0-9-]+:[0-9]+:training-job/[a-zA-Z0-9][a-zA-Z0-9-]+$`
`LocalInferenceServiceName`
本機推論服務的名稱。使用者定義的 Lambda 函數透過將名稱傳遞至 AWS IoT Greengrass Machine Learning SDK 的 `invoke_inference_service`函數來叫用服務。如需範例，請參閱 [用量範例](#image-classification-connector-usage)。
在 AWS IoT 主控台中顯示名稱：**本機推論服務名稱**
必要：`true`
類型：`string`
有效模式： `[a-zA-Z0-9][a-zA-Z0-9-]{1,62}`
`LocalInferenceServiceTimeoutSeconds`
推論請求終止之前的時間 (以秒為單位)。最小值為 1。
AWS IoT 主控台中的顯示名稱：**逾時 （秒）**
必要：`true`
類型：`string`
有效模式： `[1-9][0-9]*`
`LocalInferenceServiceMemoryLimitKB`
服務可存取的記憶體數量 (KB)。最小值為 1。
AWS IoT 主控台中的顯示名稱：**記憶體限制 (KB)**
必要：`true`
類型：`string`
有效模式： `[1-9][0-9]*`
`GPUAcceleration`
CPU 或 GPU (加速) 運算環境。此屬性僅適用於 ML Image Classification Aarch64 JTX2 連接器。
AWS IoT 主控台中的顯示名稱：**GPU 加速**
必要：`true`
類型：`string`
有效值：`CPU` 或 `GPU`
------
### 建立範例連接器 (AWS CLI)
下列 CLI 命令`ConnectorDefinition`會使用包含 ML Image Classification 連接器的初始版本來建立 。
**範例：CPU 執行個體**
此範例會建立 ML Image Classification Armv7l 連接器的執行個體。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MyImageClassificationConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/ImageClassificationARMv7/versions/2",
"Parameters": {
"MLModelDestinationPath": "/path-to-model",
"MLModelResourceId": "my-ml-resource",
"MLModelSageMakerJobArn": "arn:aws:sagemaker:us-west-2:123456789012:training-job:MyImageClassifier",
"LocalInferenceServiceName": "imageClassification",
"LocalInferenceServiceTimeoutSeconds": "10",
"LocalInferenceServiceMemoryLimitKB": "500000",
"MLFeedbackConnectorConfigId": "MyConfig0"
}
}
]
}'
```
**範例：GPU 執行個體**
此範例會建立 ML Image Classification Aarch64 JTX2 連接器的執行個體，該連接器支援 NVIDIA Jetson TX2 主機板上的 GPU 加速。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MyImageClassificationConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/ImageClassificationAarch64JTX2/versions/2",
"Parameters": {
"MLModelDestinationPath": "/path-to-model",
"MLModelResourceId": "my-ml-resource",
"MLModelSageMakerJobArn": "arn:aws:sagemaker:us-west-2:123456789012:training-job:MyImageClassifier",
"LocalInferenceServiceName": "imageClassification",
"LocalInferenceServiceTimeoutSeconds": "10",
"LocalInferenceServiceMemoryLimitKB": "500000",
"GPUAcceleration": "GPU",
"MLFeedbackConnectorConfigId": "MyConfig0"
}
}
]
}'
```
**注意**
這些連接器中的 Lambda 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。
在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。
## 輸入資料
這些連接器接受影像檔做為輸入。輸入影像檔必須採用 `jpeg` 或 `png` 格式。如需詳細資訊，請參閱[用量範例](#image-classification-connector-usage)。
這些連接器不接受 MQTT 訊息做為輸入資料。
## 輸出資料
這些連接器會傳回輸入影像中所識別物件的格式化預測：
```
[0.3,0.1,0.04,...]
```
預測包含一個清單，列出模型訓練期間與訓練資料集所使用之類別對應的值。每個值代表影像落在對應類別下的機率。具有最高機率的類別是主導預測。
這些連接器不會將 MQTT 訊息發佈為輸出資料。
## 用量範例
下列範例 Lambda 函數使用 [AWS IoT Greengrass Machine Learning SDK](lambda-functions.md#lambda-sdks-ml) 與 ML Image Classification 連接器互動。
**注意**
您可以從[AWS IoT Greengrass Machine Learning開發套件下載頁面下載開發套件](what-is-gg.md#gg-ml-sdk-download)。
範例初始化軟體開發套件用戶端，並同步呼叫軟體開發套件的 `invoke_inference_service` 函數，以叫用本機推論服務。它會傳入演算法類型、服務名稱、映像類型和映像內容。然後，範例會剖析服務回應以獲得機率結果 (預測)。
------
#### [ Python 3.7 ]
```
import logging
from threading import Timer
import numpy as np
import greengrass_machine_learning_sdk as ml
# We assume the inference input image is provided as a local file
# to this inference client Lambda function.
with open('/test_img/test.jpg', 'rb') as f:
content = bytearray(f.read())
client = ml.client('inference')
def infer():
logging.info('invoking Greengrass ML Inference service')
try:
resp = client.invoke_inference_service(
AlgoType='image-classification',
ServiceName='imageClassification',
ContentType='image/jpeg',
Body=content
)
except ml.GreengrassInferenceException as e:
logging.info('inference exception {}("{}")'.format(e.__class__.__name__, e))
return
except ml.GreengrassDependencyException as e:
logging.info('dependency exception {}("{}")'.format(e.__class__.__name__, e))
return
logging.info('resp: {}'.format(resp))
predictions = resp['Body'].read().decode("utf-8")
logging.info('predictions: {}'.format(predictions))
# The connector output is in the format: [0.3,0.1,0.04,...]
# Remove the '[' and ']' at the beginning and end.
predictions = predictions[1:-1]
count = len(predictions.split(','))
predictions_arr = np.fromstring(predictions, count=count, sep=',')
# Perform business logic that relies on the predictions_arr, which is an array
# of probabilities.
# Schedule the infer() function to run again in one second.
Timer(1, infer).start()
return
infer()
def function_handler(event, context):
return
```
------
#### [ Python 2.7 ]
```
import logging
from threading import Timer
import numpy
import greengrass_machine_learning_sdk as gg_ml
# The inference input image.
with open("/test_img/test.jpg", "rb") as f:
content = f.read()
client = gg_ml.client("inference")
def infer():
logging.info("Invoking Greengrass ML Inference service")
try:
resp = client.invoke_inference_service(
AlgoType="image-classification",
ServiceName="imageClassification",
ContentType="image/jpeg",
Body=content,
)
except gg_ml.GreengrassInferenceException as e:
logging.info('Inference exception %s("%s")', e.__class__.__name__, e)
return
except gg_ml.GreengrassDependencyException as e:
logging.info('Dependency exception %s("%s")', e.__class__.__name__, e)
return
logging.info("Response: %s", resp)
predictions = resp["Body"].read()
logging.info("Predictions: %s", predictions)
# The connector output is in the format: [0.3,0.1,0.04,...]
# Remove the '[' and ']' at the beginning and end.
predictions = predictions[1:-1]
predictions_arr = numpy.fromstring(predictions, sep=",")
logging.info("Split into %s predictions.", len(predictions_arr))
# Perform business logic that relies on predictions_arr, which is an array
# of probabilities.
# Schedule the infer() function to run again in one second.
Timer(1, infer).start()
infer()
# In this example, the required AWS Lambda handler is never called.
def function_handler(event, context):
return
```
------
AWS IoT Greengrass Machine Learning SDK 中的 `invoke_inference_service`函數接受下列引數。
| 引數 | Description |
| --- | --- |
| `AlgoType` | 用於推論之演算法類型的名稱。目前僅支援 `image-classification`。 必要：`true` 類型：`string` 有效值：`image-classification` |
| `ServiceName` | 本機推論服務的名稱。使用您設定連接器時為 `LocalInferenceServiceName` 參數指定的名稱。 必要：`true` 類型：`string` |
| `ContentType` | 輸入映像的 mime 類型。 必要：`true` 類型：`string` 有效值：`image/jpeg, image/png` |
| `Body` | 輸入映像檔的內容。 必要：`true` 類型：`binary` |
## 在 AWS IoT Greengrass 核心上安裝 MXNet 相依性
若要使用 ML Image Classification 連接器，您必須在核心裝置上安裝 Apache MXNet 架構的相依性。連接器使用架構來支援機器學習模型。
**注意**
這些連接器隨附預先編譯的 MXNet 程式庫，因此您不需要在核心裝置上安裝 MXNet 架構。
AWS IoT Greengrass 提供指令碼來安裝下列常見平台和裝置的相依性 （或做為安裝它們的參考）。如果您使用的是不同平台或裝置，請參閱 [MXNet 文件](https://mxnet.apache.org/)做為組態的參考。
在安裝 MXNet 相依性之前，請確保所需的[系統程式庫](#image-classification-connector-logging) (使用指定的最低版本) 存在於裝置上。
------
#### [ NVIDIA Jetson TX2 ]
1. 安裝 CUDA Toolkit 9.0 和 cuDNN 7.0。您可以按照入門教學課程的[設定其他裝置](setup-filter.other.md)中的指示。
1. 啟用世界各地的儲存庫，讓連接器可以安裝社群維護的開放式軟體。如需詳細資訊，請參閱 Ubuntu 文件中的[儲存庫/Ubuntu](https://help.ubuntu.com/community/Repositories/Ubuntu)。
1. 開啟 `/etc/apt/sources.list` 檔案。
1. 務必註銷以下幾行。
```
deb http://ports.ubuntu.com/ubuntu-ports/ xenial universe
deb-src http://ports.ubuntu.com/ubuntu-ports/ xenial universe
deb http://ports.ubuntu.com/ubuntu-ports/ xenial-updates universe
deb-src http://ports.ubuntu.com/ubuntu-ports/ xenial-updates universe
```
1. 在核心裝置上將以下安裝指令碼的複本儲存成名為 `nvidiajtx2.sh` 的檔案。
------
#### [ Python 3.7 ]
```
#!/bin/bash
set -e
echo "Installing dependencies on the system..."
echo 'Assuming that universe repos are enabled and checking dependencies...'
apt-get -y update
apt-get -y dist-upgrade
apt-get install -y liblapack3 libopenblas-dev liblapack-dev libatlas-base-dev
apt-get install -y python3.7 python3.7-dev
python3.7 -m pip install --upgrade pip
python3.7 -m pip install numpy==1.15.0
python3.7 -m pip install opencv-python || echo 'Error: Unable to install OpenCV with pip on this platform. Try building the latest OpenCV from source (https://github.com/opencv/opencv).'
echo 'Dependency installation/upgrade complete.'
```
**注意**
如果 [OpenCV](https://github.com/opencv/opencv) 未使用此指令碼成功安裝，您可以嘗試從來源建置。如需詳細資訊，請參閱 OpenCV 文件中的 [Installation in Linux](https://docs.opencv.org/4.1.0/d7/d9f/tutorial_linux_install.html)，或參閱適用於您平台的其他線上資源。
------
#### [ Python 2.7 ]
```
#!/bin/bash
set -e
echo "Installing dependencies on the system..."
echo 'Assuming that universe repos are enabled and checking dependencies...'
apt-get -y update
apt-get -y dist-upgrade
apt-get install -y liblapack3 libopenblas-dev liblapack-dev libatlas-base-dev python-dev
echo 'Install latest pip...'
wget https://bootstrap.pypa.io/get-pip.py
python get-pip.py
rm get-pip.py
pip install numpy==1.15.0 scipy
echo 'Dependency installation/upgrade complete.'
```
------
1. 從您儲存檔案的目錄中，執行下列命令：
```
sudo nvidiajtx2.sh
```
------
#### [ x86\$164 (Ubuntu or Amazon Linux) ]
1. 在核心裝置上將以下安裝指令碼的複本儲存成名為 `x86_64.sh` 的檔案。
------
#### [ Python 3.7 ]
```
#!/bin/bash
set -e
echo "Installing dependencies on the system..."
release=$(awk -F= '/^NAME/{print $2}' /etc/os-release)
if [ "$release" == '"Ubuntu"' ]; then
# Ubuntu. Supports EC2 and DeepLens. DeepLens has all the dependencies installed, so
# this is mostly to prepare dependencies on Ubuntu EC2 instance.
apt-get -y update
apt-get -y dist-upgrade
apt-get install -y libgfortran3 libsm6 libxext6 libxrender1
apt-get install -y python3.7 python3.7-dev
elif [ "$release" == '"Amazon Linux"' ]; then
# Amazon Linux. Expect python to be installed already
yum -y update
yum -y upgrade
yum install -y compat-gcc-48-libgfortran libSM libXrender libXext
else
echo "OS Release not supported: $release"
exit 1
fi
python3.7 -m pip install --upgrade pip
python3.7 -m pip install numpy==1.15.0
python3.7 -m pip install opencv-python || echo 'Error: Unable to install OpenCV with pip on this platform. Try building the latest OpenCV from source (https://github.com/opencv/opencv).'
echo 'Dependency installation/upgrade complete.'
```
**注意**
如果 [OpenCV](https://github.com/opencv/opencv) 未使用此指令碼成功安裝，您可以嘗試從來源建置。如需詳細資訊，請參閱 OpenCV 文件中的 [Installation in Linux](https://docs.opencv.org/4.1.0/d7/d9f/tutorial_linux_install.html)，或參閱適用於您平台的其他線上資源。
------
#### [ Python 2.7 ]
```
#!/bin/bash
set -e
echo "Installing dependencies on the system..."
release=$(awk -F= '/^NAME/{print $2}' /etc/os-release)
if [ "$release" == '"Ubuntu"' ]; then
# Ubuntu. Supports EC2 and DeepLens. DeepLens has all the dependencies installed, so
# this is mostly to prepare dependencies on Ubuntu EC2 instance.
apt-get -y update
apt-get -y dist-upgrade
apt-get install -y libgfortran3 libsm6 libxext6 libxrender1 python-dev python-pip
elif [ "$release" == '"Amazon Linux"' ]; then
# Amazon Linux. Expect python to be installed already
yum -y update
yum -y upgrade
yum install -y compat-gcc-48-libgfortran libSM libXrender libXext python-pip
else
echo "OS Release not supported: $release"
exit 1
fi
pip install numpy==1.15.0 scipy opencv-python
echo 'Dependency installation/upgrade complete.'
```
------
1. 從您儲存檔案的目錄中，執行下列命令：
```
sudo x86_64.sh
```
------
#### [ Armv7 (Raspberry Pi) ]
1. 在核心裝置上將以下安裝指令碼的複本儲存成名為 `armv7l.sh` 的檔案。
------
#### [ Python 3.7 ]
```
#!/bin/bash
set -e
echo "Installing dependencies on the system..."
apt-get update
apt-get -y upgrade
apt-get install -y liblapack3 libopenblas-dev liblapack-dev
apt-get install -y python3.7 python3.7-dev
python3.7 -m pip install --upgrade pip
python3.7 -m pip install numpy==1.15.0
python3.7 -m pip install opencv-python || echo 'Error: Unable to install OpenCV with pip on this platform. Try building the latest OpenCV from source (https://github.com/opencv/opencv).'
echo 'Dependency installation/upgrade complete.'
```
**注意**
如果 [OpenCV](https://github.com/opencv/opencv) 未使用此指令碼成功安裝，您可以嘗試從來源建置。如需詳細資訊，請參閱 OpenCV 文件中的 [Installation in Linux](https://docs.opencv.org/4.1.0/d7/d9f/tutorial_linux_install.html)，或參閱適用於您平台的其他線上資源。
------
#### [ Python 2.7 ]
```
#!/bin/bash
set -e
echo "Installing dependencies on the system..."
apt-get update
apt-get -y upgrade
apt-get install -y liblapack3 libopenblas-dev liblapack-dev python-dev
# python-opencv depends on python-numpy. The latest version in the APT repository is python-numpy-1.8.2
# This script installs python-numpy first so that python-opencv can be installed, and then install the latest
# numpy-1.15.x with pip
apt-get install -y python-numpy python-opencv
dpkg --remove --force-depends python-numpy
echo 'Install latest pip...'
wget https://bootstrap.pypa.io/get-pip.py
python get-pip.py
rm get-pip.py
pip install --upgrade numpy==1.15.0 picamera scipy
echo 'Dependency installation/upgrade complete.'
```
------
1. 從您儲存檔案的目錄中，執行下列命令：
```
sudo bash armv7l.sh
```
**注意**
在 Raspberry Pi 上，使用 `pip` 來安裝機器學習相依性是一種記憶體密集型操作，可能會導致裝置記憶體不足、無法回應。若要解決這項問題，您可以暫時增加交換大小：
在 `/etc/dphys-swapfile` 中，增加 `CONF_SWAPSIZE` 變數的值，然後執行下列命令來重新啟動 `dphys-swapfile`。
```
/etc/init.d/dphys-swapfile restart
```
------
## 記錄和故障診斷
根據您的群組設定，事件和錯誤日誌會寫入 CloudWatch Logs、本機檔案系統或兩者。來自這個連接器的日誌使用字首 `LocalInferenceServiceName`。如果連接器發生非預期的行為，請檢查連接器的日誌。日誌通常會包含有用的偵錯資訊，例如遺失機器學習程式庫相依性或連接器啟動失敗的原因。
如果 AWS IoT Greengrass 群組設定為寫入本機日誌，連接器會將日誌檔案寫入 `greengrass-root/ggc/var/log/user/region/aws/`。如需 Greengrass 記錄的詳細資訊，請參閱 [使用 AWS IoT Greengrass 日誌監控](greengrass-logs-overview.md)。
使用以下資訊來協助疑難排解 ML Image Classification 連接器的問題。
**必要系統程式庫**
下列索引標籤列出每個 ML Image Classification 連接器所需的系統程式庫。
------
#### [ ML Image Classification Aarch64 JTX2 ]
| 程式庫 | 最低版本 |
| --- | --- |
| ld-linux-aarch64.so.1 | GLIBC\$12.17 |
| libc.so.6 | GLIBC\$12.17 |
| libcublas.so.9.0 | 不適用 |
| libcudart.so.9.0 | 不適用 |
| libcudnn.so.7 | 不適用 |
| libcufft.so.9.0 | 不適用 |
| libcurand.so.9.0 | 不適用 |
| libcusolver.so.9.0 | 不適用 |
| libgcc\$1s.so.1 | GCC\$14.2.0 |
| libgomp.so.1 | GOMP\$14.0, OMP\$11.0 |
| libm.so.6 | GLIBC\$12.23 |
| libpthread.so.0 | GLIBC\$12.17 |
| librt.so.1 | GLIBC\$12.17 |
| libstdc\$1\$1.so.6 | GLIBCXX\$13.4.21, CXXABI\$11.3.8 |
------
#### [ ML Image Classification x86\$164 ]
| 程式庫 | 最低版本 |
| --- | --- |
| ld-linux-x86-64.so.2 | GCC\$14.0.0 |
| libc.so.6 | GLIBC\$12.4 |
| libgfortran.so.3 | GFORTRAN\$11.0 |
| libm.so.6 | GLIBC\$12.23 |
| libpthread.so.0 | GLIBC\$12.2.5 |
| librt.so.1 | GLIBC\$12.2.5 |
| libstdc\$1\$1.so.6 | CXXABI\$11.3.8, GLIBCXX\$13.4.21 |
------
#### [ ML Image Classification Armv7 ]
| 程式庫 | 最低版本 |
| --- | --- |
| ld-linux-armhf.so.3 | GLIBC\$12.4 |
| libc.so.6 | GLIBC\$12.7 |
| libgcc\$1s.so.1 | GCC\$14.0.0 |
| libgfortran.so.3 | GFORTRAN\$11.0 |
| libm.so.6 | GLIBC\$12.4 |
| libpthread.so.0 | GLIBC\$12.4 |
| librt.so.1 | GLIBC\$12.4 |
| libstdc\$1\$1.so.6 | CXXABI\$11.3.8、CXXABI\$1ARM\$11.3.3、GLIBCXX\$13.4.20 |
------
**問題**
| 徵狀 | 解決方案 |
| --- | --- |
| 在 Raspberry Pi 上，下列錯誤訊息已記錄，並且您不是使用相機：`Failed to initialize libdc1394` | 執行下列命令以停用驅動程式： sudo ln /dev/null /dev/raw1394
此操作為暫時性，符號連結在重新啟動就會消失。請參閱您作業系統版本的手冊，了解如何在重新啟動時自動建立連結。 |
## 授權
ML Image Classification 連接器包含下列第三方軟體/授權：
+ [適用於 Python (Boto3) 的 AWS SDK](https://pypi.org/project/boto3/)/Apache License 2.0
+ [botocore](https://pypi.org/project/botocore/)/Apache License 2.0
+ [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License
+ [docutils](https://pypi.org/project/docutils/)/BSD 授權、GNU 一般公有授權 (GPL)、Python 軟體基金會授權、公有網域
+ [jmespath](https://pypi.org/project/jmespath/)/MIT License
+ [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0
+ [urllib3](https://pypi.org/project/urllib3/)/MIT License
+ [Deep Neural Network Library (DNNL)](https://github.com/intel/mkl-dnn)/Apache License 2.0
+ [OpenMP\$1 Runtime Library](https://software.intel.com/content/www/us/en/develop/documentation/cpp-compiler-developer-guide-and-reference/top/optimization-and-programming-guide/openmp-support/openmp-library-support/openmp-run-time-library-routines.html)/請參閱 [Intel OpenMP Runtime Library 授權](#openmp-license)。
+ [mxnet](https://pypi.org/project/mxnet/)/Apache License 2.0
+ [six](https://github.com/benjaminp/six)/MIT
**Intel OpenMP Runtime Library 授權**。Intel® OpenMP\$1 執行期是雙重授權，具有商業 (COM) 授權做為 Intel® Parallel Studio XE Suite 產品的一部分，以及 BSD 開放原始碼 (OSS) 授權。
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明每個版本連接器的變更。
| 版本 | 變更 |
| --- | --- |
| 2 | 新增 `MLFeedbackConnectorConfigId` 參數以支援使用 [ML Feedback 連接器](ml-feedback-connector.md)上傳模型輸入資料、將預測發佈至 MQTT 主題，以及將指標發佈至 Amazon CloudWatch。 |
| 1 | 初始版本。 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
+ [執行機器學習推論](ml-inference.md)
+ 《*Amazon SageMaker AI 開發人員指南*》中的[映像分類演算法](https://docs.aws.amazon.com/sagemaker/latest/dg/image-classification.html)
# ML 物件偵測連接器
**警告**
此連接器已進入*延長生命週期階段*， AWS IoT Greengrass 且不會發佈提供現有功能、增強功能、安全修補程式或錯誤修正的更新。如需詳細資訊，請參閱[AWS IoT Greengrass Version 1 維護政策](maintenance-policy.md)。
ML 物件偵測[連接器](connectors.md)提供在 AWS IoT Greengrass 核心上執行的機器學習 (ML) 推論服務。此本機推論服務會使用 SageMaker AI Neo 深度學習編譯器編譯的物件偵測模型來執行物件偵測。支援兩種類型的物件偵測模型：Single Shot Multibox Detector (SSD) 和 You Only Look Once (YOLO) v3。如需詳細資訊，請參閱[物件偵測模型需求](#obj-detection-connector-req-model)。
使用者定義的 Lambda 函數使用 AWS IoT Greengrass Machine Learning SDK 將推論請求提交至本機推論服務。此服務會在輸入影像上執行本機推論，並針對影像中偵測到的每個物件傳回預測清單。每個預測都包含一個物件類別、預測可信度分數，以及指定預測物件之週框方塊的像素座標。
AWS IoT Greengrass 為多個平台提供 ML 物件偵測連接器：
| 連接器 | 描述和 ARN |
| --- | --- |
| ML 物件偵測 Aarch64 JTX2 | 適用於 NVIDIA Jetson TX2 的物件偵測推論服務。支援 GPU 加速。 **ARN**：`arn:aws:greengrass:region::/connectors/ObjectDetectionAarch64JTX2/versions/1` |
| ML 物件偵測 x86\$164 | 適用於 x86\$164 平台的物件偵測推論服務。 **ARN**：`arn:aws:greengrass:region::/connectors/ObjectDetectionx86-64/versions/1` |
| ML 物件偵測 ARMv7 | 適用於 ARMv7 平台的物件偵測推論服務。 **ARN**：`arn:aws:greengrass:region::/connectors/ObjectDetectionARMv7/versions/1` |
## 要求
這些連接器有下列要求：
+ AWS IoT Greengrass 核心軟體 1.9.3 版或更新版本。
+ 安裝在核心裝置上並新增至 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 需求。
+ 核心裝置上安裝的 SageMaker AI Neo 深度學習執行期的相依性。如需詳細資訊，請參閱[在 AWS IoT Greengrass 核心上安裝 Neo 深度學習執行期相依性](#obj-detection-connector-config)。
+ Greengrass 群組中的 [ML 資源](ml-inference.md#ml-resources)。ML 資源必須參考包含物件偵測模型的 Amazon S3 儲存貯體。如需詳細資訊，請參閱 [Amazon S3 模型來源](ml-inference.md#s3-ml-resources)。
**注意**
模型必須是 Single Shot Multibox Detector 或 You Only Look Once v3 物件偵測模型類型。它必須使用 SageMaker AI Neo 深度學習編譯器進行編譯。如需詳細資訊，請參閱[物件偵測模型需求](#obj-detection-connector-req-model)。
+ [ML 意見回饋連接器](ml-feedback-connector.md)已新增至 Greengrass 群組並設定。只有在您想要使用連接器上傳模型輸入資料，並將預測發佈至 MQTT 主題時，才需要此項目。
+ 需要[AWS IoT Greengrass Machine Learning SDK](lambda-functions.md#lambda-sdks-ml) 1.1.0 版才能與此連接器互動。
### 物件偵測模型需求
ML 物件偵測連接器支援單一鏡頭多盒偵測器 (SSD) 和僅監看一次 (YOLO) v3 物件偵測模型類型。您可以使用 [GluonCV](https://gluon-cv.mxnet.io) 提供的物件偵測元件，搭配您自己的資料集來訓練模型。或者，您可以使用來自 GluonCV Model Zoo 的預先訓練模型：
+ [預先訓練的 SSD 模型](https://gluon-cv.mxnet.io/build/examples_detection/demo_ssd.html)
+ [預先訓練的 YOLO v3 模型](https://gluon-cv.mxnet.io/build/examples_detection/demo_yolo.html)
您的物件偵測模型必須使用 512 x 512 輸入影像進行訓練。來自 GluonCV Model Zoo 的預先訓練模型已符合此需求。
訓練過的物件偵測模型必須使用 SageMaker AI Neo 深度學習編譯器進行編譯。編譯時，請確定目標硬體符合 Greengrass 核心裝置的硬體。如需詳細資訊，請參閱《Amazon [ SageMaker AI 開發人員指南》中的 SageMaker AI Neo](https://docs.aws.amazon.com/sagemaker/latest/dg/neo.html)。 *Amazon SageMaker *
編譯的模型必須新增為 ML 資源 ([Amazon S3 模型來源](ml-inference.md#s3-ml-resources)) 到與連接器相同的 Greengrass 群組。
## 連接器參數
這些連接器提供下列參數。
`MLModelDestinationPath`
Amazon S3 儲存貯體的絕對路徑，其中包含 Neo 相容 ML 模型。這是指定給 ML 模型資源的目的地路徑。
AWS IoT 主控台中的顯示名稱：**模型目的地路徑**
必要： `true`
類型：`string`
有效模式： `.+`
`MLModelResourceId`
參考來源模型的機器學習資源 ID。
在 AWS IoT 主控台中顯示名稱：**Greengrass 群組 ML 資源**
必要： `true`
類型：`S3MachineLearningModelResource`
有效模式： `^[a-zA-Z0-9:_-]+$`
`LocalInferenceServiceName`
本機推論服務的名稱。使用者定義的 Lambda 函數透過將名稱傳遞至 AWS IoT Greengrass Machine Learning SDK 的 `invoke_inference_service`函數來叫用服務。如需範例，請參閱「[使用範例](#obj-detection-connector-usage)」。
在 AWS IoT 主控台中顯示名稱：**本機推論服務名稱**
必要： `true`
類型：`string`
有效模式： `^[a-zA-Z0-9][a-zA-Z0-9-]{1,62}$`
`LocalInferenceServiceTimeoutSeconds`
推論請求終止之前的時間 (以秒為單位)。最小值為 1。預設值為 10。
AWS IoT 主控台中的顯示名稱：**逾時 （秒）**
必要： `true`
類型：`string`
有效模式： `^[1-9][0-9]*$`
`LocalInferenceServiceMemoryLimitKB`
服務可存取的記憶體數量 (KB)。最小值為 1。
AWS IoT 主控台中的顯示名稱：**記憶體限制**
必要： `true`
類型：`string`
有效模式： `^[1-9][0-9]*$`
`GPUAcceleration`
CPU 或 GPU (加速) 運算環境。此屬性僅適用於 ML Image Classification Aarch64 JTX2 連接器。
AWS IoT 主控台中的顯示名稱：**GPU 加速**
必要： `true`
類型：`string`
有效值：`CPU` 或 `GPU`
`MLFeedbackConnectorConfigId`
用來上傳模型輸入資料的意見回饋組態 ID。這必須符合針對 [ML 意見回饋連接器](ml-feedback-connector.md)定義的意見回饋組態 ID。
只有在您想要使用 ML 意見回饋連接器上傳模型輸入資料，並將預測發佈至 MQTT 主題時，才需要此參數。
AWS IoT 主控台中的顯示名稱：**ML Feedback 連接器組態 ID**
必要： `false`
類型：`string`
有效模式： `^$|^[a-zA-Z0-9][a-zA-Z0-9-]{1,62}$`
### 建立範例連接器 (AWS CLI)
下列 CLI 命令會使用包含 ML 物件偵測連接器的`ConnectorDefinition`初始版本建立 。此範例會建立 ML 物件偵測 ARMv7l 連接器的執行個體。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MyObjectDetectionConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/ObjectDetectionARMv7/versions/1",
"Parameters": {
"MLModelDestinationPath": "/path-to-model",
"MLModelResourceId": "my-ml-resource",
"LocalInferenceServiceName": "objectDetection",
"LocalInferenceServiceTimeoutSeconds": "10",
"LocalInferenceServiceMemoryLimitKB": "500000",
"MLFeedbackConnectorConfigId" : "object-detector-random-sampling"
}
}
]
}'
```
**注意**
這些連接器中的 Lambda 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。
在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。
## 輸入資料
這些連接器接受影像檔做為輸入。輸入影像檔必須採用 `jpeg` 或 `png` 格式。如需詳細資訊，請參閱[使用範例](#obj-detection-connector-usage)。
這些連接器不接受 MQTT 訊息做為輸入資料。
## 輸出資料
這些連接器會傳回格式化的清單，列出輸入影像中所識別物件的預測結果：
```
{
"prediction": [
[
14,
0.9384938478469849,
0.37763649225234985,
0.5110225081443787,
0.6697432398796082,
0.8544386029243469
],
[
14,
0.8859519958496094,
0,
0.43536216020584106,
0.3314110040664673,
0.9538808465003967
],
[
12,
0.04128098487854004,
0.5976729989051819,
0.5747185945510864,
0.704264223575592,
0.857937216758728
],
...
]
}
```
清單中的每個預測都包含在方括號中，並包含六個值：
+ 第一個值代表所識別物件的預測物件類別。在 Neo 深度學習編譯器中訓練物件偵測機器學習模型時，會決定物件類別及其對應值。
+ 第二個值是物件類別預測的可信度分數。這代表預測正確的機率。
+ 最後四個值對應至像素維度，代表影像中所預測物件的週框方塊。
這些連接器不會將 MQTT 訊息發佈為輸出資料。
## 使用範例
下列範例 Lambda 函數使用[AWS IoT Greengrass Machine Learning開發套件](lambda-functions.md#lambda-sdks-ml)與 ML 物件偵測連接器互動。
**注意**
您可以從[AWS IoT Greengrass Machine Learning開發套件下載頁面下載開發套件](what-is-gg.md#gg-ml-sdk-download)。
範例初始化軟體開發套件用戶端，並同步呼叫軟體開發套件的 `invoke_inference_service` 函數，以叫用本機推論服務。它會傳入演算法類型、服務名稱、映像類型和映像內容。然後，範例會剖析服務回應以獲得機率結果 (預測)。
```
import logging
from threading import Timer
import numpy as np
import greengrass_machine_learning_sdk as ml
# We assume the inference input image is provided as a local file
# to this inference client Lambda function.
with open('/test_img/test.jpg', 'rb') as f:
content = bytearray(f.read())
client = ml.client('inference')
def infer():
logging.info('invoking Greengrass ML Inference service')
try:
resp = client.invoke_inference_service(
AlgoType='object-detection',
ServiceName='objectDetection',
ContentType='image/jpeg',
Body=content
)
except ml.GreengrassInferenceException as e:
logging.info('inference exception {}("{}")'.format(e.__class__.__name__, e))
return
except ml.GreengrassDependencyException as e:
logging.info('dependency exception {}("{}")'.format(e.__class__.__name__, e))
return
logging.info('resp: {}'.format(resp))
predictions = resp['Body'].read().decode("utf-8")
logging.info('predictions: {}'.format(predictions))
predictions = eval(predictions)
# Perform business logic that relies on the predictions.
# Schedule the infer() function to run again in ten second.
Timer(10, infer).start()
return
infer()
def function_handler(event, context):
return
```
AWS IoT Greengrass Machine Learning開發套件中的 `invoke_inference_service`函數接受下列引數。
| 引數 | 描述 |
| --- | --- |
| `AlgoType` | 用於推論之演算法類型的名稱。目前僅支援 `object-detection`。 必要： `true` 類型：`string` 有效值：`object-detection` |
| `ServiceName` | 本機推論服務的名稱。使用您設定連接器時為 `LocalInferenceServiceName` 參數指定的名稱。 必要： `true` 類型：`string` |
| `ContentType` | 輸入映像的 mime 類型。 必要： `true` 類型：`string` 有效值：`image/jpeg, image/png` |
| `Body` | 輸入映像檔的內容。 必要： `true` 類型：`binary` |
## 在 AWS IoT Greengrass 核心上安裝 Neo 深度學習執行期相依性
ML 物件偵測連接器隨附於 SageMaker AI Neo 深度學習執行期 (DLR)。連接器使用執行時間來提供 ML 模型。若要使用這些連接器，您必須在核心裝置上安裝 DLR 的相依性。
在安裝 DLR 相依性之前，請確保所需的[系統程式庫](#obj-detection-connector-logging) (使用指定的最低版本) 存在於裝置上。
------
#### [ NVIDIA Jetson TX2 ]
1. 安裝 CUDA Toolkit 9.0 和 cuDNN 7.0。您可以按照入門教學課程的[設定其他裝置](setup-filter.other.md)中的指示。
1. 啟用世界各地的儲存庫，讓連接器可以安裝社群維護的開放式軟體。如需詳細資訊，請參閱 Ubuntu 文件中的[儲存庫/Ubuntu](https://help.ubuntu.com/community/Repositories/Ubuntu)。
1. 開啟 `/etc/apt/sources.list` 檔案。
1. 務必註銷以下幾行。
```
deb http://ports.ubuntu.com/ubuntu-ports/ xenial universe
deb-src http://ports.ubuntu.com/ubuntu-ports/ xenial universe
deb http://ports.ubuntu.com/ubuntu-ports/ xenial-updates universe
deb-src http://ports.ubuntu.com/ubuntu-ports/ xenial-updates universe
```
1. 在核心裝置上將以下安裝指令碼的複本儲存成名為 `nvidiajtx2.sh` 的檔案。
```
#!/bin/bash
set -e
echo "Installing dependencies on the system..."
echo 'Assuming that universe repos are enabled and checking dependencies...'
apt-get -y update
apt-get -y dist-upgrade
apt-get install -y liblapack3 libopenblas-dev liblapack-dev libatlas-base-dev
apt-get install -y python3.7 python3.7-dev
python3.7 -m pip install --upgrade pip
python3.7 -m pip install numpy==1.15.0
python3.7 -m pip install opencv-python || echo 'Error: Unable to install OpenCV with pip on this platform. Try building the latest OpenCV from source (https://github.com/opencv/opencv).'
echo 'Dependency installation/upgrade complete.'
```
**注意**
如果 [OpenCV](https://github.com/opencv/opencv) 未使用此指令碼成功安裝，您可以嘗試從來源建置。如需詳細資訊，請參閱 OpenCV 文件中的 [Installation in Linux](https://docs.opencv.org/4.1.0/d7/d9f/tutorial_linux_install.html)，或參閱適用於您平台的其他線上資源。
1. 從您儲存檔案的目錄中，執行下列命令：
```
sudo nvidiajtx2.sh
```
------
#### [ x86\$164 (Ubuntu or Amazon Linux) ]
1. 在核心裝置上將以下安裝指令碼的複本儲存成名為 `x86_64.sh` 的檔案。
```
#!/bin/bash
set -e
echo "Installing dependencies on the system..."
release=$(awk -F= '/^NAME/{print $2}' /etc/os-release)
if [ "$release" == '"Ubuntu"' ]; then
# Ubuntu. Supports EC2 and DeepLens. DeepLens has all the dependencies installed, so
# this is mostly to prepare dependencies on Ubuntu EC2 instance.
apt-get -y update
apt-get -y dist-upgrade
apt-get install -y libgfortran3 libsm6 libxext6 libxrender1
apt-get install -y python3.7 python3.7-dev
elif [ "$release" == '"Amazon Linux"' ]; then
# Amazon Linux. Expect python to be installed already
yum -y update
yum -y upgrade
yum install -y compat-gcc-48-libgfortran libSM libXrender libXext
else
echo "OS Release not supported: $release"
exit 1
fi
python3.7 -m pip install --upgrade pip
python3.7 -m pip install numpy==1.15.0
python3.7 -m pip install opencv-python || echo 'Error: Unable to install OpenCV with pip on this platform. Try building the latest OpenCV from source (https://github.com/opencv/opencv).'
echo 'Dependency installation/upgrade complete.'
```
**注意**
如果 [OpenCV](https://github.com/opencv/opencv) 未使用此指令碼成功安裝，您可以嘗試從來源建置。如需詳細資訊，請參閱 OpenCV 文件中的 [Installation in Linux](https://docs.opencv.org/4.1.0/d7/d9f/tutorial_linux_install.html)，或參閱適用於您平台的其他線上資源。
1. 從您儲存檔案的目錄中，執行下列命令：
```
sudo x86_64.sh
```
------
#### [ ARMv7 (Raspberry Pi) ]
1. 在核心裝置上將以下安裝指令碼的複本儲存成名為 `armv7l.sh` 的檔案。
```
#!/bin/bash
set -e
echo "Installing dependencies on the system..."
apt-get update
apt-get -y upgrade
apt-get install -y liblapack3 libopenblas-dev liblapack-dev
apt-get install -y python3.7 python3.7-dev
python3.7 -m pip install --upgrade pip
python3.7 -m pip install numpy==1.15.0
python3.7 -m pip install opencv-python || echo 'Error: Unable to install OpenCV with pip on this platform. Try building the latest OpenCV from source (https://github.com/opencv/opencv).'
echo 'Dependency installation/upgrade complete.'
```
**注意**
如果 [OpenCV](https://github.com/opencv/opencv) 未使用此指令碼成功安裝，您可以嘗試從來源建置。如需詳細資訊，請參閱 OpenCV 文件中的 [Installation in Linux](https://docs.opencv.org/4.1.0/d7/d9f/tutorial_linux_install.html)，或參閱適用於您平台的其他線上資源。
1. 從您儲存檔案的目錄中，執行下列命令：
```
sudo bash armv7l.sh
```
**注意**
在 Raspberry Pi 上，使用 `pip` 來安裝機器學習相依性是一種記憶體密集型操作，可能會導致裝置記憶體不足、無法回應。若要解決這項問題，您可以暫時增加交換大小。在 `/etc/dphys-swapfile` 中，增加 `CONF_SWAPSIZE` 變數的值，然後執行下列命令來重新啟動 `dphys-swapfile`。
```
/etc/init.d/dphys-swapfile restart
```
------
## 記錄和故障診斷
根據您的群組設定，事件和錯誤日誌會寫入 CloudWatch Logs、本機檔案系統或兩者。來自這個連接器的日誌使用字首 `LocalInferenceServiceName`。如果連接器發生非預期的行為，請檢查連接器的日誌。日誌通常會包含有用的偵錯資訊，例如遺失機器學習程式庫相依性或連接器啟動失敗的原因。
如果 AWS IoT Greengrass 群組設定為寫入本機日誌，連接器會將日誌檔案寫入 `greengrass-root/ggc/var/log/user/region/aws/`。如需 Greengrass 記錄的詳細資訊，請參閱 [使用 AWS IoT Greengrass 日誌監控](greengrass-logs-overview.md)。
使用下列資訊，以協助針對 ML 物件偵測連接器的問題進行故障診斷。
**必要系統程式庫**
下列索引標籤列出每個 ML 物件偵測連接器所需的系統程式庫。
------
#### [ ML Object Detection Aarch64 JTX2 ]
| 程式庫 | 最低版本 |
| --- | --- |
| ld-linux-aarch64.so.1 | GLIBC\$12.17 |
| libc.so.6 | GLIBC\$12.17 |
| libcublas.so.9.0 | 不適用 |
| libcudart.so.9.0 | 不適用 |
| libcudnn.so.7 | 不適用 |
| libcufft.so.9.0 | 不適用 |
| libcurand.so.9.0 | 不適用 |
| libcusolver.so.9.0 | 不適用 |
| libgcc\$1s.so.1 | GCC\$14.2.0 |
| libgomp.so.1 | GOMP\$14.0, OMP\$11.0 |
| libm.so.6 | GLIBC\$12.23 |
| libnvinfer.so.4 | 不適用 |
| libnvrm\$1gpu.so | 不適用 |
| libnvrm.so | 不適用 |
| libnvidia-fatbinaryloader.so.28.2.1 | 不適用 |
| libnvos.so | 不適用 |
| libpthread.so.0 | GLIBC\$12.17 |
| librt.so.1 | GLIBC\$12.17 |
| libstdc\$1\$1.so.6 | GLIBCXX\$13.4.21, CXXABI\$11.3.8 |
------
#### [ ML Object Detection x86\$164 ]
| 程式庫 | 最低版本 |
| --- | --- |
| ld-linux-x86-64.so.2 | GCC\$14.0.0 |
| libc.so.6 | GLIBC\$12.4 |
| libgfortran.so.3 | GFORTRAN\$11.0 |
| libm.so.6 | GLIBC\$12.23 |
| libpthread.so.0 | GLIBC\$12.2.5 |
| librt.so.1 | GLIBC\$12.2.5 |
| libstdc\$1\$1.so.6 | CXXABI\$11.3.8, GLIBCXX\$13.4.21 |
------
#### [ ML Object Detection ARMv7 ]
| 程式庫 | 最低版本 |
| --- | --- |
| ld-linux-armhf.so.3 | GLIBC\$12.4 |
| libc.so.6 | GLIBC\$12.7 |
| libgcc\$1s.so.1 | GCC\$14.0.0 |
| libgfortran.so.3 | GFORTRAN\$11.0 |
| libm.so.6 | GLIBC\$12.4 |
| libpthread.so.0 | GLIBC\$12.4 |
| librt.so.1 | GLIBC\$12.4 |
| libstdc\$1\$1.so.6 | CXXABI\$11.3.8、CXXABI\$1ARM\$11.3.3、GLIBCXX\$13.4.20 |
------
**問題**
| 徵狀 | 解決方案 |
| --- | --- |
| 在 Raspberry Pi 上，下列錯誤訊息已記錄，並且您不是使用相機：`Failed to initialize libdc1394` | 執行下列命令以停用驅動程式： sudo ln /dev/null /dev/raw1394
此為是暫時性的操作。符號連結會在您重新啟動後消失。請參閱您作業系統版本的手冊，了解如何在重新啟動時自動建立連結。 |
## 授權
ML 物件偵測連接器包含下列第三方軟體/授權：
+ [適用於 Python (Boto3) 的 AWS SDK](https://pypi.org/project/boto3/)/Apache License 2.0
+ [botocore](https://pypi.org/project/botocore/)/Apache License 2.0
+ [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License
+ [docutils](https://pypi.org/project/docutils/)/BSD 授權、GNU 一般公有授權 (GPL)、Python 軟體基金會授權、公有網域
+ [jmespath](https://pypi.org/project/jmespath/)/MIT License
+ [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0
+ [urllib3](https://pypi.org/project/urllib3/)/MIT License
+ [深度學習執行時間](https://github.com/neo-ai/neo-ai-dlr)/Apache License 2.0
+ [six](https://github.com/benjaminp/six)/MIT
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
+ [執行機器學習推論](ml-inference.md)
+ 《*Amazon SageMaker AI 開發人員指南*》中的[物件偵測演算法](https://docs.aws.amazon.com/sagemaker/latest/dg/object-detection.html)
# Modbus-RTU 通訊協定轉接器連接器
Modbus-RTU 通訊協定轉接器[連接器](connectors.md)會從 AWS IoT Greengrass 群組中的 Modbus RTU 裝置輪詢資訊。
此連接器會從使用者定義的 Lambda 函數接收 Modbus RTU 請求的參數。它會傳送對應的請求，然後從目標裝置發佈回應做為 MQTT 訊息。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 3 | `arn:aws:greengrass:region::/connectors/ModbusRTUProtocolAdapter/versions/3` |
| 2 | `arn:aws:greengrass:region::/connectors/ModbusRTUProtocolAdapter/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/ModbusRTUProtocolAdapter/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#modbus-protocol-adapter-connector-changelog)。
## 要求
此連接器有下列要求：
------
#### [ Version 3 ]
+ AWS IoT Greengrass 核心軟體 1.9.3 版或更新版本。
+ 安裝在核心裝置上並新增至 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 需求。
+ AWS IoT Greengrass 核心和 Modbus 裝置之間的實體連線。核心必須透過序列埠 (例如 USB 連接埠) 實際連接到 RTU Modbus 網路。
+ Greengrass 群組中的[本機裝置資源](access-local-resources.md)，指向實體 Modbus 序列埠。
+ 使用者定義的 Lambda 函數，會將 Modbus RTU 請求參數傳送至此連接器。此請求參數必須符合預期模式，且包含 Modbus RTU 網路上目標裝置的 ID 和地址。如需詳細資訊，請參閱[輸入資料](#modbus-protocol-adapter-connector-data-input)。
------
#### [ Versions 1 - 2 ]
+ AWS IoT Greengrass 核心軟體 1.7 版或更新版本。
+ 核心裝置上安裝並新增至 PATH 環境變數的 [Python](https://www.python.org/) 2.7 版。
+ AWS IoT Greengrass 核心和 Modbus 裝置之間的實體連線。核心必須透過序列埠 (例如 USB 連接埠) 實際連接到 RTU Modbus 網路。
+ Greengrass 群組中的[本機裝置資源](access-local-resources.md)，指向實體 Modbus 序列埠。
+ 使用者定義的 Lambda 函數，會將 Modbus RTU 請求參數傳送至此連接器。此請求參數必須符合預期模式，且包含 Modbus RTU 網路上目標裝置的 ID 和地址。如需詳細資訊，請參閱[輸入資料](#modbus-protocol-adapter-connector-data-input)。
------
## 連接器參數
此連接器支援下列參數：
`ModbusSerialPort-ResourceId`
代表實體 Modbus 序列埠的本機裝置資源 ID。
此連接器已授予資源的讀寫存取權。
AWS IoT 主控台中的顯示名稱：**Modbus 序列連接埠資源**
必要： `true`
類型：`string`
有效模式： `.+`
`ModbusSerialPort`
裝置上實體 Modbus 序列埠的絕對路徑。這是指定給 Modbus 本機裝置資源的來源路徑。
AWS IoT 主控台中的顯示名稱：**Modbus 序列連接埠資源的來源路徑**
必要： `true`
類型：`string`
有效模式： `.+`
### 建立範例連接器 (AWS CLI)
下列 CLI 命令`ConnectorDefinition`會使用包含 Modbus-RTU 通訊協定轉接器連接器的初始版本來建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MyModbusRTUProtocolAdapterConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/ModbusRTUProtocolAdapter/versions/3",
"Parameters": {
"ModbusSerialPort-ResourceId": "MyLocalModbusSerialPort",
"ModbusSerialPort": "/path-to-port"
}
}
]
}'
```
**注意**
此連接器中的 Lambda 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。
在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。
**注意**
部署 Modbus-RTU 通訊協定轉接器連接器之後，您可以使用 AWS IoT Things Graph 來協調 群組中裝置之間的互動。如需詳細資訊，請參閱*AWS IoT Things Graph 《 使用者指南*》中的 [Modbus](https://docs.aws.amazon.com/thingsgraph/latest/ug/iot-tg-protocols-modbus.html)。
## 輸入資料
此連接器接受 MQTT 主題上使用者定義 Lambda 函數的 Modbus RTU 請求參數。輸入訊息必須是 JSON 格式。
**訂閱中的主題篩選條件**
`modbus/adapter/request`
**訊息屬性**
請求訊息隨著其所代表的 Modbus RTU 請求類型而不同。所有請求需要下列屬性：
+ 在 `request` 物件中：
+ `operation`。 要執行的操作名稱。例如，指定 `"operation": "ReadCoilsRequest"` 以讀取線圈。這個值必須是 Unicode 字串。如需支援的作業，請參閱 [Modbus RTU 請求和回應](#modbus-protocol-adapter-connector-requests-responses)。
+ `device`。 請求的目標裝置。此值必須介於 `0 - 247` 之間。
+ `id` 屬性。請求的 ID。這個值用於重複資料刪除，並在所有回應的 `id` 屬性中依現狀傳回，包括錯誤回應。這個值必須是 Unicode 字串。
如果您的請求中包含地址欄位，則必須將該值指定為整數。例如：`"address": 1`。
要包含在請求中的其他參數取決於操作。除了 CRC (另外處理)，所有請求參數都是必要。如需範例，請參閱 [範例請求和回應](#modbus-protocol-adapter-connector-examples)。
**範例輸入：讀取線圈請求**
```
{
"request": {
"operation": "ReadCoilsRequest",
"device": 1,
"address": 1,
"count": 1
},
"id": "TestRequest"
}
```
## 輸出資料
此連接器將回應發佈到傳入 Modbus RTU 請求。
**訂閱中的主題篩選條件**
`modbus/adapter/response`
**訊息屬性**
回應訊息的格式根據對應的請求和回應狀態而不同。如需範例，請參閱 [範例請求和回應](#modbus-protocol-adapter-connector-examples)。
寫入操作的回應只是請求的回響。雖然寫入回應沒有傳回有意義的資訊，建議檢查回應的狀態。
每個回應含有以下屬性：
+ 在 `response` 物件中：
+ `status`。 請求的狀態。狀態可以是下列其中一個值：
+ `Success`。 請求有效、傳送至 Modbus RTU 網路，並傳回回應。
+ `Exception`。 請求有效，已傳送至 Modbus RTU 網路，並傳回例外狀況回應。如需詳細資訊，請參閱[回應狀態：例外](#modbus-protocol-adapter-connector-response-exception)。
+ `No Response`。 請求無效，連接器在透過 Modbus RTU 網路傳送請求之前發現錯誤。如需詳細資訊，請參閱[回應狀態：沒有回應](#modbus-protocol-adapter-connector-response-noresponse)。
+ `device`。 傳送請求的裝置。
+ `operation`。 傳送的請求類型。
+ `payload`。 傳回的回應內容。如果 `status` 是 `No Response`，此物件只包含 `error` 屬性和錯誤描述 (例如，`"error": "[Input/Output] No Response received from the remote unit"`)。
+ `id` 屬性。用於資料重複刪除的請求 ID。
**範例輸出：成功**
```
{
"response" : {
"status" : "success",
"device": 1,
"operation": "ReadCoilsRequest",
"payload": {
"function_code": 1,
"bits": [1]
}
},
"id" : "TestRequest"
}
```
**範例輸出：失敗**
```
{
"response" : {
"status" : "fail",
"error_message": "Internal Error",
"error": "Exception",
"device": 1,
"operation": "ReadCoilsRequest",
"payload": {
"function_code": 129,
"exception_code": 2
}
},
"id" : "TestRequest"
}
```
如需更多範例，請參閱[範例請求和回應](#modbus-protocol-adapter-connector-examples)。
## Modbus RTU 請求和回應
此連接器接受 Modbus RTU 請求參數做為[輸入資料](#modbus-protocol-adapter-connector-data-input)，並發佈回應做為[輸出資料](#modbus-protocol-adapter-connector-data-output)。
以下是支援的常見操作。
| 請求中的作業名稱 | 回應中的函數代碼 |
| --- | --- |
| ReadCoilsRequest | 01 |
| ReadDiscreteInputsRequest | 02 |
| ReadHoldingRegistersRequest | 03 |
| ReadInputRegistersRequest | 04 |
| WriteSingleCoilRequest | 05 |
| WriteSingleRegisterRequest | 06 |
| WriteMultipleCoilsRequest | 15 |
| WriteMultipleRegistersRequest | 16 |
| MaskWriteRegisterRequest | 22 |
| ReadWriteMultipleRegistersRequest | 23 |
### 範例請求和回應
以下是受支援操作的範例請求和回應。
讀取線圈
**請求範例：**
```
{
"request": {
"operation": "ReadCoilsRequest",
"device": 1,
"address": 1,
"count": 1
},
"id": "TestRequest"
}
```
**回應範例：**
```
{
"response": {
"status": "success",
"device": 1,
"operation": "ReadCoilsRequest",
"payload": {
"function_code": 1,
"bits": [1]
}
},
"id" : "TestRequest"
}
```
讀取離散輸入
**請求範例：**
```
{
"request": {
"operation": "ReadDiscreteInputsRequest",
"device": 1,
"address": 1,
"count": 1
},
"id": "TestRequest"
}
```
**回應範例：**
```
{
"response": {
"status": "success",
"device": 1,
"operation": "ReadDiscreteInputsRequest",
"payload": {
"function_code": 2,
"bits": [1]
}
},
"id" : "TestRequest"
}
```
讀取保留暫存器
**請求範例：**
```
{
"request": {
"operation": "ReadHoldingRegistersRequest",
"device": 1,
"address": 1,
"count": 1
},
"id": "TestRequest"
}
```
**回應範例：**
```
{
"response": {
"status": "success",
"device": 1,
"operation": "ReadHoldingRegistersRequest",
"payload": {
"function_code": 3,
"registers": [20,30]
}
},
"id" : "TestRequest"
}
```
讀取輸入暫存器
**請求範例：**
```
{
"request": {
"operation": "ReadInputRegistersRequest",
"device": 1,
"address": 1,
"value": 1
},
"id": "TestRequest"
}
```
寫入單一線圈
**請求範例：**
```
{
"request": {
"operation": "WriteSingleCoilRequest",
"device": 1,
"address": 1,
"value": 1
},
"id": "TestRequest"
}
```
**回應範例：**
```
{
"response": {
"status": "success",
"device": 1,
"operation": "WriteSingleCoilRequest",
"payload": {
"function_code": 5,
"address": 1,
"value": true
}
},
"id" : "TestRequest"
```
寫入單一暫存器
**請求範例：**
```
{
"request": {
"operation": "WriteSingleRegisterRequest",
"device": 1,
"address": 1,
"value": 1
},
"id": "TestRequest"
}
```
寫入多個線圈
**請求範例：**
```
{
"request": {
"operation": "WriteMultipleCoilsRequest",
"device": 1,
"address": 1,
"values": [1,0,0,1]
},
"id": "TestRequest"
}
```
**回應範例：**
```
{
"response": {
"status": "success",
"device": 1,
"operation": "WriteMultipleCoilsRequest",
"payload": {
"function_code": 15,
"address": 1,
"count": 4
}
},
"id" : "TestRequest"
}
```
寫入多個暫存器
**請求範例：**
```
{
"request": {
"operation": "WriteMultipleRegistersRequest",
"device": 1,
"address": 1,
"values": [20,30,10]
},
"id": "TestRequest"
}
```
**回應範例：**
```
{
"response": {
"status": "success",
"device": 1,
"operation": "WriteMultipleRegistersRequest",
"payload": {
"function_code": 23,
"address": 1,
"count": 3
}
},
"id" : "TestRequest"
}
```
遮罩寫入暫存器
**請求範例：**
```
{
"request": {
"operation": "MaskWriteRegisterRequest",
"device": 1,
"address": 1,
"and_mask": 175,
"or_mask": 1
},
"id": "TestRequest"
}
```
**回應範例：**
```
{
"response": {
"status": "success",
"device": 1,
"operation": "MaskWriteRegisterRequest",
"payload": {
"function_code": 22,
"and_mask": 0,
"or_mask": 8
}
},
"id" : "TestRequest"
}
```
讀寫多個暫存器
**請求範例：**
```
{
"request": {
"operation": "ReadWriteMultipleRegistersRequest",
"device": 1,
"read_address": 1,
"read_count": 2,
"write_address": 3,
"write_registers": [20,30,40]
},
"id": "TestRequest"
}
```
**回應範例：**
```
{
"response": {
"status": "success",
"device": 1,
"operation": "ReadWriteMultipleRegistersRequest",
"payload": {
"function_code": 23,
"registers": [10,20,10,20]
}
},
"id" : "TestRequest"
}
```
這個回應中傳回的暫存器是要讀取的暫存器。
### 回應狀態：例外
當請求格式有效但請求未順利完成時會發生例外。在此情況下，回應包含下列資訊：
+ `status` 設定為 `Exception`。
+ `function_code` 等於請求的函數碼 \$1 128。
+ `exception_code` 包含例外碼。如需詳細資訊，請參閱 Modbus 例外碼。
**範例：**
```
{
"response" : {
"status" : "fail",
"error_message": "Internal Error",
"error": "Exception",
"device": 1,
"operation": "ReadCoilsRequest",
"payload": {
"function_code": 129,
"exception_code": 2
}
},
"id" : "TestRequest"
}
```
### 回應狀態：沒有回應
此連接器會在 Modbus 請求上執行驗證檢查。例如，它檢查是否格式無效和遺漏欄位。如果驗證失敗，連接器不會傳送請求。而是傳回包含以下資訊的回應：
+ `status` 設定為 `No Response`。
+ `error` 包含錯誤的原因。
+ `error_message` 包含錯誤訊息。
**範例**：
```
{
"response" : {
"status" : "fail",
"error_message": "Invalid address field. Expected , got ",
"error": "No Response",
"device": 1,
"operation": "ReadCoilsRequest",
"payload": {
"error": "Invalid address field. Expected , got "
}
},
"id" : "TestRequest"
}
```
如果請求的目標是不存在的裝置，或 Modbus RTU 網路沒有作用，您可能會收到 `ModbusIOException` (使用「沒有回應」格式)。
```
{
"response" : {
"status" : "fail",
"error_message": "[Input/Output] No Response received from the remote unit",
"error": "No Response",
"device": 1,
"operation": "ReadCoilsRequest",
"payload": {
"error": "[Input/Output] No Response received from the remote unit"
}
},
"id" : "TestRequest"
}
```
## 使用範例
使用下列高階步驟來設定範例 Python 3.7 Lambda 函數，您可以用來嘗試連接器。
**注意**
如果您使用其他 Python 執行期，則可以建立從 Python3.x 到 Python 3.7 的符號連結。
[連接器入門 (主控台)](connectors-console.md) 和 [連接器入門 (CLI)](connectors-cli.md) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。
1. 確定您符合連接器的[要求](#modbus-protocol-adapter-connector-req)。
1. 建立並發佈 Lambda 函數，將輸入資料傳送至連接器。
將[範例程式碼](#modbus-protocol-adapter-connector-usage-example)儲存為 PY 檔案。下載並解壓縮[AWS IoT Greengrass 適用於 Python 的 核心 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. 新增連接器並設定其[參數](#modbus-protocol-adapter-connector-param)。
1. 新增訂閱，允許連接器在支援主題篩選條件上接收[輸入資料](#modbus-protocol-adapter-connector-data-input)並傳送[輸出資料](#modbus-protocol-adapter-connector-data-output)。
+ 將 Lambda 函數設定為來源，將連接器設定為目標，並使用支援的輸入主題篩選條件。
+ 將連接器設為來源、將 AWS IoT Core 設為目標，並使用支援的輸出主題篩選條件。您可以使用此訂閱在 AWS IoT 主控台中檢視狀態訊息。
1. 部署群組。
1. 在 AWS IoT 主控台**的測試**頁面上，訂閱輸出資料主題，以檢視連接器的狀態訊息。Lambda 函數範例為長期函數，並在部署群組後立即開始傳送訊息。
完成測試後，您可以將 Lambda 生命週期設定為隨需 （或在 CLI `"Pinned": false`中） 並部署群組。這會讓函數停止傳送訊息。
### 範例
下列範例 Lambda 函數會將輸入訊息傳送至連接器。
```
import greengrasssdk
import json
TOPIC_REQUEST = 'modbus/adapter/request'
# Creating a greengrass core sdk client
iot_client = greengrasssdk.client('iot-data')
def create_read_coils_request():
request = {
"request": {
"operation": "ReadCoilsRequest",
"device": 1,
"address": 1,
"count": 1
},
"id": "TestRequest"
}
return request
def publish_basic_request():
iot_client.publish(payload=json.dumps(create_read_coils_request()), topic=TOPIC_REQUEST)
publish_basic_request()
def lambda_handler(event, context):
return
```
## 授權
Modbus-RTU 通訊協定轉接器連接器包含下列第三方軟體/授權：
+ [pymodbus](https://github.com/riptideio/pymodbus/blob/master/README.rst)/BSD
+ [pyserial](https://github.com/pyserial/pyserial)/BSD
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明連接器每個版本中的變更。
| 版本 | 變更 |
| --- | --- |
| 3 | 將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 |
| 2 | 更新連接器 ARN 以取得 AWS 區域 支援。 改善錯誤記錄。 |
| 1 | 初始版本。 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
# Modbus-TCP 通訊協定轉接器連接器
Modbus-TCP 通訊協定轉接器[連接器](connectors.md)會透過 ModbusTCP 通訊協定從本機裝置收集資料，並將其發佈至選取的`StreamManager`串流。
您也可以將此連接器與 IoT SiteWise 連接器和 IoT SiteWise 閘道搭配使用。您的閘道必須提供連接器的組態。如需詳細資訊，請參閱 IoT SiteWise 使用者指南中的[設定 Modbus TCP 來源](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/configure-modbus-source.html)。
**注意**
此連接器以[無容器](lambda-group-config.md#no-container-mode)隔離模式執行，因此您可以將其部署到在 Docker 容器中執行的 AWS IoT Greengrass 群組。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 3 | `arn:aws:greengrass:region::/connectors/ModbusTCPConnector/versions/3` |
| 2 | `arn:aws:greengrass:region::/connectors/ModbusTCPConnector/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/ModbusTCPConnector/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#modbus-tcp-connector-changelog)。
## 要求
此連接器有下列要求：
------
#### [ Version 1 - 3 ]
+ AWS IoT Greengrass 核心軟體 1.10.2 版或更新版本。
+ AWS IoT Greengrass 群組上已啟用串流管理員。
+ 安裝在核心裝置上並新增至`PATH`環境變數的 Java 8。
**注意**
此連接器僅適用於下列區域：
ap-southeast-1
ap-southeast-2
eu-central-1
eu-west-1
us-east-1
us-west-2
cn-north-1
------
## 連接器參數
此連接器支援下列參數：
`LocalStoragePath`
IoT SiteWise 連接器可寫入持久性資料的 AWS IoT Greengrass 主機目錄。預設目錄為 `/var/sitewise`。
AWS IoT 主控台中的顯示名稱：**本機儲存路徑**
必要： `false`
類型：`string`
有效模式： `^\s*$|\/.`
`MaximumBufferSize`
IoT SiteWise 磁碟用量的大小上限，以 GB 為單位。預設大小為 10GB。
AWS IoT 主控台中的顯示名稱：**磁碟緩衝區大小上限**
必要： `false`
類型：`string`
有效模式： `^\s*$|[0-9]+`
`CapabilityConfiguration`
連接器從 收集資料並連線的一組 Modbus TCP 收集器組態。
AWS IoT 主控台中的顯示名稱：**CapabilityConfiguration**
必要： `false`
類型：格式正確的 JSON 字串，定義一組支援的意見回饋組態。
以下是 的範例`CapabilityConfiguration`：
```
{
"sources": [
{
"type": "ModBusTCPSource",
"name": "SourceName1",
"measurementDataStreamPrefix": "SourceName1_Prefix",
"destination": {
"type": "StreamManager",
"streamName": "SiteWise_Stream_1",
"streamBufferSize": 8
},
"endpoint": {
"ipAddress": "127.0.0.1",
"port": 8081,
"unitId": 1
},
"propertyGroups": [
{
"name": "GroupName",
"tagPathDefinitions": [
{
"type": "ModBusTCPAddress",
"tag": "TT-001",
"address": "30001",
"size": 2,
"srcDataType": "float",
"transformation": "byteWordSwap",
"dstDataType": "double"
}
],
"scanMode": {
"type": "POLL",
"rate": 100
}
}
]
}
]
}
```
### 建立範例連接器 (AWS CLI)
下列 CLI 命令`ConnectorDefinition`會使用包含 Modbus-TCP 通訊協定轉接器連接器的初始版本來建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '
{
"Connectors": [
{
"Id": "MyModbusTCPConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/ModbusTCP/versions/3",
"Parameters": {
"capability_configuration": "{\"version\":1,\"namespace\":\"iotsitewise:modbuscollector:1\",\"configuration\":\"{\"sources\":[{\"type\":\"ModBusTCPSource\",\"name\":\"SourceName1\",\"measurementDataStreamPrefix\":\"\",\"endpoint\":{\"ipAddress\":\"127.0.0.1\",\"port\":8081,\"unitId\":1},\"propertyGroups\":[{\"name\":\"PropertyGroupName\",\"tagPathDefinitions\":[{\"type\":\"ModBusTCPAddress\",\"tag\":\"TT-001\",\"address\":\"30001\",\"size\":2,\"srcDataType\":\"hexdump\",\"transformation\":\"noSwap\",\"dstDataType\":\"string\"}],\"scanMode\":{\"rate\":200,\"type\":\"POLL\"}}],\"destination\":{\"type\":\"StreamManager\",\"streamName\":\"SiteWise_Stream\",\"streamBufferSize\":10},\"minimumInterRequestDuration\":200}]}\"}"
}
}
]
}'
```
**注意**
此連接器中的 Lambda 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。
## 輸入資料
此連接器不接受 MQTT 訊息做為輸入資料。
## 輸出資料
此連接器會將資料發佈至 `StreamManager`。您必須設定目的地訊息串流。輸出訊息的結構如下：
```
{
"alias": "string",
"messages": [
{
"name": "string",
"value": boolean|double|integer|string,
"timestamp": number,
"quality": "string"
}
]
}
```
## 授權
Modbus-TCP 通訊協定轉接器連接器包含下列第三方軟體/授權：
+ [數位 Petri](https://github.com/digitalpetri/modbus) Modbus
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明連接器每個版本中的變更。
| 版本 | 改變 | 日期 |
| --- | --- | --- |
| 3 （建議） | 此版本包含錯誤修正。 | 2021 年 12 月 22 日 |
| 2 | 新增對 ASCII、UTF8 和 ISO8859 編碼來源字串的支援。 | 2021 年 5 月 24 日 |
| 1 | 初始版本。 | 2020 年 12 月 15 日 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
# Raspberry Pi GPIO 連接器
**警告**
此連接器已進入*延長的生命週期階段*， AWS IoT Greengrass 且不會發佈提供現有功能、增強功能、安全修補程式或錯誤修正的更新。如需詳細資訊，請參閱[AWS IoT Greengrass Version 1 維護政策](maintenance-policy.md)。
Raspberry Pi GPIO [連接器](connectors.md)控制 Raspberry Pi 核心裝置上的一般用途輸入/輸出 (GPIO) 接腳。
此連接器以指定的間隔輪詢輸入接腳，並將狀態變更發佈到 MQTT 主題。它也接受來自使用者定義 Lambda 函數的讀取和寫入請求做為 MQTT 訊息。寫入請求用來將接腳設為高或低電壓。
連接器提供參數讓您用來指定輸入和輸出接腳。此行為是在群組部署之前設定。無法在執行時間變更。
+ 輸入接腳可用於從周邊裝置接收資料。
+ 輸出接腳可用於控制周邊設備，或將資料傳送到周邊設備。
您可以在許多案例中使用此連接器，例如：
+ 控制紅綠燈的綠色、黃色及紅色 LED 燈。
+ 根據濕度感應器的資料來控制風扇 (連接到繼電器)。
+ 在零售店當客戶按下按鈕時通知員工。
+ 使用智慧型電燈開關來控制其他 IoT 裝置。
**注意**
此連接器不適用於有即時需求的應用程式。期間較短的活動可能會被遺漏。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 3 | `arn:aws:greengrass:region::/connectors/RaspberryPiGPIO/versions/3` |
| 2 | `arn:aws:greengrass:region::/connectors/RaspberryPiGPIO/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/RaspberryPiGPIO/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#raspberrypi-gpio-connector-changelog)。
## 要求
此連接器有下列要求：
------
#### [ Version 3 ]
+ AWS IoT Greengrass 核心軟體 1.9.3 版或更新版本。
+ 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 3.7 版。
+ Raspberry Pi 4 模型 B，或 Raspberry Pi 3 模型 B/B\$1。您必須了解 Raspberry Pi 的接腳順序。如需詳細資訊，請參閱[GPIO 接腳順序](#raspberrypi-gpio-connector-req-pins)。
+ Greengrass 群組中的[本機裝置資源](access-local-resources.md)，指向 Raspberry Pi `/dev/gpiomem`上的 。如果您在 主控台中建立資源，則必須選取**擁有資源選項之 Linux 群組的自動新增作業系統群組許可**。在 API 中，將 `GroupOwnerSetting.AutoAddGroupOwner` 屬性設定為 `true`。
+ 安裝在 Raspberry Pi 的 [RPi.GPIO](https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/) 模組。在 Raspbian 中，預設已安裝這個模組。您可以使用下列命令來重新加以安裝：
```
sudo pip install RPi.GPIO
```
------
#### [ Versions 1 - 2 ]
+ AWS IoT Greengrass 核心軟體 1.7 版或更新版本。
+ [Python](https://www.python.org/) 2.7 版安裝在核心裝置上，並新增至 PATH 環境變數。
+ Raspberry Pi 4 模型 B，或 Raspberry Pi 3 模型 B/B\$1。您必須了解 Raspberry Pi 的接腳順序。如需詳細資訊，請參閱[GPIO 接腳順序](#raspberrypi-gpio-connector-req-pins)。
+ Greengrass 群組中的[本機裝置資源](access-local-resources.md)，指向 Raspberry Pi `/dev/gpiomem`上的 。如果您在 主控台中建立資源，則必須選取**擁有資源選項之 Linux 群組的自動新增作業系統群組許可**。在 API 中，將 `GroupOwnerSetting.AutoAddGroupOwner` 屬性設定為 `true`。
+ 安裝在 Raspberry Pi 的 [RPi.GPIO](https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/) 模組。在 Raspbian 中，預設已安裝這個模組。您可以使用下列命令來重新加以安裝：
```
sudo pip install RPi.GPIO
```
------
### GPIO 接腳順序
Raspberry Pi GPIO 連接器透過晶片上基礎系統 (SoC) 的編號方案來參考 GPIO 接腳，而不是 GPIO 接腳的實體配置。接腳的實體順序可能因 Raspberry Pi 版本而異。如需詳細資訊，請參閱 Raspberry Pi 文件中的 [GPIO](https://www.raspberrypi.org/documentation/usage/gpio/)。
連接器無法驗證您設定的輸入和輸出接腳是否正確映射到 Raspberry Pi 的基礎硬體。如果接腳組態無效，連接器嘗試在裝置上啟動時會傳回執行時間錯誤。若要解決這個問題，請重新設定連接器，然後重新部署。
**注意**
請確定 GPIO 接腳的周邊設備已正確接線，以防止元件損壞。
## 連接器參數
此連接器提供下列參數：
`InputGpios`
要設定為輸入的 GPIO 接腳號碼 (逗號分隔清單)。您也可以選擇附加 `U` 來設定接腳的上拉電阻，或附加 `D` 來設定下拉電阻。範例：`"5,6U,7D"`。
在 AWS IoT 主控台中顯示名稱：**輸入 GPIO 接腳**
必要：`false`。您必須指定輸入接腳、輸出接腳或兩者。
類型：`string`
有效模式： `^$|^[0-9]+[UD]?(,[0-9]+[UD]?)*$`
`InputPollPeriod`
每個輪詢操作的間隔 (毫秒)，依此檢查輸入 GPIO 接腳的狀態是否變更。最小值為 1。
這個值取決於您的案例和輪詢的裝置類型。例如，值 `50` 的速度應該足夠偵測到按鈕按下。
在 AWS IoT 主控台中顯示名稱：**輸入 GPIO 輪詢期間**
必要： `false`
類型：`string`
有效模式： `^$|^[1-9][0-9]*$`
`OutputGpios`
要設定為輸出的 GPIO 接腳號碼 (逗號分隔清單)。您也可以選擇附加 `H` 來設定高狀態 (1)，或附加 `L` 來設定低狀態 (0)。範例：`"8H,9,27L"`。
在 AWS IoT 主控台中顯示名稱：**輸出 GPIO 接腳**
必要：`false`。您必須指定輸入接腳、輸出接腳或兩者。
類型：`string`
有效模式： `^$|^[0-9]+[HL]?(,[0-9]+[HL]?)*$`
`GpioMem-ResourceId`
代表 `/dev/gpiomem` 的本機裝置資源的 ID。
此連接器已授予資源的讀寫存取權。
AWS IoT 主控台中的顯示名稱：**/dev/gpiomem 裝置的資源**
必要： `true`
類型：`string`
有效模式： `.+`
### 建立範例連接器 (AWS CLI)
下列 CLI 命令會使用包含 Raspberry Pi GPIO 連接器的`ConnectorDefinition`初始版本建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MyRaspberryPiGPIOConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/RaspberryPiGPIO/versions/3",
"Parameters": {
"GpioMem-ResourceId": "my-gpio-resource",
"InputGpios": "5,6U,7D",
"InputPollPeriod": 50,
"OutputGpios": "8H,9,27L"
}
}
]
}'
```
**注意**
此連接器中的 Lambda 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。
在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。
## 輸入資料
此連接器接受兩個 MQTT 主題上對 GPIO 接腳的讀取或寫入請求。
+ `gpio/+/+/read` 主題上的讀取請求。
+ `gpio/+/+/write` 主題上的寫入請求。
若要發佈到這些主題，請將 `+` 萬用字元分別換成核心物件名稱和目標接腳號碼。例如：
```
gpio/core-thing-name/gpio-number/read
```
**注意**
目前，當您建立使用 Raspberry Pi GPIO 連接器的訂閱時，您必須在主題中指定至少一個 \$1 萬用字元的值。
**主題篩選條件：** `gpio/+/+/read`
使用此主題來引導連接器讀取主題中指定之 GPIO 接腳的狀態。
連接器將回應發佈到對應的輸出主題 (例如，`gpio/core-thing-name/gpio-number/state`)。
**訊息屬性**
無。忽略傳送到這個主題的訊息。
**主題篩選條件：** `gpio/+/+/write`
使用此主題將寫入請求傳送到 GPIO 接腳。這引導連接器將主題中指定的 GPIO 接腳設定為低或高電壓。
+ `0` 將接腳設定為低電壓。
+ `1` 將接腳設定為高電壓。
連接器將回應發佈到對應的輸出 `/state` 主題 (例如，`gpio/core-thing-name/gpio-number/state`)。
**訊息屬性**
值 `0` 或 `1`，做為整數或字串。
**範例輸入**
```
0
```
## 輸出資料
此連接器將資料發佈到兩個主題：
+ `gpio/+/+/state` 主題上高或低狀態變更。
+ `gpio/+/error`主題的相關錯誤。
**主題篩選條件：** `gpio/+/+/state`
使用此主題監聽輸入接腳的狀態變更和讀取請求的回應。如果接腳處於低狀態，連接器會傳回字串 `"0"`，或者，如果是高狀態，則傳回 `"1"`。
發佈到此主題時，連接器會將 `+` 萬用字元分別換成核心物件名稱和目標接腳。例如：
```
gpio/core-thing-name/gpio-number/state
```
目前，當您建立使用 Raspberry Pi GPIO 連接器的訂閱時，您必須在主題中指定至少一個 \$1 萬用字元的值。
**範例輸出**
```
0
```
**主題篩選條件：** `gpio/+/error`
使用此主題監聽錯誤。連接器會因為請求無效而發佈到本主題 (例如，在輸入接腳上請求狀態變更時)。
發佈到此主題時，連接器會將 `+` 萬用字元換成核心物件名稱。
**範例輸出**
```
{
"topic": "gpio/my-core-thing/22/write",
"error": "Invalid GPIO operation",
"long_description": "GPIO 22 is configured as an INPUT GPIO. Write operations are not permitted."
}
```
## 使用範例
使用下列高階步驟來設定範例 Python 3.7 Lambda 函數，您可以用來嘗試連接器。
**注意**
如果您使用其他 Python 執行期，則可以建立從 Python3.x 到 Python 3.7 的符號連結。
[連接器入門 (主控台)](connectors-console.md) 和 [連接器入門 (CLI)](connectors-cli.md) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。
1. 確定您符合連接器的[要求](#raspberrypi-gpio-connector-req)。
1. 建立並發佈 Lambda 函數，將輸入資料傳送至連接器。
將[範例程式碼](#raspberrypi-gpio-connector-usage-example)儲存為 PY 檔案。下載並解壓縮[AWS IoT Greengrass 適用於 Python 的 核心 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. 新增連接器並設定其[參數](#raspberrypi-gpio-connector-param)。
1. 新增訂閱，允許連接器在支援主題篩選條件上接收[輸入資料](#raspberrypi-gpio-connector-data-input)並傳送[輸出資料](#raspberrypi-gpio-connector-data-output)。
+ 將 Lambda 函數設定為來源，將連接器設定為目標，並使用支援的輸入主題篩選條件。
+ 將連接器設為來源、將 AWS IoT Core 設為目標，並使用支援的輸出主題篩選條件。您可以使用此訂閱在 AWS IoT 主控台中檢視狀態訊息。
1. 部署群組。
1. 在 AWS IoT 主控台**的測試**頁面上，訂閱輸出資料主題，以檢視連接器的狀態訊息。Lambda 函數範例為長期函數，並在部署群組後立即開始傳送訊息。
完成測試後，您可以將 Lambda 生命週期設定為隨需 （或在 CLI `"Pinned": false`中） 並部署群組。這會讓函數停止傳送訊息。
### 範例
下列範例 Lambda 函數會將輸入訊息傳送至連接器。此範例會傳送一組輸入 GPIO 接腳的讀取請求。它會說明如何使用核心物件名稱和 PIN 碼來建構主題。
```
import greengrasssdk
import json
import os
iot_client = greengrasssdk.client('iot-data')
INPUT_GPIOS = [6, 17, 22]
thingName = os.environ['AWS_IOT_THING_NAME']
def get_read_topic(gpio_num):
return '/'.join(['gpio', thingName, str(gpio_num), 'read'])
def get_write_topic(gpio_num):
return '/'.join(['gpio', thingName, str(gpio_num), 'write'])
def send_message_to_connector(topic, message=''):
iot_client.publish(topic=topic, payload=str(message))
def set_gpio_state(gpio, state):
send_message_to_connector(get_write_topic(gpio), str(state))
def read_gpio_state(gpio):
send_message_to_connector(get_read_topic(gpio))
def publish_basic_message():
for i in INPUT_GPIOS:
read_gpio_state(i)
publish_basic_message()
def lambda_handler(event, context):
return
```
## 授權
Raspberry Pi GPIO； 連接器包含下列第三方軟體/授權：
+ [RPi.GPIO](https://pypi.org/project/RPi.GPIO/)/MIT
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明每個連接器版本中的變更。
| 版本 | 變更 |
| --- | --- |
| 3 | 將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 |
| 2 | 更新連接器 ARN 以取得 AWS 區域 支援。 |
| 1 | 初始版本。 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
+ Raspberry Pi 文件中的 [GPIO](https://www.raspberrypi.org/documentation/usage/gpio/)
# 序列串流連接器
**警告**
此連接器已進入*延長的生命週期階段*， AWS IoT Greengrass 且不會發佈提供現有功能、增強功能、安全修補程式或錯誤修正的更新。如需詳細資訊，請參閱[AWS IoT Greengrass Version 1 維護政策](maintenance-policy.md)。
序列串流[連接器](connectors.md)會讀取和寫入 AWS IoT Greengrass 核心裝置上的序列連接埠。
此連接器支援兩種操作模式：
+ **隨需讀取**。接收 MQTT 主題上的讀取和寫入請求，並發佈讀取操作的回應，或寫入操作的狀態。
+ **輪詢讀取**。定期從序列埠讀取。這個模式還支援隨需讀取請求。
**注意**
讀取請求的最大讀取長度限制為 63994 位元組。寫入請求的最大資料長度限制為 128000 位元組。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 3 | `arn:aws:greengrass:region::/connectors/SerialStream/versions/3` |
| 2 | `arn:aws:greengrass:region::/connectors/SerialStream/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/SerialStream/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#serial-stream-connector-changelog)。
## 要求
此連接器有下列要求：
------
#### [ Version 3 ]
+ AWS IoT Greengrass 核心軟體 1.9.3 版或更新版本。
+ 安裝在核心裝置上並新增至 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 需求。
+ Greengrass 群組中的[本機裝置資源](access-local-resources.md)，指向目標序列埠。
**注意**
在您部署此連接器之前，建議您設定序列埠並驗證是否可對該序列埠進行讀取和寫入。
------
#### [ Versions 1 - 2 ]
+ AWS IoT Greengrass 核心軟體 1.7 版或更新版本。
+ [Python](https://www.python.org/) 2.7 版安裝在核心裝置上，並新增至 PATH 環境變數。
+ Greengrass 群組中的[本機裝置資源](access-local-resources.md)，指向目標序列埠。
**注意**
在您部署此連接器之前，建議您設定序列埠並驗證是否可對該序列埠進行讀取和寫入。
------
## 連接器參數
此連接器提供下列參數：
`BaudRate`
序列連線的傳輸速率。
AWS IoT 主控台中的顯示名稱：**傳輸速率**
必要： `true`
類型：`string`
有效值：`110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 56000, 57600, 115200, 230400`
有效模式： `^110$|^300$|^600$|^1200$|^2400$|^4800$|^9600$|^14400$|^19200$|^28800$|^38400$|^56000$|^57600$|^115200$|^230400$`
`Timeout`
讀取操作的逾時 (以秒為單位)。
AWS IoT 主控台中的顯示名稱：**逾時**
必要： `true`
類型：`string`
有效值：`1 - 59`
有效模式： `^([1-9]|[1-5][0-9])$`
`SerialPort`
裝置上實體序列埠的絕對路徑。這是指定給本機裝置資源的來源路徑。
AWS IoT 主控台中的顯示名稱：**序列連接埠**
必要： `true`
類型：`string`
有效模式： `[/a-zA-Z0-9_-]+`
`SerialPort-ResourceId`
代表實體序列埠的本機裝置資源 ID。
此連接器已授予資源的讀寫存取權。
AWS IoT 主控台中的顯示名稱：**序列連接埠資源**
必要： `true`
類型：`string`
有效模式： `[a-zA-Z0-9_-]+`
`PollingRead`
設定讀取模式：輪詢讀取或隨需讀取。
+ 對於輪詢讀取模式，指定 `true`。在此模式中，需要 `PollingInterval`、`PollingReadType` 和 `PollingReadLength` 屬性。
+ 對於隨需讀取模式，指定 `false`。在這個模式下，類型和長度值是在讀取請求中指定。
AWS IoT 主控台中的顯示名稱：**讀取模式**
必要： `true`
類型：`string`
有效值：`true, false`
有效模式： `^([Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$`
`PollingReadLength`
在每個輪詢讀取操作中讀取的資料長度 (以位元組為單位)。這只適用於使用輪詢讀取模式時。
在 AWS IoT 主控台中顯示名稱：**輪詢讀取長度**
必要：`false`。當 `PollingRead` 為 `true` 時，此為必要屬性。
類型：`string`
有效模式： `^(|[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-2][0-9]{3}|63[0-8][0-9]{2}|639[0-8][0-9]|6399[0-4])$`
`PollingReadInterval`
輪詢讀取的間隔 (以秒為單位)。這只適用於使用輪詢讀取模式時。
在 AWS IoT 主控台中顯示名稱：**輪詢讀取間隔**
必要：`false`。當 `PollingRead` 為 `true` 時，此為必要屬性。
類型：`string`
有效值：1 - 999
有效模式： `^(|[1-9]|[1-9][0-9]|[1-9][0-9][0-9])$`
`PollingReadType`
輪詢執行緒讀取的資料類型。這只適用於使用輪詢讀取模式時。
在 AWS IoT 主控台中顯示名稱：**輪詢讀取類型**
必要：`false`。當 `PollingRead` 為 `true` 時，此為必要屬性。
類型：`string`
有效值：`ascii, hex`
有效模式： `^(|[Aa][Ss][Cc][Ii][Ii]|[Hh][Ee][Xx])$`
`RtsCts`
指出是否啟用 RTS/CTS 流程控制。預設值為 `false`。如需詳細資訊，請參閱 [RTS、CTS 及 RTR](https://en.wikipedia.org/wiki/RS-232#RTS,_CTS,_and_RTR)。
AWS IoT 主控台中的顯示名稱：**RTS/CTS 流程控制**
必要： `false`
類型：`string`
有效值：`true, false`
有效模式： `^(|[Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$`
`XonXoff`
指出是否啟用軟體流程控制。預設值為 `false`。如需詳細資訊，請參閱[軟體流程控制](https://en.wikipedia.org/wiki/Software_flow_control)。
AWS IoT 主控台中的顯示名稱：**軟體流程控制**
必要： `false`
類型：`string`
有效值：`true, false`
有效模式： `^(|[Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$`
`Parity`
序列埠的同位。預設值為 `N`。如需詳細資訊，請參閱[同位](https://en.wikipedia.org/wiki/Serial_port#Parity)。
AWS IoT 主控台中的顯示名稱：**序列連接埠同位**
必要： `false`
類型：`string`
有效值：`N, E, O, S, M`
有效模式： `^(|[NEOSMneosm])$`
### 建立範例連接器 (AWS CLI)
下列 CLI 命令`ConnectorDefinition`會使用包含序列串流連接器的初始版本來建立 。它將連接器設定為輪詢讀取模式。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MySerialStreamConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/SerialStream/versions/3",
"Parameters": {
"BaudRate" : "9600",
"Timeout" : "25",
"SerialPort" : "/dev/serial1",
"SerialPort-ResourceId" : "my-serial-port-resource",
"PollingRead" : "true",
"PollingReadLength" : "30",
"PollingReadInterval" : "30",
"PollingReadType" : "hex"
}
}
]
}'
```
在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。
## 輸入資料
此連接器接受兩個 MQTT 主題上序列連接埠的讀取或寫入請求。輸入訊息必須是 JSON 格式。
+ `serial/+/read/#` 主題上的讀取請求。
+ `serial/+/write/#` 主題上的寫入請求。
若要發佈到這些主題，請將 `+` 萬用字元換成核心物件名稱，將 `#` 萬用字元換成序列埠的路徑。例如：
```
serial/core-thing-name/read/dev/serial-port
```
**主題篩選條件：** `serial/+/read/#`
使用此主題將隨需讀取請求傳送到序列接腳。讀取請求的最大讀取長度限制為 63994 位元組。
**訊息屬性**
`readLength`
從序列埠讀取的資料長度。
必要： `true`
類型：`string`
有效模式： `^[1-9][0-9]*$`
`type`
要讀取的資料類型。
必要： `true`
類型：`string`
有效值：`ascii, hex`
有效模式： `(?i)^(ascii|hex)$`
`id`
請求的任意 ID。此屬性用於將輸入請求映射到輸出回應。
必要： `false`
類型：`string`
有效模式： `.+`
**範例輸入**
```
{
"readLength": "30",
"type": "ascii",
"id": "abc123"
}
```
**主題篩選條件：** `serial/+/write/#`
使用此主題將寫入請求傳送到序列接腳。寫入請求的最大資料長度限制為 128000 位元組。
**訊息屬性**
`data`
要寫入序列埠的字串。
必要： `true`
類型：`string`
有效模式： `^[1-9][0-9]*$`
`type`
要讀取的資料類型。
必要： `true`
類型：`string`
有效值：`ascii, hex`
有效模式： `^(ascii|hex|ASCII|HEX)$`
`id`
請求的任意 ID。此屬性用於將輸入請求映射到輸出回應。
必要： `false`
類型：`string`
有效模式： `.+`
**範例輸入：ASCII 請求**
```
{
"data": "random serial data",
"type": "ascii",
"id": "abc123"
}
```
**範例輸入：十六進位請求**
```
{
"data": "base64 encoded data",
"type": "hex",
"id": "abc123"
}
```
## 輸出資料
連接器將輸出資料發佈在兩個主題：
+ 在 `serial/+/status/#` 主題上來自連接器的狀態資訊。
+ 在 `serial/+/read_response/#` 主題上來自讀取請求的回應。
發佈到此主題時，連接器會將 `+` 萬用字元換成核心物件名稱，將 `#` 萬用字元換成序列埠的路徑。例如：
```
serial/core-thing-name/status/dev/serial-port
```
**主題篩選條件：** `serial/+/status/#`
使用此主題監聽讀取和寫入請求的狀態。如果 `id` 屬性包含在請求中，則會在回應中傳回。
**範例輸出：成功**
```
{
"response": {
"status": "success"
},
"id": "abc123"
}
```
**範例輸出：失敗**
失敗回應包含 `error_message` 屬性，描述執行讀取或寫入操作時發生的錯誤或逾時。
```
{
"response": {
"status": "fail",
"error_message": "Could not write to port"
},
"id": "abc123"
}
```
**主題篩選條件：** `serial/+/read_response/#`
使用此主題，以接收來自讀取操作的回應資料。如果類型為 `hex`，則回應資料為 Base64 編碼。
**範例輸出**
```
{
"data": "output of serial read operation"
"id": "abc123"
}
```
## 使用範例
使用下列高階步驟來設定範例 Python 3.7 Lambda 函數，您可以用來嘗試連接器。
**注意**
如果您使用其他 Python 執行期，則可以建立從 Python3.x 到 Python 3.7 的符號連結。
[連接器入門 (主控台)](connectors-console.md) 和 [連接器入門 (CLI)](connectors-cli.md) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。
1. 確定您符合連接器的[要求](#serial-stream-connector-req)。
1. 建立並發佈 Lambda 函數，將輸入資料傳送至連接器。
將[範例程式碼](#serial-stream-connector-usage-example)儲存為 PY 檔案。下載並解壓縮[AWS IoT Greengrass 適用於 Python 的 核心 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. 將連接器新增至群組並設定其[參數](#serial-stream-connector-param)。
1. 將訂閱新增至群組，允許連接器在支援主題篩選條件上接收[輸入資料](#serial-stream-connector-data-input)並傳送[輸出資料](#serial-stream-connector-data-output)。
+ 將 Lambda 函數設定為來源，將連接器設定為目標，並使用支援的輸入主題篩選條件。
+ 將連接器設為來源、將 AWS IoT Core 設為目標，並使用支援的輸出主題篩選條件。您可以使用此訂閱在 AWS IoT 主控台中檢視狀態訊息。
1. 部署群組。
1. 在 AWS IoT 主控台**的測試**頁面上，訂閱輸出資料主題，以檢視連接器的狀態訊息。Lambda 函數範例為長期函數，並在部署群組後立即開始傳送訊息。
完成測試後，您可以將 Lambda 生命週期設定為隨需 （或在 CLI `"Pinned": false`中） 並部署群組。這會讓函數停止傳送訊息。
### 範例
下列範例 Lambda 函數會將輸入訊息傳送至連接器。
```
import greengrasssdk
import json
TOPIC_REQUEST = 'serial/CORE_THING_NAME/write/dev/serial1'
# Creating a greengrass core sdk client
iot_client = greengrasssdk.client('iot-data')
def create_serial_stream_request():
request = {
"data": "TEST",
"type": "ascii",
"id": "abc123"
}
return request
def publish_basic_request():
iot_client.publish(payload=json.dumps(create_serial_stream_request()), topic=TOPIC_REQUEST)
publish_basic_request()
def lambda_handler(event, context):
return
```
## 授權
序列串流連接器包含下列第三方軟體/授權：
+ [pyserial](https://github.com/pyserial/pyserial)/BSD
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明每個連接器版本中的變更。
| 版本 | 變更 |
| --- | --- |
| 3 | 將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 |
| 2 | 更新連接器 ARN 以取得 AWS 區域 支援。 |
| 1 | 初始版本。 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
# ServiceNow MetricBase 整合連接器
**警告**
此連接器已進入*延長生命週期階段*， AWS IoT Greengrass 且不會發佈提供現有功能、增強功能、安全修補程式或錯誤修正的更新。如需詳細資訊，請參閱[AWS IoT Greengrass Version 1 維護政策](maintenance-policy.md)。
ServiceNow MetricBase 整合[連接器](connectors.md)會將時間序列指標從 Greengrass 裝置發佈至 ServiceNow MetricBase。這可讓您存放、分析和視覺化來自 Greengrass 核心環境的時間序列資料，並對本機事件採取行動。
此連接器會接收 MQTT 主題上的時間序列資料，並定期將資料發佈到 ServiceNow API。
您可以使用此連接器來支援如下案例：
+ 根據從 Greengrass 裝置收集的時間序列資料，建立以閾值為基礎的提醒和警示。
+ 使用來自 Greengrass 裝置的時間服務資料，搭配在 ServiceNow 平台上建構的自訂應用程式。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 4 | `arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/4` |
| 3 | `arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/3` |
| 2 | `arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#servicenow-connector-changelog)。
## 要求
此連接器有下列要求：
------
#### [ Version 3 - 4 ]
+ 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 需求。
+ 具有 MetricBase 有效訂閱的 ServiceNow 帳戶。此外，帳戶中必須建立指標和指標資料表。如需詳細資訊，請參閱 ServiceNow 文件中的 [MetricBase](https://docs.servicenow.com/bundle/london-servicenow-platform/page/administer/metricbase/concept/metricbase.html)。
+ 在 中 AWS Secrets Manager 存放使用者名稱和密碼的文字類型秘密，以使用基本身分驗證登入您的 ServiceNow 執行個體。此私密必須包含「使用者」和「密碼」金鑰與對應的值。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[建立基本秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)。
+ Greengrass 群組中參考 Secrets Manager 秘密的秘密資源。如需詳細資訊，請參閱[將秘密部署到 AWS IoT Greengrass 核心](secrets.md)。
------
#### [ Versions 1 - 2 ]
+ AWS IoT Greengrass 核心軟體 v1.7 或更新版本。 AWS IoT Greengrass 必須設定為支援本機秘密，如[秘密要求](secrets.md#secrets-reqs)中所述。
**注意**
此要求包括允許存取您的 Secrets Manager 秘密。如果您使用預設 Greengrass 服務角色，Greengrass 具有許可，可取得名稱開頭為 *greengrass-* 的秘密值。
+ [Python](https://www.python.org/) 2.7 版安裝在核心裝置上，並新增至 PATH 環境變數。
+ 具有 MetricBase 有效訂閱的 ServiceNow 帳戶。此外，帳戶中必須建立指標和指標資料表。如需詳細資訊，請參閱 ServiceNow 文件中的 [MetricBase](https://docs.servicenow.com/bundle/london-servicenow-platform/page/administer/metricbase/concept/metricbase.html)。
+ 在 中 AWS Secrets Manager 存放使用者名稱和密碼的文字類型秘密，以使用基本身分驗證登入您的 ServiceNow 執行個體。此私密必須包含「使用者」和「密碼」金鑰與對應的值。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[建立基本秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)。
+ Greengrass 群組中參考 Secrets Manager 秘密的秘密資源。如需詳細資訊，請參閱[將秘密部署到 AWS IoT Greengrass 核心](secrets.md)。
------
## 連接器參數
此連接器提供下列參數：
------
#### [ Version 4 ]
`PublishInterval`
將事件發佈到 ServiceNow 之間等待的秒數上限。最大值為 900。
連接器`PublishBatchSize`會在達到或`PublishInterval`過期時發佈至 ServiceNow。
在 AWS IoT 主控台中顯示名稱：以**秒為單位發佈間隔**
必要： `true`
類型：`string`
有效值：`1 - 900`
有效模式： `[1-9]|[1-9]\d|[1-9]\d\d|900`
`PublishBatchSize`
發佈到 ServiceNow 之前可批次處理的指標值數量上限。
連接器`PublishBatchSize`會在達到或`PublishInterval`過期時發佈至 ServiceNow。
在 AWS IoT 主控台中顯示名稱：**發佈批次大小**
必要： `true`
類型：`string`
有效模式： `^[0-9]+$`
`InstanceName`
用於連接到 ServiceNow 的執行個體名稱。
在 AWS IoT 主控台中顯示名稱：**ServiceNow 執行個體的名稱**
必要： `true`
類型：`string`
有效模式： `.+`
`DefaultTableName`
資料表的名稱，其中包含與時間序列 MetricBase 資料庫相關聯的 `GlideRecord`。輸入訊息承載中的 `table` 屬性可用來覆寫這個值。
在 AWS IoT 主控台中顯示名稱：**要包含指標的資料表名稱**
必要： `true`
類型：`string`
有效模式： `.+`
`MaxMetricsToRetain`
由新指標取代之前在記憶體中儲存的指標數目上限。
在沒有網際網路連線且連接器開始緩衝指標來稍後發佈時，就受此限制。當緩衝區已滿時，新指標會取代最舊指標。
如果連接器的主機程序中斷，則不會儲存指標。例如，在群組部署或裝置重新啟動期間就可能發生這種情況。
這個值應該大於批次大小，且根據 MQTT 訊息的傳入速率，大小足夠保留訊息。
在 AWS IoT 主控台中顯示名稱：**記憶體中保留的指標上限**
必要： `true`
類型：`string`
有效模式： `^[0-9]+$`
`AuthSecretArn`
中 AWS Secrets Manager 存放 ServiceNow 使用者名稱和密碼的秘密。這必須是文字類型私密。此私密必須包含「使用者」和「密碼」金鑰與對應的值。
在 AWS IoT 主控台中顯示名稱：**身分驗證秘密的 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]+`
`AuthSecretArn-ResourceId`
群組中參考 ServiceNow 登入資料的 Secrets Manager 秘密的秘密資源。
AWS IoT 主控台中的顯示名稱：**Auth 字符資源**
必要： `true`
類型：`string`
有效模式： `.+`
`IsolationMode`
此連接器的[容器化](connectors.md#connector-containerization)模式。預設值為 `GreengrassContainer`，這表示連接器在 AWS IoT Greengrass 容器內的隔離執行時間環境中執行。
群組的預設容器化設定不會套用至連接器。
在 AWS IoT 主控台中顯示名稱：**容器隔離模式**
必要： `false`
類型：`string`
有效值：`GreengrassContainer` 或 `NoContainer`
有效模式： `^NoContainer$|^GreengrassContainer$`
------
#### [ Version 1 - 3 ]
`PublishInterval`
將事件發佈到 ServiceNow 之間等待的秒數上限。最大值為 900。
連接器`PublishBatchSize`會在達到或`PublishInterval`過期時發佈至 ServiceNow。
在 AWS IoT 主控台中顯示名稱：以**秒為單位發佈間隔**
必要： `true`
類型：`string`
有效值：`1 - 900`
有效模式： `[1-9]|[1-9]\d|[1-9]\d\d|900`
`PublishBatchSize`
發佈到 ServiceNow 之前可批次處理的指標值數量上限。
連接器`PublishBatchSize`會在達到或`PublishInterval`過期時發佈至 ServiceNow。
在 AWS IoT 主控台中顯示名稱：**發佈批次大小**
必要： `true`
類型：`string`
有效模式： `^[0-9]+$`
`InstanceName`
用於連接到 ServiceNow 的執行個體名稱。
在 AWS IoT 主控台中顯示名稱：**ServiceNow 執行個體的名稱**
必要： `true`
類型：`string`
有效模式： `.+`
`DefaultTableName`
資料表的名稱，其中包含與時間序列 MetricBase 資料庫相關聯的 `GlideRecord`。輸入訊息承載中的 `table` 屬性可用來覆寫這個值。
在 AWS IoT 主控台中顯示名稱：**要包含指標的資料表名稱**
必要： `true`
類型：`string`
有效模式： `.+`
`MaxMetricsToRetain`
由新指標取代之前在記憶體中儲存的指標數目上限。
在沒有網際網路連線且連接器開始緩衝指標來稍後發佈時，就受此限制。當緩衝區已滿時，新指標會取代最舊指標。
如果連接器的主機程序中斷，則不會儲存指標。例如，在群組部署或裝置重新啟動期間就可能發生這種情況。
這個值應該大於批次大小，且根據 MQTT 訊息的傳入速率，大小足夠保留訊息。
在 AWS IoT 主控台中顯示名稱：**記憶體中保留的指標上限**
必要： `true`
類型：`string`
有效模式： `^[0-9]+$`
`AuthSecretArn`
中 AWS Secrets Manager 存放 ServiceNow 使用者名稱和密碼的秘密。這必須是文字類型私密。此私密必須包含「使用者」和「密碼」金鑰與對應的值。
在 AWS IoT 主控台中顯示名稱：**身分驗證秘密的 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]+`
`AuthSecretArn-ResourceId`
群組中參考 ServiceNow 登入資料的 Secrets Manager 秘密的秘密資源。
在 AWS IoT 主控台中顯示名稱：**Auth 字符資源**
必要： `true`
類型：`string`
有效模式： `.+`
------
### 建立範例連接器 (AWS CLI)
下列 CLI 命令`ConnectorDefinition`會使用包含 ServiceNow MetricBase 整合連接器的初始版本來建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MyServiceNowMetricBaseIntegrationConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/4",
"Parameters": {
"PublishInterval" : "10",
"PublishBatchSize" : "50",
"InstanceName" : "myinstance",
"DefaultTableName" : "u_greengrass_app",
"MaxMetricsToRetain" : "20000",
"AuthSecretArn" : "arn:aws:secretsmanager:region:account-id:secret:greengrass-secret-hash",
"AuthSecretArn-ResourceId" : "MySecretResource",
"IsolationMode" : "GreengrassContainer"
}
}
]
}'
```
**注意**
此連接器中的 Lambda 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。
在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。
## 輸入資料
此連接器接受 MQTT 主題上的時間序列指標，並將指標發佈至 ServiceNow。輸入訊息必須是 JSON 格式。
**訂閱中的主題篩選條件**
`servicenow/metricbase/metric`
**訊息屬性**
`request`
資料表、記錄和指標的相關資訊。這個請求代表時間序列 POST 請求中的 `seriesRef` 物件。如需詳細資訊，請參閱 [Clotho 時間序列 API - POST](https://docs.servicenow.com/bundle/london-application-development/page/integrate/inbound-rest/concept/Clotho-Time-Series-API.html#clotho-POST-put)。
必要： `true`
類型：`object`包含下列屬性：
`subject`
資料表中特定記錄的 `sys_id`。
必要： `true`
類型：`string`
`metric_name`
指標欄位名稱。
必要： `true`
類型：`string`
`table`
用於存放記錄的資料表名稱。指定此值以覆寫 `DefaultTableName` 參數。
必要： `false`
類型：`string`
`value`
個別資料點的值。
必要： `true`
類型：`float`
`timestamp`
個別資料點的時間戳記。預設值是目前時間。
必要： `false`
類型：`string`
**範例輸入**
```
{
"request": {
"subject":"ef43c6d40a0a0b5700c77f9bf387afe3",
"metric_name":"u_count",
"table": "u_greengrass_app"
"value": 1.0,
"timestamp": "2018-10-14T10:30:00"
}
}
```
## 輸出資料
這個連接器會將狀態資訊發佈為輸出資料，且主題為 MQTT。
**訂閱中的主題篩選條件**
`servicenow/metricbase/metric/status`
**範例輸出：成功**
```
{
"response": {
"metric_name": "Errors",
"table_name": "GliderProd",
"processed_on": "2018-10-14T10:35:00",
"response_id": "khjKSkj132qwr23fcba",
"status": "success",
"values": [
{
"timestamp": "2016-10-14T10:30:00",
"value": 1.0
},
{
"timestamp": "2016-10-14T10:31:00",
"value": 1.1
}
]
}
}
```
**範例輸出：失敗**
```
{
"response": {
"error": "InvalidInputException",
"error_message": "metric value is invalid",
"status": "fail"
}
}
```
如果連接器偵測到可重試的錯誤 （例如連線錯誤），則會在下一個批次中重試發佈。
## 使用範例
使用下列高階步驟來設定範例 Python 3.7 Lambda 函數，您可以用來嘗試連接器。
**注意**
如果您使用其他 Python 執行期，則可以建立從 Python3.x 到 Python 3.7 的符號連結。
[連接器入門 (主控台)](connectors-console.md) 和 [連接器入門 (CLI)](connectors-cli.md) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。
1. 確定您符合連接器的[要求](#servicenow-connector-req)。
1. 建立並發佈 Lambda 函數，將輸入資料傳送至連接器。
將[範例程式碼](#servicenow-connector-usage-example)儲存為 PY 檔案。下載並解壓縮[AWS IoT Greengrass 適用於 Python 的 核心 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. 新增連接器並設定其[參數](#servicenow-connector-param)。
1. 新增訂閱，允許連接器在支援主題篩選條件上接收[輸入資料](#servicenow-connector-data-input)並傳送[輸出資料](#servicenow-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')
SEND_TOPIC = 'servicenow/metricbase/metric'
def create_request_with_all_fields():
return {
"request": {
"subject": '2efdf6badbd523803acfae441b961961',
"metric_name": 'u_count',
"value": 1234,
"timestamp": '2018-10-20T20:22:20',
"table": 'u_greengrass_metricbase_test'
}
}
def publish_basic_message():
messageToPublish = create_request_with_all_fields()
print("Message To Publish: ", messageToPublish)
iot_client.publish(topic=SEND_TOPIC,
payload=json.dumps(messageToPublish))
publish_basic_message()
def lambda_handler(event, context):
return
```
## 授權
ServiceNow MetricBase 整合連接器包含下列第三方軟體/授權：
+ [pysnow](https://github.com/rbw/pysnow)/MIT
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明每個版本的連接器的變更。
| 版本 | 變更 |
| --- | --- |
| 4 | 已新增 `IsolationMode` 參數，以設定連接器的容器化模式。 |
| 3 | 將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 |
| 2 | 可減少過多記錄的修正。 |
| 1 | 初始版本。 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
# SNS 連接器
SNS [連接器](connectors.md)會將訊息發佈至 Amazon SNS 主題。這可讓 Web 伺服器、電子郵件地址和其他訊息訂閱者回應 Greengrass 群組中的事件。
此連接器接收 MQTT 主題上的 SNS 訊息資訊，然後將訊息傳送到指定的 SNS 主題。您可以選擇使用自訂 Lambda 函數，在訊息發佈至此連接器之前，對訊息實作篩選或格式化邏輯。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 4 | `arn:aws:greengrass:region::/connectors/SNS/versions/4` |
| 3 | `arn:aws:greengrass:region::/connectors/SNS/versions/3` |
| 2 | `arn:aws:greengrass:region::/connectors/SNS/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/SNS/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#sns-connector-changelog)。
## 要求
此連接器有下列要求：
------
#### [ Version 3 - 4 ]
+ AWS IoT Greengrass 核心軟體 v1.9.3 或更新版本。
+ 安裝在核心裝置上並新增至 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 需求。
+ 設定的 SNS 主題。如需詳細資訊，請參閱《Amazon Simple Notification Service 開發人員指南》**中的[建立 Amazon SNS 主題](https://docs.aws.amazon.com/sns/latest/dg/sns-tutorial-create-topic.html)。
+ 設定為允許對目標 Amazon SNStopic `sns:Publish`執行動作的 [Greengrass 群組角色](group-role.md)，如下列範例 IAM 政策所示。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1528133056761",
"Action": [
"sns:Publish"
],
"Effect": "Allow",
"Resource": [
"arn:aws:sns:us-east-1:123456789012:topic-name"
]
}
]
}
```
------
此連接器可讓您動態覆寫輸入訊息承載中的預設主題。如果您的實作使用此功能，IAM 政策必須允許所有目標主題的`sns:Publish`許可。您可以為資源授予細微或條件式存取 (例如，使用萬用字元 \$1 命名配置)。
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
------
#### [ Versions 1 - 2 ]
+ AWS IoT Greengrass 核心軟體 v1.7 或更新版本。
+ 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 2.7 版。
+ 設定的 SNS 主題。如需詳細資訊，請參閱《Amazon Simple Notification Service 開發人員指南》**中的[建立 Amazon SNS 主題](https://docs.aws.amazon.com/sns/latest/dg/sns-tutorial-create-topic.html)。
+ 設定為允許對目標 Amazon SNStopic `sns:Publish`執行動作的 [Greengrass 群組角色](group-role.md)，如下列範例 IAM 政策所示。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1528133056761",
"Action": [
"sns:Publish"
],
"Effect": "Allow",
"Resource": [
"arn:aws:sns:us-east-1:123456789012:topic-name"
]
}
]
}
```
------
此連接器可讓您動態覆寫輸入訊息承載中的預設主題。如果您的實作使用此功能，IAM 政策必須允許所有目標主題的`sns:Publish`許可。您可以為資源授予細微或條件式存取 (例如，使用萬用字元 \$1 命名配置)。
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
------
## 連接器參數
此連接器提供下列參數：
------
#### [ Version 4 ]
`DefaultSNSArn`
訊息發佈到的預設 SNS 主題 ARN。輸入訊息承載中的 `sns_topic_arn` 屬性可以覆寫目的地主題。
群組角色必須允許所有目標主題的 `sns:Publish` 許可。如需詳細資訊，請參閱[要求](#sns-connector-req)。
在 AWS IoT 主控台中顯示名稱：**預設 SNS 主題 ARN**
必要：`true`
類型：`string`
有效模式： `arn:aws:sns:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):([a-zA-Z0-9-_]+)$`
`IsolationMode`
此連接器的[容器化](connectors.md#connector-containerization)模式。預設值為 `GreengrassContainer`，這表示連接器會在 AWS IoT Greengrass 容器內的隔離執行時間環境中執行。
群組的預設容器化設定不會套用至連接器。
AWS IoT 主控台中的顯示名稱：**容器隔離模式**
必要：`false`
類型：`string`
有效值：`GreengrassContainer` 或 `NoContainer`
有效模式： `^NoContainer$|^GreengrassContainer$`
------
#### [ Versions 1 - 3 ]
`DefaultSNSArn`
訊息發佈到的預設 SNS 主題 ARN。輸入訊息承載中的 `sns_topic_arn` 屬性可以覆寫目的地主題。
群組角色必須允許所有目標主題的 `sns:Publish` 許可。如需詳細資訊，請參閱[要求](#sns-connector-req)。
在 AWS IoT 主控台中顯示名稱：**預設 SNS 主題 ARN**
必要：`true`
類型：`string`
有效模式： `arn:aws:sns:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):([a-zA-Z0-9-_]+)$`
------
### 建立範例連接器 (AWS CLI)
下列 CLI 命令`ConnectorDefinition`會使用包含 SNS 連接器的初始版本來建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MySNSConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/SNS/versions/4",
"Parameters": {
"DefaultSNSArn": "arn:aws:sns:region:account-id:topic-name",
"IsolationMode" : "GreengrassContainer"
}
}
]
}'
```
在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。
## 輸入資料
此連接器接受 MQTT 主題的 SNS 訊息資訊，然後將訊息依原樣發佈至目標 SNS 主題。輸入訊息必須是 JSON 格式。
**訂閱中的主題篩選條件**
`sns/message`
**訊息屬性**
`request`
要傳送到 SNS 主題之訊息的相關資訊。
必要：`true`
類型：`object`包含下列屬性：
`message`
做為字串或 JSON 格式的訊息內容。如需範例，請參閱[範例輸入](#sns-connector-data-input-example)。
若要傳送 JSON，`message_structure` 屬性必須設定為 `json`，並且訊息必須是字串編碼的 JSON 物件，其中包含 `default` 鍵。
必要：`true`
類型：`string`
有效模式： `.*`
`subject`
訊息的主旨。
必要：`false`
類型：ASCII 文字，最多 100 個字元。這必須以字母、數字或標點符號開頭。這不可包含換行或控制字元。
有效模式： `.*`
`sns_topic_arn`
將訊息發佈到其中的 SNS 主題的 ARN。如果指定，連接器會發佈到這個主題，而非預設主題。
群組角色必須允許任何目標主題的 `sns:Publish` 許可。如需詳細資訊，請參閱[要求](#sns-connector-req)。
必要：`false`
類型：`string`
有效模式： `arn:aws:sns:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):([a-zA-Z0-9-_]+)$`
`message_structure`
訊息的結構。
必要：`false`。這必須指定於傳送 JSON 訊息。
類型：`string`
有效值：`json`
`id`
請求的任意 ID。此屬性用於將輸入請求映射到輸出回應。當指定時，回應物件中的 `id` 屬性會設為這個值。如果您不使用此功能，您可以省略此屬性或指定空白字串。
必要：`false`
類型：`string`
有效模式： `.*`
**限制**
訊息大小以 SNS 訊息大小上限 256 KB 為限。
**範例輸入：字串訊息**
此範例會傳送字串訊息。會指定選用 `sns_topic_arn` 屬性，此屬性會覆寫預設目的地主題。
```
{
"request": {
"subject": "Message subject",
"message": "Message data",
"sns_topic_arn": "arn:aws:sns:region:account-id:topic2-name"
},
"id": "request123"
}
```
**範例輸入：JSON 訊息**
此範例會傳送做為字串編碼 JSON 物件的訊息，其中包含 `default` 鍵。
```
{
"request": {
"subject": "Message subject",
"message": "{ \"default\": \"Message data\" }",
"message_structure": "json"
},
"id": "request123"
}
```
## 輸出資料
這個連接器會將狀態資訊發佈為輸出資料，且主題為 MQTT。
**訂閱中的主題篩選條件**
`sns/message/status`
**範例輸出：成功**
```
{
"response": {
"sns_message_id": "f80a81bc-f44c-56f2-a0f0-d5af6a727c8a",
"status": "success"
},
"id": "request123"
}
```
**範例輸出：失敗**
```
{
"response" : {
"error": "InvalidInputException",
"error_message": "SNS Topic Arn is invalid",
"status": "fail"
},
"id": "request123"
}
```
## 用量範例
使用下列高階步驟來設定範例 Python 3.7 Lambda 函數，您可以用來嘗試連接器。
**注意**
如果您使用其他 Python 執行期，則可以建立從 Python3.x 到 Python 3.7 的符號連結。
[連接器入門 (主控台)](connectors-console.md) 和 [連接器入門 (CLI)](connectors-cli.md) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。
1. 確定您符合連接器的[要求](#sns-connector-req)。
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。
1. 建立並發佈 Lambda 函數，將輸入資料傳送至連接器。
將[範例程式碼](#sns-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. 新增連接器並設定其[參數](#sns-connector-param)。
1. 新增訂閱，允許連接器在支援主題篩選條件上接收[輸入資料](#sns-connector-data-input)並傳送[輸出資料](#sns-connector-data-output)。
+ 將 Lambda 函數設定為來源，將連接器設定為目標，並使用支援的輸入主題篩選條件。
+ 將連接器設為來源、將 AWS IoT Core 設為目標，並使用支援的輸出主題篩選條件。您可以使用此訂閱在 AWS IoT 主控台中檢視狀態訊息。
1. 部署群組。
1. 在 AWS IoT 主控台**的測試**頁面上，訂閱輸出資料主題，以檢視連接器的狀態訊息。Lambda 函數範例為長期函數，並在部署群組後立即開始傳送訊息。
完成測試後，您可以將 Lambda 生命週期設定為隨需 （或在 CLI `"Pinned": false`中） 並部署群組。這會讓函數停止傳送訊息。
### 範例
下列範例 Lambda 函數會將輸入訊息傳送至連接器。
```
import greengrasssdk
import time
import json
iot_client = greengrasssdk.client('iot-data')
send_topic = 'sns/message'
def create_request_with_all_fields():
return {
"request": {
"message": "Message from SNS Connector Test"
},
"id" : "req_123"
}
def publish_basic_message():
messageToPublish = create_request_with_all_fields()
print("Message To Publish: ", messageToPublish)
iot_client.publish(topic=send_topic,
payload=json.dumps(messageToPublish))
publish_basic_message()
def lambda_handler(event, context):
return
```
## 授權
SNS 連接器包含下列第三方軟體/授權：
+ [適用於 Python (Boto3) 的 AWS SDK](https://pypi.org/project/boto3/)/Apache License 2.0
+ [botocore](https://pypi.org/project/botocore/)/Apache License 2.0
+ [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License
+ [docutils](https://pypi.org/project/docutils/)/BSD 授權、GNU 一般公有授權 (GPL)、Python 軟體基金會授權、公有網域
+ [jmespath](https://pypi.org/project/jmespath/)/MIT License
+ [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0
+ [urllib3](https://pypi.org/project/urllib3/)/MIT License
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明每個版本連接器的變更。
| 版本 | 變更 |
| --- | --- |
| 4 | 已新增 `IsolationMode` 參數，以設定連接器的容器化模式。 |
| 3 | 將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 |
| 2 | 可減少過多記錄的修正。 |
| 1 | 初始版本。 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
+ Boto 3 文件中的[發佈動作](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sns.html#SNS.Client.publish)
+ 《Amazon Simple Notification Service 開發人員指南》**中的[什麼是 Amazon Simple Notification Service？](https://docs.aws.amazon.com/sns/latest/dg/welcome.html)
# Splunk 整合連接器
**警告**
此連接器已進入*延長的生命週期階段*， AWS IoT Greengrass 且不會發佈提供現有功能、增強功能、安全修補程式或錯誤修正的更新。如需詳細資訊，請參閱[AWS IoT Greengrass Version 1 維護政策](maintenance-policy.md)。
Splunk Integration [連接器](connectors.md)會將資料從 Greengrass 裝置發佈至 Splunk。這可讓您使用 Splunk 來監控和分析 Greengrass 核心環境，並對本機事件採取行動。連接器與 HTTP 事件收集器 (HEC) 整合。如需詳細資訊，請參閱 Splunk 文件中的 [Splunk HTTP 事件收集器簡介](https://dev.splunk.com/view/event-collector/SP-CAAAE6M)。
此連接器會接收 MQTT 主題上的記錄和事件資料，並將資料依現狀發佈到 Splunk API。
您可以使用此連接器來支援工業案例，例如：
+ 運算子可以使用來自傳動器和感應器的定期資料 （例如溫度、壓力和水讀數），在值超過特定閾值時啟動警示。
+ 開發人員使用從工業機械收集的資料，以建置機器學習模型來監控設備的潛在問題。
此連接器具有下列版本。
| 版本 | ARN |
| --- | --- |
| 4 | `arn:aws:greengrass:region::/connectors/SplunkIntegration/versions/4` |
| 3 | `arn:aws:greengrass:region::/connectors/SplunkIntegration/versions/3` |
| 2 | `arn:aws:greengrass:region::/connectors/SplunkIntegration/versions/2` |
| 1 | `arn:aws:greengrass:region::/connectors/SplunkIntegration/versions/1` |
如需版本變更的詳細資訊，請參閱 [Changelog](#splunk-connector-changelog)。
## 要求
此連接器有下列要求：
------
#### [ Version 3 - 4 ]
+ 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 需求。
+ Splunk 中必須啟用 HTTP 事件收集器功能。如需詳細資訊，請參閱 Splunk 文件中的[在 Splunk Web 中設定和使用 HTTP 事件收集器](https://docs.splunk.com/Documentation/Splunk/7.2.0/Data/UsetheHTTPEventCollector)。
+ 在 中 AWS Secrets Manager 存放 Splunk HTTP 事件收集器字符的文字類型秘密。如需詳細資訊，請參閱 Splunk 文件中的[關於事件收集器權杖](https://docs.splunk.com/Documentation/Splunk/7.2.0/Data/UsetheHTTPEventCollector#About_Event_Collector_tokens)和*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 - 2 ]
+ AWS IoT Greengrass 核心軟體 v1.7 或更新版本。 AWS IoT Greengrass 必須設定為支援本機秘密，如[秘密要求](secrets.md#secrets-reqs)中所述。
**注意**
此要求包括允許存取您的 Secrets Manager 秘密。如果您使用的是預設 Greengrass 服務角色，Greengrass 具有許可，可取得名稱開頭為 *greengrass-* 的秘密值。
+ [Python](https://www.python.org/) 2.7 版安裝在核心裝置上，並新增至 PATH 環境變數。
+ Splunk 中必須啟用 HTTP 事件收集器功能。如需詳細資訊，請參閱 Splunk 文件中的[在 Splunk Web 中設定和使用 HTTP 事件收集器](https://docs.splunk.com/Documentation/Splunk/7.2.0/Data/UsetheHTTPEventCollector)。
+ 在 中 AWS Secrets Manager 存放 Splunk HTTP 事件收集器字符的文字類型秘密。如需詳細資訊，請參閱 Splunk 文件中的[關於事件收集器權杖](https://docs.splunk.com/Documentation/Splunk/7.2.0/Data/UsetheHTTPEventCollector#About_Event_Collector_tokens)和*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 4 ]
`SplunkEndpoint`
Splunk 執行個體的端點。這個值必須包含通訊協定、主機名稱和連接埠。
AWS IoT 主控台中的顯示名稱：**Splunk 端點**
必要： `true`
類型：`string`
有效模式： `^(http:\/\/|https:\/\/)?[a-z0-9]+([-.]{1}[a-z0-9]+)*.[a-z]{2,5}(:[0-9]{1,5})?(\/.*)?$`
`MemorySize`
配置給連接器的記憶體數量 (KB)。
AWS IoT 主控台中的顯示名稱：**記憶體大小**
必要： `true`
類型：`string`
有效模式： `^[0-9]+$`
`SplunkQueueSize`
提交或捨棄項目之前在記憶體中儲存的項目數上限。達到此限制時，佇列中最舊項目會由較新項目取代。此限制通常適用於未連接到網際網路時。
在 AWS IoT 主控台中顯示名稱：**要保留的項目上限**
必要： `true`
類型：`string`
有效模式： `^[0-9]+$`
`SplunkFlushIntervalSeconds`
將收到的資料發佈到 Splunk HEC 的間隔 (以秒為單位)。最大值為 900。若要將連接器設定為一收到項目就立刻將其發佈 (不批次處理)，請指定 0。
AWS IoT 主控台中的顯示名稱：**Splunk 發佈間隔**
必要： `true`
類型：`string`
有效模式： `[0-9]|[1-9]\d|[1-9]\d\d|900`
`SplunkTokenSecretArn`
中 AWS Secrets Manager 存放 Splunk 字符的秘密。這必須是文字類型私密。
在 AWS IoT 主控台中顯示名稱：**Splunk 驗證字符秘密的 ARN**
必要： `true`
類型：`string`
有效模式： `arn:aws:secretsmanager:[a-z]{2}-[a-z]+-\d{1}:\d{12}?:secret:[a-zA-Z0-9-_]+-[a-zA-Z0-9-_]+`
`SplunkTokenSecretArn-ResourceId`
Greengrass 群組中參考 Splunk 私密的私密資源。
AWS IoT 主控台中的顯示名稱：**Splunk 驗證字符資源**
必要： `true`
類型：`string`
有效模式： `.+`
`SplunkCustomCALocation`
Splunk 自訂憑證授權單位 (CA) 的檔案路徑 (例如 `/etc/ssl/certs/splunk.crt`)。
AWS IoT 主控台中的顯示名稱：**Splunk 自訂憑證授權單位位置**
必要： `false`
類型：`string`
有效模式： `^$|/.*`
`IsolationMode`
此連接器的[容器化](connectors.md#connector-containerization)模式。預設值為 `GreengrassContainer`，這表示連接器在 AWS IoT Greengrass 容器內的隔離執行時間環境中執行。
群組的預設容器化設定不會套用至連接器。
在 AWS IoT 主控台中顯示名稱：**容器隔離模式**
必要： `false`
類型：`string`
有效值：`GreengrassContainer` 或 `NoContainer`
有效模式： `^NoContainer$|^GreengrassContainer$`
------
#### [ Version 1 - 3 ]
`SplunkEndpoint`
Splunk 執行個體的端點。這個值必須包含通訊協定、主機名稱和連接埠。
AWS IoT 主控台中的顯示名稱：**Splunk 端點**
必要： `true`
類型：`string`
有效模式： `^(http:\/\/|https:\/\/)?[a-z0-9]+([-.]{1}[a-z0-9]+)*.[a-z]{2,5}(:[0-9]{1,5})?(\/.*)?$`
`MemorySize`
配置給連接器的記憶體數量 (KB)。
AWS IoT 主控台中的顯示名稱：**記憶體大小**
必要： `true`
類型：`string`
有效模式： `^[0-9]+$`
`SplunkQueueSize`
提交或捨棄項目之前在記憶體中儲存的項目數上限。達到此限制時，佇列中最舊項目會由較新項目取代。此限制通常適用於未連接到網際網路時。
在 AWS IoT 主控台中顯示名稱：**要保留的項目上限**
必要： `true`
類型：`string`
有效模式： `^[0-9]+$`
`SplunkFlushIntervalSeconds`
將收到的資料發佈到 Splunk HEC 的間隔 (以秒為單位)。最大值為 900。若要將連接器設定為一收到項目就立刻將其發佈 (不批次處理)，請指定 0。
AWS IoT 主控台中的顯示名稱：**Splunk 發佈間隔**
必要： `true`
類型：`string`
有效模式： `[0-9]|[1-9]\d|[1-9]\d\d|900`
`SplunkTokenSecretArn`
中 AWS Secrets Manager 存放 Splunk 字符的秘密。這必須是文字類型私密。
在 AWS IoT 主控台中顯示名稱：**Splunk 驗證字符秘密的 ARN**
必要： `true`
類型：`string`
有效模式： `arn:aws:secretsmanager:[a-z]{2}-[a-z]+-\d{1}:\d{12}?:secret:[a-zA-Z0-9-_]+-[a-zA-Z0-9-_]+`
`SplunkTokenSecretArn-ResourceId`
Greengrass 群組中參考 Splunk 私密的私密資源。
AWS IoT 主控台中的顯示名稱：**Splunk 驗證字符資源**
必要： `true`
類型：`string`
有效模式： `.+`
`SplunkCustomCALocation`
Splunk 自訂憑證授權單位 (CA) 的檔案路徑 (例如 `/etc/ssl/certs/splunk.crt`)。
AWS IoT 主控台中的顯示名稱：**Splunk 自訂憑證授權單位位置**
必要： `false`
類型：`string`
有效模式： `^$|/.*`
------
### 建立範例連接器 (AWS CLI)
下列 CLI 命令`ConnectorDefinition`會使用包含 Splunk 整合連接器的初始版本來建立 。
```
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
"Connectors": [
{
"Id": "MySplunkIntegrationConnector",
"ConnectorArn": "arn:aws:greengrass:region::/connectors/SplunkIntegration/versions/4",
"Parameters": {
"SplunkEndpoint": "https://myinstance.cloud.splunk.com:8088",
"MemorySize": 200000,
"SplunkQueueSize": 10000,
"SplunkFlushIntervalSeconds": 5,
"SplunkTokenSecretArn":"arn:aws:secretsmanager:region:account-id:secret:greengrass-secret-hash",
"SplunkTokenSecretArn-ResourceId": "MySplunkResource",
"IsolationMode" : "GreengrassContainer"
}
}
]
}'
```
**注意**
此連接器中的 Lambda 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。
在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。
## 輸入資料
此連接器接受 MQTT 主題上的記錄和事件資料，並將收到的資料依原樣發佈至 Splunk API。輸入訊息必須是 JSON 格式。
**訂閱中的主題篩選條件**
`splunk/logs/put`
**訊息屬性**
`request`
要傳送到 Splunk API 的事件資料。事件必須符合 [服務/收集器](https://docs.splunk.com/Documentation/Splunk/latest/RESTREF/RESTinput#services.2Fcollector) API 的規格。
必要： `true`
類型：`object`。只需要 `event` 屬性。
`id`
請求的任意 ID。此屬性用於將輸入請求映射到輸出狀態。
必要： `false`
類型：`string`
**限制**
Splunk API 實施的所有限制，在使用此連接器時都適用。如需詳細資訊，請參閱[服務/收集器](https://docs.splunk.com/Documentation/Splunk/latest/RESTREF/RESTinput#services.2Fcollector)。
**範例輸入**
```
{
"request": {
"event": "some event",
"fields": {
"severity": "INFO",
"category": [
"value1",
"value2"
]
}
},
"id": "request123"
}
```
## 輸出資料
此連接器將輸出資料發佈在兩個主題：
+ `splunk/logs/put/status` 主題上的狀態資訊。
+ `splunk/logs/put/error`主題的相關錯誤。
**主題篩選條件：** `splunk/logs/put/status`
使用此主題監聽請求的狀態。每次連接器將一批收到的資料傳送到 Splunk API 時，就會發佈成功請求和失敗請求的 ID 清單。
**範例輸出**
```
{
"response": {
"succeeded": [
"request123",
...
],
"failed": [
"request789",
...
]
}
}
```
**主題篩選條件：** `splunk/logs/put/error`
使用此主題監聽來自連接器的錯誤。`error_message` 屬性，描述處理請求時發生的錯誤或逾時。
**範例輸出**
```
{
"response": {
"error": "UnauthorizedException",
"error_message": "invalid splunk token",
"status": "fail"
}
}
```
如果連接器偵測到可重試的錯誤 （例如連線錯誤），則會在下一個批次中重試發佈。
## 使用範例
使用下列高階步驟來設定範例 Python 3.7 Lambda 函數，您可以用來嘗試連接器。
**注意**
如果您使用其他 Python 執行期，則可以建立從 Python3.x 到 Python 3.7 的符號連結。
[連接器入門 (主控台)](connectors-console.md) 和 [連接器入門 (CLI)](connectors-cli.md) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。
1. 確定您符合連接器的[要求](#splunk-connector-req)。
1. 建立並發佈 Lambda 函數，將輸入資料傳送至連接器。
將[範例程式碼](#splunk-connector-usage-example)儲存為 PY 檔案。下載並解壓縮[AWS IoT Greengrass 適用於 Python 的 核心 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. 新增連接器並設定其[參數](#splunk-connector-param)。
1. 新增訂閱，允許連接器在支援主題篩選條件上接收[輸入資料](#splunk-connector-data-input)並傳送[輸出資料](#splunk-connector-data-output)。
+ 將 Lambda 函數設定為來源，將連接器設定為目標，並使用支援的輸入主題篩選條件。
+ 將連接器設為來源、將 AWS IoT Core 設為目標，並使用支援的輸出主題篩選條件。您可以使用此訂閱在 AWS IoT 主控台中檢視狀態訊息。
1. 部署群組。
1. 在 AWS IoT 主控台**的測試**頁面上，訂閱輸出資料主題，以檢視連接器的狀態訊息。Lambda 函數範例為長期函數，並在部署群組後立即開始傳送訊息。
完成測試後，您可以將 Lambda 生命週期設定為隨需 （或在 CLI `"Pinned": false`中） 並部署群組。這會讓函數停止傳送訊息。
### 範例
下列範例 Lambda 函數會將輸入訊息傳送至連接器。
```
import greengrasssdk
import time
import json
iot_client = greengrasssdk.client('iot-data')
send_topic = 'splunk/logs/put'
def create_request_with_all_fields():
return {
"request": {
"event": "Access log test message."
},
"id" : "req_123"
}
def publish_basic_message():
messageToPublish = create_request_with_all_fields()
print("Message To Publish: ", messageToPublish)
iot_client.publish(topic=send_topic,
payload=json.dumps(messageToPublish))
publish_basic_message()
def lambda_handler(event, context):
return
```
## 授權
此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。
## 變更記錄
下表說明每個連接器版本中的變更。
| 版本 | 變更 |
| --- | --- |
| 4 | 已新增 `IsolationMode` 參數，以設定連接器的容器化模式。 |
| 3 | 將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 |
| 2 | 可減少過多記錄的修正。 |
| 1 | 初始版本。 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 另請參閱
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)
# 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 的 核心 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)
# Greengrass 連接器入門 (主控台)
此功能適用於 AWS IoT Greengrass Core v1.7 和更新版本。
本教學課程說明如何使用 AWS 管理主控台 來使用連接器。
使用連接器來加速您的開發生命週期。連接器是預先建置的、可重複使用的模組，可讓您更輕鬆地與服務、通訊協定和資源互動。它們可協助您更快地將商業邏輯部署到 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-console-create-secret)
1. [將私密資源新增至群組](#connectors-console-create-resource)
1. [將連接器新增到群組](#connectors-console-create-connector)
1. [建立 Lambda 函數部署套件](#connectors-console-create-deployment-package)
1. [建立 Lambda 函式](#connectors-console-create-function)
1. [將函數新增到群組](#connectors-console-create-gg-function)
1. [新增訂閱到群組](#connectors-console-create-subscription)
1. [部署群組](#connectors-console-create-deployment)
1. [測試解決方案](#connectors-console-test-solution)
此教學課程需約 20 分鐘完成。
## 先決條件
為完成此教學課程您需要：
+ 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)。
## 步驟 1：建立 Secrets Manager 秘密
在此步驟中，您可以使用 AWS Secrets Manager 主控台為 Twilio 驗證字符建立文字類型秘密。
1. 登入 [AWS Secrets Manager 主控台](https://console.aws.amazon.com/secretsmanager/)。
**注意**
如需此程序的詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[步驟 1：建立和存放您的秘密 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/tutorials_basic.html)。
1. 選擇**儲存新機密**。
1. 在**選擇秘密類型**下，選擇**其他類型的秘密**。
1. 在**指定要為此秘密存放的金鑰/值對**下，在**純文字**索引標籤上，輸入您的 Twilio 驗證字符。移除所有的 JSON 格式，只輸入字符值。
1. 保持選取加密金鑰的 **aws/secretsmanager**，然後選擇**下一步**。
**注意**
AWS KMS 如果您使用 Secrets Manager 在帳戶中建立的預設 AWS 受管金鑰，則 不會向您收費。
1. 針對 **Secret name (私密名稱)**，輸入 **greengrass-TwilioAuthToken**，然後選擇 **Next (下一步)**。
**注意**
根據預設，Greengrass 服務角色允許 AWS IoT Greengrass 取得名稱開頭為 *greengrass-* 的秘密值。如需詳細資訊，請參閱[私密需求](secrets.md#secrets-reqs)。
1. 本教學課程不需要輪換，因此請選擇停用自動輪換，然後選擇**下一步**。
1. 在 **Review (檢閱)** 頁面上，檢閱設定，然後選擇 **Store (儲存)**。
接著，您可以在 Greengrass 群組中建立一個參考私密的私密資源。
## 步驟 2：將私密資源新增至 Greengrass 群組
在此步驟中，您會將*私密資源*新增到 Greengrass 群組。此資源會參考您在上一步中建立的私密。
1. 在 AWS IoT 主控台導覽窗格的**管理**下，展開 **Greengrass 裝置**，然後選擇**群組 (V1)**。
1. 選擇您要將私密資源新增至其中的群組。
1. 在群組組態頁面上，選擇**資源**索引標籤，然後向下捲動至**秘密**區段。**秘密**區段會顯示屬於 群組的秘密資源。您可以從本節新增、編輯和移除秘密資源。
**注意**
或者，主控台可讓您在設定連接器或 Lambda 函數時建立秘密和秘密資源。您可以從連接器**的設定參數**頁面或 Lambda 函數**的資源**頁面執行此操作。
1. 在**秘密**區段下選擇**新增**。
1. 在**新增秘密資源**頁面上，輸入 **MyTwilioAuthToken** 做為**資源名稱**。
1. 針對**秘密**，選擇 **greengrass-TwilioAuthToken**。
1. 在**選取標籤 （選用）** 區段中，AWSCURRENT 預備標籤代表秘密的最新版本。此標籤一律包含在私密資源中。
**注意**
本教學課程僅需要 AWSCURRENT 標籤。您可以選擇性地包含 Lambda 函數或連接器所需的標籤。
1. 選擇 **Add resource (新增資源)**。
## 步驟 3：將連接器新增到 Greengrass 群組
在此步驟中，您會設定 [Twilio Notifications 連接器](twilio-notifications-connector.md)的參數，並將其新增至群組。
1. 在群組組態頁面上，選擇 **Connectors (連接器)**，然後選擇 **Add a connector (新增連接器)**。
1. 在**新增連接器**頁面上，選擇 **Twilio Notifications**。
1. 選擇 版本。
1. 在**組態**區段中：
+ 對於 **Twilio 驗證字符資源**，輸入您在上一個步驟中建立的資源。
**注意**
當您輸入 資源時，會為您填入 **Twilio 驗證字符秘密屬性的 ARN**。
+ 針對 **Default from phone number (預設從電話號碼)**，輸入已啟用 Twilio 的電話號碼。
+ 針對 **Twilio account SID (Twilio 帳戶 SID)**，輸入您的 Twilio 帳戶 SID。
1. 選擇 **Add resource (新增資源)**。
## 步驟 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 函數部署套件。
現在，建立使用部署套件的 Lambda 函數。
## 步驟 5：在 AWS Lambda 主控台中建立 Lambda 函數
在此步驟中，您會使用 AWS Lambda 主控台來建立 Lambda 函數，並將其設定為使用您的部署套件。然後，您會發佈函數版本和建立別名。
1. 首先，建立 Lambda 函數。
1. 在 中 AWS 管理主控台，選擇**服務**，然後開啟 AWS Lambda 主控台。
1. 選擇**建立函數**，然後選擇**從頭開始撰寫**。
1. 在 **Basic information (基本資訊)** 區段中，使用下列值：
+ 針對**函數名稱**，請輸入 **TempMonitor**。
+ 針對**執行期**，選擇 **Python 3.7**。
+ 對於**許可**，請保留預設設定。這會建立授予基本 Lambda 許可的執行角色。不會使用此角色 AWS IoT Greengrass。
1. 請在頁面底部，選擇**建立函式**。
1. 接著，註冊處理常式並上傳您的 Lambda 函數部署套件。
1. 在**程式碼**索引標籤的**程式碼來源**下，選擇**上傳來源**。從下拉式清單中，選擇 **.zip 檔案**。
![\[從下拉式清單上傳，並反白顯示 .zip 檔案。\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/images/lra-console/upload-deployment-package.png)
1. 選擇**上傳**，然後選擇您的`temp_monitor_python.zip`部署套件。然後選擇 **Save (儲存)**。
1. 在函數的**程式碼**索引標籤的**執行時間設定**下，選擇**編輯**，然後輸入下列值。
+ 針對**執行期**，選擇 **Python 3.7**。
+ 對於 **Handler (處理常式)**，輸入 **temp\$1monitor.function\$1handler**。
1. 選擇**儲存**。
**注意**
AWS Lambda 主控台上的**測試**按鈕不適用於此函數。 AWS IoT Greengrass 核心 SDK 不包含在 AWS Lambda 主控台中獨立執行 Greengrass Lambda 函數所需的模組。這些模組 （例如 `greengrass_common`) 會在部署到您的 Greengrass 核心之後提供給函數。
1. 現在，發佈 Lambda 函數的第一個版本，並為[該版本建立別名](https://docs.aws.amazon.com/lambda/latest/dg/versioning-aliases.html)。
**注意**
Greengrass 群組可以依別名 （建議） 或版本參考 Lambda 函數。使用別名可讓您更輕鬆地管理程式碼更新，因為您不必在更新函數程式碼時變更訂閱資料表或群組定義。反之，您只需將別名指向新的函數版本。
1. 請從**操作**功能表中選擇**發行新版本**。
1. 針對 **Version description (版本描述)**，輸入 **First version**，然後選擇 **Publish (發佈)**。
1. 在 **TempMonitor: 1 ** 組態頁面，從 **Actions (動作)** 選單中選擇 **Create alias (建立別名)**。
1. 在**建立警示**頁面上使用下列值：
+ 對於**名稱**，輸入 **GG\$1TempMonitor**。
+ 對於**版本**，選擇 **1**。
**注意**
AWS IoT Greengrass 不支援 **\$1LATEST** 版本的 Lambda 別名。
1. 選擇**建立**。
現在您已準備好將 Lambda 函數新增至 Greengrass 群組。
## 步驟 6：將 Lambda 函數新增至 Greengrass 群組
在此步驟中，您將 Lambda 函數新增至 群組，然後設定其生命週期和環境變數。如需詳細資訊，請參閱[使用群組特定的組態控制 Greengrass Lambda 函數的執行](lambda-group-config.md)。
1. 在群組組態頁面上，選擇 **Lambda 函數**索引標籤。
1. 在**我的 Lambda 函數**下，選擇**新增**。
1. 在**新增 Lambda 函數**頁面上，為您的 Lambda 函數選擇 **TempMonitor**。
1. 針對 **Lambda 函數版本**，選擇**別名：GG\$1TempMonitor**。
1. 選擇**新增 Lambda 函數**。
## 步驟 7：將訂閱新增到 Greengrass 群組
在此步驟中，您會新增訂閱，讓 Lambda 函數將輸入資料傳送至連接器。連接器定義它所訂閱的 MQTT 主題，所以這個訂閱使用其中一個主題。這是範例函數發佈到的同一個主題。
在本教學課程中，您也會建立訂閱，允許函數接收來自 AWS IoT 的模擬溫度讀數 AWS IoT ，並允許 從連接器接收狀態資訊。
1. 在群組組態頁面上，選擇**訂閱**索引標籤，然後選擇**新增訂閱**。
1. 在**建立訂閱**頁面上，設定來源和目標，如下所示：
1. 針對**來源類型**，選擇 **Lambda 函數**，然後選擇 **TempMonitor**。
1. 針對**目標類型**，選擇**連接器**，然後選擇 **Twilio Notifications**。
1. 針對**主題篩選條件**，選擇 **twilio/txt**。
1. 選擇**建立訂閱**。
1. 重複步驟 1 - 4 來建立允許 AWS IoT 將訊息發佈至 函數的訂閱。
1. 針對**來源類型**，選擇**服務**，然後選擇 **IoT Cloud**。
1. 針對**選取目標**，選擇 **Lambda 函數**，然後選擇 **TempMonitor**。
1. 針對 **Topic filter (主題篩選條件)**，輸入 **temperature/input**。
1. 重複步驟 1 – 4，建立允許連接器發佈訊息至 AWS IoT的訂閱。
1. 針對**來源類型**，選擇**連接器**，然後選擇 **Twilio Notifications**。
1. 針對**目標類型**，選擇**服務**，然後選擇 **IoT 雲端**。
1. 針對 **Topic filter (主題篩選條件)**，已為您輸入 **twilio/message/status**。此為連接器所發佈到的預先定義主題。
## 步驟 8：部署 Greengrass 群組
將群組部署到核心裝置。
1. 確定 AWS IoT Greengrass 核心正在執行。如果需要，請在您的 Raspberry Pi 終端機執行以下命令。
1. 檢查精靈是否有在運作：
```
ps aux | grep -E 'greengrass.*daemon'
```
若輸出的 `root` 含有 `/greengrass/ggc/packages/ggc-version/bin/daemon` 項目，則精靈有在運作。
**注意**
路徑中的版本取決於核心裝置上安裝的核心 AWS IoT Greengrass 軟體版本。
1. 若要啟動協助程式：
```
cd /greengrass/ggc/core/
sudo ./greengrassd start
```
1. 在群組組態頁面上，選擇**部署**。
1.
1. 在 **Lambda 函數**索引標籤**的系統 Lambda 函數**區段下，選取 **IP 偵測器**，然後選擇**編輯**。
1. 在**編輯 IP 偵測器設定**對話方塊中，選取**自動偵測和覆寫 MQTT 代理程式端點**。
1. 選擇**儲存**。
這可讓裝置自動取得核心的連接資訊，例如 IP 位址、DNS、連接埠編號。建議自動偵測，但 AWS IoT Greengrass 也支援手動指定的端點。只會在第一次部署群組時收到復原方法的提示。
**注意**
如果出現提示，請授予許可來建立 [Greengrass 服務角色](service-role.md)，並將其與目前 AWS 帳戶 中的 建立關聯 AWS 區域。此角色允許 AWS IoT Greengrass 存取 AWS 服務中的資源。
此**部署**頁面會顯示部署時間戳記、版本 ID 和狀態。完成後，部署顯示的狀態應為**已完成**。
如需故障診斷協助，請參閱[故障診斷 AWS IoT Greengrass](gg-troubleshooting.md)。
**注意**
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。
## 測試解決方案
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-console.html)
1. 針對**發佈至主題**，請使用下列值，然後選擇**發佈**以叫用函數。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/connectors-console.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 連接器入門 (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 參考中的 命令*