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

# QueryMetrics
<a name="CloudWatch-PromQL-API-QueryMetrics"></a>

`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 查詢](CloudWatch-PromQL-Querying.md)。

## URL 查詢參數
<a name="CloudWatch-PromQL-API-QueryMetrics-Parameters"></a>

下列參數會在`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)。請參閱 [結果限制](#CloudWatch-PromQL-API-QueryMetrics-Limits)。 | 

**Duration (持續時間)**

與 Prometheus 相容 API 的 `duration`，後續立即接著下列其中一個單位：
+ `ms` 毫秒
+ `s` 秒
+ `m` 分鐘
+ `h` 小時
+ `d` 天，假設一天總是 24 小時
+ `w` 週，假設一周總是 7 天
+ `y` 年，假設一年總是 365 天

## 所需的 IAM 許可
<a name="CloudWatch-PromQL-API-QueryMetrics-IAM"></a>

若要呼叫 `QueryMetrics`，呼叫身分必須具有下列兩個 IAM 動作：
+ `cloudwatch:GetMetricData`
+ `cloudwatch:ListMetrics`

如需所有 PromQL 操作的完整 IAM 動作映射，請參閱 [PromQL 的 IAM 許可](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)。

## 結果限制
<a name="CloudWatch-PromQL-API-QueryMetrics-Limits"></a>

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

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

如需 PromQL 限制的完整清單，包括 TPS、並行和 24 小時掃描時段，請參閱 [PromQL 限制](CloudWatch-PromQL.md#CloudWatch-PromQL-Limits)。

## 請求範例
<a name="CloudWatch-PromQL-API-QueryMetrics-Sample"></a>

下列`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"})'
```

## 回應範例
<a name="CloudWatch-PromQL-API-QueryMetrics-Response"></a>

成功的回應使用標準 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"
    ]
}
```