支援終止通知：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)。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 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)