View a markdown version of this page

QueryMetrics - Amazon CloudWatch
URL 查詢參數所需的 IAM 許可結果限制請求範例回應範例

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

QueryMetrics

QueryMetrics 操作會在單一時間點評估 PromQL 即時查詢，或在一段時間內評估查詢。

有效的 HTTP 動詞

GET, POST

有效的 URIs

/api/v1/query — 會在單一時間點評估即時查詢。

/api/v1/query_range — 評估一段時間內的查詢。

完整的請求 URL 結合了 AWS 區域的 CloudWatch 監控主機與操作路徑，例如 https://monitoring.AWS Region.amazonaws.com/api/v1/query。如需端點、簽署和必要 IAM 許可的資訊，請參閱 PromQL 查詢。

URL 查詢參數

下列參數會在GET請求的 URL 查詢字串中傳遞，或做為POST請求的表單編碼內文欄位傳遞。

參數 適用對象 說明

query

兩者

必要. 要評估的 PromQL 表達式字串。表達式必須依名稱選取指標，例如 {"http.server.active_requests"}或 {__name__="http.server.active_requests"}。不支援僅透過沒有指標名稱的標籤選取序列。

time

/api/v1/query

選用。RFC 3339 時間戳記或 Unix 時間戳記的評估時間戳記。預設為目前的伺服器時間。

start

/api/v1/query_range

必要. 時間範圍的開始，以 RFC 3339 時間戳記或 Unix 時間戳記表示。

end

/api/v1/query_range

必要. 時間範圍結束，以 RFC 3339 時間戳記或 Unix 時間戳記表示。

step

/api/v1/query_range

必要. 查詢解析步驟寬度，duration格式或浮點數秒數。

limit

兩者

選用。要傳回的唯一時間序列數目上限，從 1到 500。如果您未指定 limit，CloudWatch 會傳回上限 (500)。請參閱 結果限制。

Duration (持續時間)

與 Prometheus 相容 API 的 duration，後續立即接著下列其中一個單位：

  • ms 毫秒

  • s 秒

  • m 分鐘

  • h 小時

  • d 天，假設一天總是 24 小時

  • w 週，假設一周總是 7 天

  • y 年，假設一年總是 365 天

所需的 IAM 許可

若要呼叫 QueryMetrics，呼叫身分必須具有下列兩個 IAM 動作：

  • cloudwatch:GetMetricData

  • cloudwatch:ListMetrics

如需所有 PromQL 操作的完整 IAM 動作映射，請參閱 PromQL 的 IAM 許可。

結果限制

單一 /api/v1/query 或 /api/v1/query_range回應最多可傳回 500 個唯一的時間序列。若要請求較少的結果，請將具有 值的 limit 參數傳遞1至 500。如果您未指定 limit，CloudWatch 最多會傳回 上限。

當相符的序列超過上限時，回應會截斷，並在標準 Prometheus warnings欄位中包含訊息。HTTP 狀態碼保持 200。

如需 PromQL 限制的完整清單，包括 TPS、並行和 24 小時掃描時段，請參閱 PromQL 限制。

請求範例

下列POST請求會以形式編碼的內文傳遞 PromQL 表達式。特殊字元，例如 {、 }和 "以百分比編碼。

POST /api/v1/query HTTP/1.1
Host: monitoring.us-east-1.amazonaws.com
Content-Type: application/x-www-form-urlencoded
Authorization: AUTHPARAMS
X-Amz-Date: 20260605T193725Z
User-Agent: awscurl/0.36

query=sum(%7B%22http.server.active_requests%22%7D)

與 的相同呼叫awscurl：

awscurl --service monitoring --region us-east-1 \
    -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/query' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'query=sum({"http.server.active_requests"})'

回應範例

成功的回應使用標準 Prometheus JSON 信封：

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Type: application/json

{
    "status": "success",
    "data": {
        "resultType": "vector",
        "result": [
            {
                "metric": {},
                "value": [
                    1780000000.000,
                    "42"
                ]
            }
        ]
    }
}

當結果集超過每次呼叫上限時，CloudWatch 會傳回截斷的result陣列，並在 warnings 欄位中包含訊息：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "resultType": "vector",
        "result": [ ... up to 500 series ... ]
    },
    "warnings": [
        "result truncated to the maximum of 500 series; refine the query or use the limit parameter"
    ]
}