AWS IoT Greengrass Version 1 於 2023 年 6 月 30 日進入延長使用壽命階段。如需詳細資訊，請參閱AWS IoT Greengrass V1 維護政策。在此日期之後， AWS IoT Greengrass V1 將不會發行提供功能、增強功能、錯誤修正或安全性修補程式的更新。在上運行的設備 AWS IoT Greengrass V1 不會中斷，並將繼續運行並連接到雲。我們強烈建議您移轉至 AWS IoT Greengrass Version 2，這會增加重要的新功能，並支援其他平台。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
IoT Analytics
警告
此連接器已進入延長使用壽命階段，AWS IoT Greengrass不會發行提供功能、現有功能增強功能、安全性修補程式或錯誤修正的更新。如需詳細資訊，請參閱AWS IoT Greengrass Version 1維護政策。
IoT 分析連接器會將本機裝置資料傳送至AWS IoT Analytics。您可以使用此連接器做為中央集線器，從 Greengrass 核心裝置上的感應器和連線的用戶端裝置收集資料。連接器將數據發送到當前AWS 帳戶和區域中的AWS IoT Analytics通道。它可以將資料傳送到預設目的地管道和動態指定的管道。
注意
AWS IoT Analytics 是一種全受管的服務，可讓您收集、存放、處理和查詢 IoT 資料。您可以在 AWS IoT Analytics 中進一步分析和處理資料。例如，您可以用於訓練機器學習模型來監控機器運作狀況，或測試新的建模策略。如需詳細資訊，請參閱《AWS IoT Analytics 使用者指南》中的什麼是 AWS IoT Analytics？。
連接器接受輸入 MQTT 主題上的有格式和無格式資料。它支援兩種預先定義的主題，目的地管道為指定的內嵌。它也可以接收在訂閱中配置的客戶定義主題訊息。這可用於從發佈到固定主題的用戶端裝置路由傳送訊息，或處理來自資源受限裝置的非結構化或堆疊相依資料。
此連接器會使用 BatchPutMessageAPI 將資料 (以 JSON 或 base64 編碼的字串形式) 傳送至目的地通道。連接器可將原始資料處理為符合 API 要求的格式。連接器會依管道佇列緩衝輸入的訊息，並以非同步方式處理批次。它提供參數，讓您控制佇列和批次處理行為，以及限制記憶體用量。例如，您可以設定最大佇列大小、批次間隔、記憶體大小和作用中管道的數量。
此連接器具有下列版本。
版本 |
ARN |
|---|---|
4 |
|
3 |
|
2 |
|
1 |
|
如需版本變更的詳細資訊，請參閱 Changelog。
請求
此連接器有下列要求：
參數
MemorySize-
配置給此連接器的記憶體數量 (KB)。
AWS IoT控制台中的顯示名稱：內存大小
必要：
true類型：
string有效模式：
^[0-9]+$ PublishRegion-
您AWS 區域的AWS IoT Analytics頻道是在中創建的。使用與連接器相同的區域。
注意
這也必須與群組角色中指定的管道所在區域相同。
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-
此連接器的容器化模式。預設值為
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 函數具有長壽命的生命週期。
在AWS IoT Greengrass主控台中，您可以從群組的 [連接器] 頁面新增連接器。如需詳細資訊，請參閱Greengrass 連接器入門 (主控台)。
輸入資料
此連接器根據預先定義和客戶定義的 MQTT 主題接受資料。發行者可以是用戶端裝置、Lambda 函數或其他連接器。
- 預先定義的主題
-
連接器支援以下兩個結構化 MQTT 主題，讓發佈方內嵌指定頻道名稱。
-
關於該
iotanalytics/channels/+/messages/put主題的格式化消息。這些輸入訊息中的 IoT 資料，必須格式化為 JSON 或 base64 編碼字串。 -
有關
iotanalytics/channels/+/messages/binary/put主題的非格式化訊息。在此主題接收到的輸入訊息皆視為二元資料，可包含任何資料類型。若要發佈到預先定義的主題，請將
+萬用字元改為管道名稱。例如：iotanalytics/channels/my_channel/messages/put
-
- 客戶定義的主題
-
連接器支援
#主題的語法，可接受您在訂閱中配置的任何 MQTT 主題中的輸入訊息。我們建議您指定主題路徑，而不要在訂閱中僅使用#萬用字元。這些訊息會傳送至您為連接器指定的預設通道。客戶定義主題上的輸入訊息視為二元資料。此類資料可使用任何訊息格式，並包含任何資料類型。您可以使用客戶定義的主題，從發佈至固定主題的裝置路由訊息。您也可以使用它們來接受來自用戶端裝置的輸入資料，這些裝置無法將資料處理成格式化的訊息以傳送至連接器。
如需更多關於訂閱和 MQTT 主題的資訊，請參閱 輸入和輸出。
群組角色必須允許所有目標管道上的 iotanalytics:BatchPutMessage 動作。如需詳細資訊，請參閱請求。
- 主題篩選條件：
iotanalytics/channels/+/messages/put -
使用此主題將格式化訊息傳送至連接器，並動態指定目的地頻道。此主題也可讓您指定 ID，在回應輸出中傳回。連接器驗證每則傳送至 AWS IoT Analytics 之傳出
BatchPutMessage請求的訊息 ID 為獨特。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 前，連接器會將訊息編碼，讓格式符合
BatchPutMessageAPI 要求：連接器 base64 編碼原始資料，並將編碼的酬載加入傳出的
BatchPutMessage請求。連接器會為每個輸入訊息產生和指派 ID。
注意
連接器的回應輸出不包含這些輸入訊息的 ID 相關性。
- 訊息屬性
-
無。
- 主題篩選條件：
# -
使用此主題將任何訊息格式傳送至預設管道。當您的用戶端裝置發佈到固定主題，或者當您想要從無法將資料處理為連接器支援的訊息格式的用戶端裝置傳送資料至預設通道時，此功能特別有用。
您可以在為將此連接器連線到資料來源而建立的訂閱中定義主題語法。我們建議您指定主題路徑，而不要在訂閱中僅使用
#萬用字元。連接器資料不剖析發佈至此輸入主題的訊息。所有輸入訊息視為二元資料。將訊息傳送至 AWS IoT Analytics 前，連接器會將訊息編碼，讓格式符合
BatchPutMessageAPI 要求：連接器 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 運行時，則可以創建一個從 Python 3.x 到 Python 3.7 的符號鏈接。
-
連接器入門 (主控台) 和 連接器入門 (CLI) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。
確定您符合連接器的要求。
針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱管理 Greengrass 群組角色 (主控台)或管理 Greengrass 群組角色 (CLI)。
-
建立並發佈將輸入資料傳送至連接器的 Lambda 函數。
將範例程式碼儲存為 PY 檔案。下載並解壓縮適用於 Python 的AWS IoT Greengrass核心開發套件。然後，建立在根層級包含 PY 檔案和
greengrasssdk資料夾的 zip 套件。此 zip 套件是您上傳至的部署套件AWS Lambda。建立 Python 3.7 Lambda 函數之後，請發佈函數版本並建立別名。
-
設定 Greengrass 群組。
-
部署群組。
-
在主AWS IoT控台的 [測試] 頁面上，訂閱輸出資料主題，以檢視來自連接器的狀態訊息。Lambda 函數的範例很長，並且會在部署群組後立即開始傳送訊息。
完成測試後，您可以將 Lambda 生命週期設定為隨需 (或
"Pinned": false在 CLI 中)，然後部署群組。這會讓函數停止傳送訊息。
範例
下列範例 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
限制
此連接器受下列限制的約束。
對該動作施加AWS SDK for Python (Boto3)的所有限AWS IoT Analytics
batch_put_message制。 AWS IoT Analytics BatchPutMessageAPI 施加的所有配額。如需詳細資 Service Quotas 請AWS IoT Analytics參閱 AWS 一般參考.
每個管道每秒 100,000 個訊息。
每個批次 100 則訊息。
每則訊息 128 KB。
這個 API 使用管道名稱 (而非管道 ARN)，因此不支援跨區域或跨帳戶管道傳送資料。
所有由 AWS IoT Greengrass 核心施加的配額。如需詳細資訊，AWS IoT Greengrass請參閱 AWS 一般參考.
以下配額可能特別適用：
裝置傳送的訊息大小上限為 128 KB。
Greengrass 核心路由器中的訊息佇列大小上限為 2.5 MB。
主題字串的長度上限為 256 位元組的 UTF-8 編碼字元。
许可证
IoT 分析連接器包含下列協力廠商軟體/授權：
-
AWS SDK for Python (Boto3)
/Apache License 2.0 -
botocore
/Apache License 2.0 -
dateutil
/PSF License -
docutils
/BSD 授權、GNU 一般公有授權 (GPL)、Python 軟體基金會授權、公有網域 -
jmespath
/MIT License -
s3transfer
/Apache License 2.0 -
urllib3
/MIT License
此連接器是根據 Greengrass 核心軟體授權合約
Changelog
下表說明連接器每個版本中均會說明變更。
版本 |
改變 |
|---|---|
4 |
新增 |
3 |
將 Lambda 執行階段升級至 Python 3.7，這會變更執行階段需求。 |
2 |
可減少過多記錄的修正。 |
1 |
初始版本。 |
Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱升級連接器版本。
另請參閱
-
《AWS IoT Analytics 使用者指南》中的什麼是 AWS IoT Analytics？
