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

`QueryMetrics` 操作会在单个时间点评估 PromQL 即时查询，或在一段时间范围内评估查询。

有效的 HTTP 动词  
`GET`, `POST`

有效的 URI  
`/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"
    ]
}
```