# 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)을(를) 참조하세요. | 

**지속 시간**

Prometheus 호환 API의 `duration`은 숫자이며, 그 뒤에 바로 다음 단위 중 하나가 따라옵니다.
+ `ms`밀리초
+ `s`초
+ `m`분
+ `h`시간
+ `d`일(항상 하루를 24시간으로 가정)
+ `w`주(항상 한 주를 7일로 가정)
+ `y`년(항상 1년을 365일로 가정)

## 필수 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"
    ]
}
```