# GetSeries
`GetSeries` 작업은 레이블이 하나 이상의 선택기와 일치하는 시계열 목록을 반환합니다.
유효한 HTTP 동사
`GET`, `POST`
유효한 URI
`/api/v1/series`
전체 요청 URL은 AWS 리전의 CloudWatch 모니터링 호스트를 `https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/series`와 같은 작업 경로와 결합합니다. 엔드포인트, 서명, 필수 IAM 권한에 대한 자세한 정보는 [PromQL 쿼리](CloudWatch-PromQL-Querying.md) 섹션을 참조하세요.
## URL 쿼리 파라미터
다음 파라미터는 `GET` 요청의 경우 URL 쿼리 문자열로, `POST` 요청의 경우 양식 인코딩 본문 필드로 전달됩니다.
| 파라미터 | 설명 |
| --- | --- |
| `match[]` | 필수 사항입니다. 반환할 시계열을 필터링하는 시리즈 선택기입니다. 각 선택기에는 지표 이름에 `{"http.server.active_requests"}` 또는 `{__name__="http.server.active_requests"}`와 같은 정확한 일치(`=`)가 포함되어야 합니다. 지표 이름이 같은 매처가 없는 선택기는 지원되지 않습니다. 정확히 일치 외에도 레이블 메처는 동일하지 않음(`!=`), 정규식 일치(`=~`) 및 부정 정규식 일치(`!~`)를 지원합니다. 선택기를 결합하려면 `match[]`를 한 번 이상 지정합니다. 선택기 구문에 대한 자세한 내용은 [PromQL 쿼리](CloudWatch-PromQL-Querying.md) 섹션을 참조하세요. |
| `start` | 필수 사항입니다. RFC 3339 타임스탬프 또는 Unix 타임스탬프로 고려할 시간 범위의 시작입니다. |
| `end` | 필수 사항입니다. RFC 3339 타임스탬프 또는 Unix 타임스탬프로 고려할 시간 범위의 종료입니다. |
| `limit` | 선택 사항. 반환할 최대 고유 시계열 수(`1`\~`10000`)입니다. `limit`를 지정하지 않으면 CloudWatch는 최대 수(10,000)까지 반환합니다. [결과 제한](#CloudWatch-PromQL-API-GetSeries-Limits)을(를) 참조하세요. |
## 필수 IAM 권한
`GetSeries`를 호출하려면 호출 ID에 다음 IAM 작업이 있어야 합니다.
+ `cloudwatch:ListMetrics`
모든 PromQL 작업에 대한 전체 IAM 작업 매핑은 [PromQL에 대한 IAM 권한](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM) 섹션을 참조하세요.
## 결과 제한
단일 `/api/v1/series` 응답은 최대 **10,000개의 고유한 시계열**을 반환할 수 있습니다. 더 적은 결과를 요청하려면 값(`1`\~`10000`)이 있는 `limit` 파라미터를 전달합니다. `limit`를 지정하지 않으면 CloudWatch는 최대 수까지 반환합니다.
일치하는 시리즈가 한도를 초과하면 응답이 잘리고 메시지가 표준 Prometheus `warnings` 필드에 포함됩니다. HTTP 상태 코드는 `200`으로 유지됩니다.
TPS, 동시성 및 24시간 스캔 기간을 포함한 PromQL 제한의 전체 목록은 [PromQL 한도 및 제한 사항](CloudWatch-PromQL.md#CloudWatch-PromQL-Limits) 섹션을 참조하세요.
## 샘플 요청
다음 `POST` 요청은 정확한 일치 선택기를 사용합니다. 선택기, `start` 및 `end`는 요청 본문에서 양식 인코딩 필드로 전달됩니다. `{`, `}`, `"`, `,`와 같은 특수 문자는 백분율로 인코딩됩니다. 디코딩된 `match[]` 값은 `{"http.server.active_requests","@resource.service.name"="myservice"}`입니다.
```
POST /api/v1/series 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
match%5B%5D=%7B%22http.server.active_requests%22%2C%22%40resource.service.name%22%3D%22myservice%22%7D&start=1780662000&end=1780665600
```
다음 `POST` 요청은 정규식 일치 선택기를 사용합니다. 디코딩된 `match[]` 값은 `{"http.server.active_requests","@aws.region"=~"us-.*"}`입니다.
```
POST /api/v1/series 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
match%5B%5D=%7B%22http.server.active_requests%22%2C%22%40aws.region%22%3D~%22us-.*%22%7D&start=1780662000&end=1780665600
```
`awscurl`과 동일한 호출:
```
awscurl --service monitoring --region us-east-1 \
-X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/series' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'match[]={"http.server.active_requests","@aws.region"=~"us-.*"}&start=1780662000&end=1780665600'
```
## 샘플 응답
성공적인 응답은 표준 Prometheus JSON 봉투를 사용합니다. `data` 필드는 일치하는 시리즈당 하나씩의 레이블 맵 배열입니다.
```
HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Type: application/json
{
"status": "success",
"data": [
{
"__name__": "http.server.active_requests",
"@resource.service.name": "myservice",
"@aws.region": "us-east-1"
},
{
"__name__": "http.server.active_requests",
"@resource.service.name": "myservice",
"@aws.region": "us-west-2"
}
]
}
```