# 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` | [Both] (両方) | 必須。評価する 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` | [Both] (両方) | オプション。返される一意の時系列の最大数 (`1` から `500` まで)。`limit` を指定しない場合、CloudWatch は最大 (500) まで返します。「[結果の制限](#CloudWatch-PromQL-API-QueryMetrics-Limits)」を参照してください。 | 

**duration**

Prometheus 互換 API の `duration` には、数値に続けて以下の単位のいずれかを指定します。
+ `ms` ミリ秒
+ `s` 秒
+ `m` 分
+ `h` 時間
+ `d` 日 (1 日は常に 24h と想定)
+ `w` 週 (1 週間は常に 7d と想定)
+ `y` 年 (1 年は常に 365d と想定)

## 必要な IAM 許可
<a name="CloudWatch-PromQL-API-QueryMetrics-IAM"></a>

`QueryMetrics` を呼び出すには、呼び出し元の ID に次の 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 個の一意の時系列**を返すことができます。結果の個数を少なくするようにリクエストするには、`1` から `500` の値で `limit` パラメータを渡します。`limit` を指定しない場合、CloudWatch は最大数を返します。

一致するシリーズが上限を超えると、レスポンスは打ち切られ、標準の Prometheus `warnings` フィールドにメッセージが含まれます。HTTP ステータスコードは `200` のままです。

TPS、同時実行数、24 時間スキャンウィンドウを含む PromQL 制限の完全なリストについては、「[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"
    ]
}
```