本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 建立資料來源的自訂連接器 本主題說明如何將自訂資料來源連線至 CloudWatch。可以透過兩種方式將自訂資料來源連線至 CloudWatch： + 使用 CloudWatch 提供的範本範例。可以將 JavaScript 或 Python 與此範本搭配使用。這些範本包含 Lambda 程式碼範例，這些程式碼在您建立 Lambda 函式時很有用。然後，可以從範本中修改 Lambda 函數，以連線到自訂資料來源。 + 從頭開始建立 AWS Lambda 函數，以實作資料來源連接器、資料查詢，以及準備供 CloudWatch 使用的時間序列。如有需要，此函數必須預先彙總或合併資料點，並調整時段和時間戳記，以便與 CloudWatch 相容。 **Contents** + [使用範本](#CloudWatch_MultiDataSources-Connect-Custom-template) + [從頭開始建立自訂資料來源](#CloudWatch_MultiDataSources-Connect-Custom-Lambda) + [步驟 1：建立函數](#MultiDataSources-Connect-Custom-Lambda-Function) + [GetMetricData 事件](#MultiDataSources-GetMetricData) + [DescribeGetMetricData 事件](#MultiDataSources-DescribeGetMetricData) + [CloudWatch 警示的重要考量](#MultiDataSources-Connect-Custom-Lambda-Alarms) + [（選用） 使用 AWS Secrets Manager 存放登入資料](#MultiDataSources-Connect-Custom-Lambda-Secrets) + [(選用) 連線至 VPC 中的資料來源](#MultiDataSources-Connect-Custom-Lambda-VPC) + [步驟 2：建立 Lambda 許可政策](#MultiDataSources-Connect-Custom-Lambda-Permissions) + [步驟 3：將資源標籤附接至 Lambda 函數](#MultiDataSources-Connect-Custom-Lambda-tags) ## 使用範本 使用範本可建立範例 Lambda 函數，並協助您更快地建置自訂連接器。這些範例函數為建置自訂連接器所涉及的許多常見案例提供範例程式碼。可以在使用範本建立連接器之後檢查 Lambda 程式碼，然後修改它以用於連線至資料來源。 此外，如果使用範本，CloudWatch 會負責建立 Lambda 許可政策，並將資源標籤附接至 Lambda 函數。 **使用範本建立自訂資料來源的連接器** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇 ** Settings** (設定)。 1. 選擇**指標資料來源**索引標籤。 1. 選擇 **Create data source (建立資料來源)**。 1. 選擇**自訂 - 開始使用範本**的選項按鈕，然後選擇**下一步**。 1. 輸入資料來源的名稱。 1. 選取列出的其中一個範本。 1. 選擇 Node.js 或 Python。 1. 選擇 **Create data source (建立資料來源)**。 在 CloudFormation 堆疊完成建立之前，您剛新增的新自訂來源不會出現。若要檢查進度，您可以選擇**檢視我的 CloudFormation 堆疊的狀態**。或者，可以選擇重新整理圖示來更新此清單。 當新資料來源出現在此清單中時，就可以在主控台中進行測試並修改。 1. (選用) 若要在主控台中查詢來自此來源的測試資料，請遵循 [從另一個資料來源建立指標圖表](graph_a_metric.md#create-metric-graph-multidatasource) 中的指示。 1. 根據需求修改 Lambda 函數。 1. 在導覽窗格中，選擇**設定**。 1. 選擇**指標資料來源**索引標籤。 1. 針對您想要修改的來源，選擇**在 Lambda 主控台中檢視**。 您現在可以修改函數以存取資料來源。如需詳細資訊，請參閱[步驟 1：建立函數](#MultiDataSources-Connect-Custom-Lambda-Function)。 **注意** 透過使用範本，當您撰寫 Lambda 函數時，無需遵循 [步驟 2：建立 Lambda 許可政策](#MultiDataSources-Connect-Custom-Lambda-Permissions) 或 [步驟 3：將資源標籤附接至 Lambda 函數](#MultiDataSources-Connect-Custom-Lambda-tags) 中的指示。這些步驟由 CloudWatch 執行，因為您使用了範本。 ## 從頭開始建立自訂資料來源 請依照本節中的步驟來建立 Lambda 函數，它可將 CloudWatch 連線至資料來源。 ### 步驟 1：建立函數 自訂資料來源連接器必須支援來自 CloudWatch 的 `GetMetricData` 事件。也可以實作 `DescribeGetMetricData` 事件，在 CloudWatch 主控台中向使用者提供如何使用連接器的說明文件。`DescribeGetMetricData` 回應也可用來設定 CloudWatch 自訂查詢建置器中使用的預設值。 CloudWatch 提供程式碼片段作為範例，協助您快速入門。如需詳細資訊，請參閱範例儲存庫，網址為 [https://github.com/aws-samples/cloudwatch-data-source-samples](https://github.com/aws-samples/cloudwatch-data-source-samples)。 **限制條件** + 來自 Lambda 的回應必須小於 6 Mb。如果回應超過 6 Mb，則 `GetMetricData` 回應會將 Lambda 函數標記為 `InternalError`，且不會傳回任何資料。 + Lambda 函數必須在 10 秒內完成其執行，以達到視覺化和儀表板目的；或在 4.5 秒內完成執行，起到警示作用。如果執行時間超過該時間，則 `GetMetricData` 回應會將 Lambda 函數標記為 `InternalError`，且不會傳回任何資料。 + Lambda 函數必須使用 Epoch 時間戳記 (以秒為單位) 來傳送其輸出。 + 如果 Lambda 函數未重新取樣資料，而是傳回與 CloudWatch 使用者請求的開始時間和間隔長度不相符的資料，則 CloudWatch 會忽略該資料。會從任何視覺效果或警示中捨棄額外資料。任何非開始時間和結束時間之間的資料也會被捨棄。 例如，如果使用者需要間隔為 5 分鐘從上午 10 點到 11 點之間的資料，則傳回資料的有效時間範圍為「10:00:00 到 10:04:59」和「10:05:00 到 10:09:59」。必須傳回包含 `10:00 value1`、`10:05 value2` 等的時間序列。例如，如果函數傳回 `10:03 valueX`，它會被丟棄，因為 10:03 與請求的開始時間和間隔不符。 + CloudWatch 資料來源連接器不支援多行查詢。執行查詢時，或當您使用查詢建立警示或儀表板小工具時，每個換行符都會取代為空格。在某些情況下，這可能會使查詢無效。 #### GetMetricData 事件 **請求承載** 以下是作為 Lambda 函數的輸入而傳送的 `GetMetricData` 請求承載範例。 ``` { "EventType": "GetMetricData", "GetMetricDataRequest": { "StartTime": 1697060700, "EndTime": 1697061600, "Period": 300, "Arguments": ["serviceregistry_external_http_requests{host_cluster!=\"prod\"}"] } } ``` + **開始時間** – 指定要傳回之最早資料的時間戳記。**類型**是時間戳記 Epoch 秒。 + **結束時間** – 指定要傳回之最新資料的時間戳記。**類型**是時間戳記 Epoch 秒。 + **間隔** – 指標資料的每個彙總所代表的秒數。最小值為 60 秒。**類型**為秒。 + **引數** – 傳遞至 Lambda 指標數學運算式的引數陣列。如需有關傳遞引數的詳細資訊，請參閱 [如何將引數傳遞給 Lambda 函數](CloudWatch_MultiDataSources-Custom-Use.md#MultiDataSources-Connect-Custom-Lambda-arguments)。 **回應承載** 以下是 Lambda 函數傳回的 `GetMetricData` 回應承載範例。 ``` { "MetricDataResults": [ { "StatusCode": "Complete", "Label": "CPUUtilization", "Timestamps": [ 1697060700, 1697061000, 1697061300 ], "Values": [ 15000, 14000, 16000 ] } ] } ``` 回應承載將包含 `MetricDataResults` 欄位或 `Error` 欄位，但不能同時包含兩者。 `MetricDataResults` 欄位是一系列 `MetricDataResult` 類型的時間序列欄位。每個時間序列欄位可以包含下列欄位。 + **狀態碼** – (選用) `Complete` 表示傳回請求時間範圍內的所有資料點。`PartialData` 表示傳回一組不完整的資料點。若省略，則預設值為 `Complete`。 有效值：`Complete` \$1 `InternalError` \$1 `PartialData` \$1 `Forbidden` + **訊息** – 可選訊息清單，其中包含有關傳回資料的其他資訊。 類型：含有 `Code` 和 `Value` 字串的 [MessageData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MessageData.html) 物件陣列。 + **標籤** – 與資料相關聯的人類可讀標籤。 類型：字串 + **時間戳記** – 資料點的時間戳記，格式為 Epoch 時間。時間戳記的數目始終符合值的數目，而且 `Timestamps[x]` 的值為 `Values[x`]。 類型：時間戳記陣列 + **值** – 指標的資料點值，對應於 `Timestamps`。值的數目始終符合時間戳記的數目，而且 `Timestamps[x]` 的值為 `Values[x`]。 類型：雙精度陣列 如需有關 `Error` 物件的詳細資訊，請參閱下列各節。 **錯誤回應格式** 您可以選擇使用錯誤回應來提供有關錯誤的詳細資訊。建議您在發生驗證錯誤時傳回「程式碼驗證」錯誤，例如當參數遺失或類型錯誤時。 以下是 Lambda 函數想要引發 `GetMetricData` 驗證例外狀況時的回應範例。 ``` { "Error": { "Code": "Validation", "Value": "Invalid Prometheus cluster" } } ``` 以下是當 Lambda 函數指出由於存取問題而無法傳回資料時的回應範例。回應會轉譯成單一時間序列，且狀態碼為 `Forbidden`。 ``` { "Error": { "Code": "Forbidden", "Value": "Unable to access ..." } } ``` 以下是 Lambda 函數引發整體 `InternalError` 例外狀況時的範例，它會轉譯為單一時間序列，且具有狀態碼 `InternalError` 和訊息。每當錯誤代碼的值不是 `Validation` 或 `Forbidden` 時，CloudWatch 會假設它是一般性內部錯誤。 ``` { "Error": { "Code": "PrometheusClusterUnreachable", "Value": "Unable to communicate with the cluster" } } ``` #### DescribeGetMetricData 事件 **請求承載** 以下是 `DescribeGetMetricData` 請求承載的範例。 ``` { "EventType": "DescribeGetMetricData" } ``` **回應承載** 以下是 `DescribeGetMetricData` 回應承載的範例。 ``` { "Description": "Data source connector", "ArgumentDefaults": [{ Value: "default value" }] } ``` + **描述** – 如何使用資料來源連接器的描述。此描述將顯示在 CloudWatch 主控台中。支援 Markdown。 類型：字串 + **ArgumentDefaults** – 用於預先填入自訂資料來源建置器的可選引數預設值陣列。 如果傳回 `[{ Value: "default value 1"}, { Value: 10}]`，CloudWatch 主控台中的查詢建置器會顯示兩個輸入，第一個輸入具有「預設值 1」，第二個輸入的預設值為 10。 如果未提供 `ArgumentDefaults`，則會顯示單一輸入，且類型預設為 `String`。 類型：包含「值」和「類型」的物件陣列。 + **錯誤** – (選用) 錯誤欄位可包含在任何回應中。可在 [GetMetricData 事件](#MultiDataSources-GetMetricData) 中看到範例。 #### CloudWatch 警示的重要考量 如果要使用資料來源來設定 CloudWatch 警示，則應將其設定為每分鐘向 CloudWatch 報告具有時間戳記的資料。如需有關從連線的資料來源中建立指標警示的詳細資訊和其他考量，請參閱 [根據連線的資料來源建立警示](Create_MultiSource_Alarm.md)。 #### （選用） 使用 AWS Secrets Manager 存放登入資料 如果您的 Lambda 函數需要使用登入資料來存取資料來源，建議您使用 AWS Secrets Manager 來存放這些登入資料，而不是將它們硬式編碼到您的 Lambda 函數。如需搭配使用 AWS Secrets Manager 與 Lambda 的詳細資訊，請參閱[在 AWS Lambda 函數中使用 AWS Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets_lambda.html)。 #### (選用) 連線至 VPC 中的資料來源 如果資料來源位於 Amazon Virtual Private Cloud 所管理的 VPC 中，則必須設定 Lambda 函數才能存取它。如需詳細資訊，請參閱[將傳出網路連線至 VPC 中的資源](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html)。 可能還需要設定 VPC 服務端點，才能存取諸如 AWS Secrets Manager等服務。如需詳細資訊，請參閱[使用介面 VPC 端點存取 AWS 服務](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#access-service-though-endpoint)。 ### 步驟 2：建立 Lambda 許可政策 必須建立政策陳述式來授予 CloudWatch 許可，才能使用所建立的 Lambda 函數。您可以使用 AWS CLI 或 Lambda 主控台來建立政策陳述式。 **使用 AWS CLI 建立政策陳述式** + 輸入以下命令。將 *123456789012* 取代為您的帳戶 ID，將 *my-data-source-function* 取代為 Lambda 函數的名稱，並將 *MyDataSource-DataSourcePermission1234* 取代為任意唯一值。 ``` aws lambda add-permission --function-name my-data-source-function --statement-id MyDataSource-DataSourcePermission1234 --action lambda:InvokeFunction --principal lambda.datasource.cloudwatch.amazonaws.com --source-account 123456789012 ``` ### 步驟 3：將資源標籤附接至 Lambda 函數 CloudWatch 主控台透過使用標籤來判斷哪些 Lambda 函數是資料來源連接器。當您使用其中一個精靈建立資料來源時，設定它的 CloudFormation 堆疊會自動套用標籤。當您自行建立資料來源時，可以針對 Lambda 函數使用下列標籤。這會讓連接器在您查詢指標時出現在 CloudWatch 主控台的**資料來源**下拉式清單中。 + 索引鍵為 `cloudwatch:datasource` 和值為 `custom` 的標籤。