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

`GetLabels` 작업은 지표 저장소에 있는 레이블 이름을 반환하거나 특정 레이블 이름의 값을 반환합니다.

유효한 HTTP 동사  
`/api/v1/labels`의 경우 `GET`, `POST`입니다.  
`GET`(`/api/v1/label/{{label_name}}/values`일 때)

유효한 URI  
`/api/v1/labels` - 레이블 이름 목록을 반환합니다.  
`/api/v1/label/{{label_name}}/values` - 지정된 레이블에서 값 목록을 반환합니다.

전체 요청 URL은 AWS 리전의 CloudWatch 모니터링 호스트를 `https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/labels`와 같은 작업 경로와 결합합니다. 엔드포인트, 서명, 필수 IAM 권한에 대한 자세한 정보는 [PromQL 쿼리](CloudWatch-PromQL-Querying.md) 섹션을 참조하세요.

## URL 쿼리 파라미터
<a name="CloudWatch-PromQL-API-GetLabels-Parameters"></a>

다음 파라미터는 `GET` 요청의 경우 URL 쿼리 문자열로, `POST` 요청의 경우 양식 인코딩 본문 필드로 전달됩니다.


| 파라미터 | 적용 대상 | 설명 | 
| --- | --- | --- | 
| `match[]` | 둘 다 | 선택 사항. 결과를 계산할 때 고려할 시리즈를 제한하는 시리즈 선택기입니다. 선택기는 정확히 일치(`=`), 동일하지 않음(`!=`), 정규식 일치(`=~`) 및 부정 정규식 일치(`!~`)를 지원합니다. 선택기를 결합하려면 `match[]`를 한 번 이상 지정합니다. 선택기 구문에 대한 자세한 내용은 [PromQL 쿼리](CloudWatch-PromQL-Querying.md) 섹션을 참조하세요. | 
| `start` | 둘 다 | 선택 사항. RFC 3339 타임스탬프 또는 Unix 타임스탬프로 고려할 시간 범위의 시작입니다. | 
| `end` | 둘 다 | 선택 사항. RFC 3339 타임스탬프 또는 Unix 타임스탬프로 고려할 시간 범위의 종료입니다. | 
| `limit` | 둘 다 | 선택 사항. 반환할 최대 고유 레이블 수(`1`\~`10000`)입니다. `limit`를 지정하지 않으면 CloudWatch는 최대 수(10,000)까지 반환합니다. [결과 제한](#CloudWatch-PromQL-API-GetLabels-Limits)을(를) 참조하세요. | 

## 필수 IAM 권한
<a name="CloudWatch-PromQL-API-GetLabels-IAM"></a>

두 경로 중 하나에서 `GetLabels`를 호출하려면 호출 ID에 다음 IAM 작업이 있어야 합니다.
+ `cloudwatch:ListMetrics`

모든 PromQL 작업에 대한 전체 IAM 작업 매핑은 [PromQL에 대한 IAM 권한](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM) 섹션을 참조하세요.

## 결과 제한
<a name="CloudWatch-PromQL-API-GetLabels-Limits"></a>

단일 `/api/v1/labels` 또는 `/api/v1/label/{{label_name}}/values` 응답은 최대 **10,000개의 레이블**을 반환할 수 있습니다. 더 적은 결과를 요청하려면 값(`1`\~`10000`)이 있는 `limit` 파라미터를 전달합니다. `limit`를 지정하지 않으면 CloudWatch는 최대 수까지 반환합니다.

일치하는 레이블이 한도를 초과하면 응답이 잘리고 메시지가 표준 Prometheus `warnings` 필드에 포함됩니다. HTTP 상태 코드는 `200`으로 유지됩니다.

TPS, 동시성 및 24시간 스캔 기간을 포함한 PromQL 제한의 전체 목록은 [PromQL 한도 및 제한 사항](CloudWatch-PromQL.md#CloudWatch-PromQL-Limits) 섹션을 참조하세요.

## 샘플 요청
<a name="CloudWatch-PromQL-API-GetLabels-Sample"></a>

`POST` 요청과 빈 본문이 있는 모든 레이블 이름 나열:

```
POST /api/v1/labels HTTP/1.1
Host: monitoring.us-east-1.amazonaws.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 0
Authorization: AUTHPARAMS
X-Amz-Date: 20260605T193725Z
User-Agent: awscurl/0.36
```

`awscurl`과 동일한 호출:

```
awscurl --service monitoring --region us-east-1 \
    -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/labels' \
    -H 'Content-Type: application/x-www-form-urlencoded'
```

선택기와 일치하는 레이블 이름을 나열합니다. 선택기 및 시간 범위는 요청 본문에서 양식으로 인코딩된 필드로 전달됩니다.

```
awscurl --service monitoring --region us-east-1 \
    -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/labels' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'match[]={"http.server.active_requests","@aws.region"=~"us-.*"}&start=1780662000&end=1780665600'
```

`@resource.service.name` 레이블의 값을 나열합니다. 레이블 이름은 URL 경로의 일부이며 백분율로 인코딩됩니다(`@` → `%40`). 이 경로는 `GET`만 지원합니다.

```
GET /api/v1/label/%40resource.service.name/values HTTP/1.1
Host: monitoring.us-east-1.amazonaws.com
Authorization: AUTHPARAMS
X-Amz-Date: 20260605T193725Z
User-Agent: awscurl/0.36
```

`awscurl`과 동일한 호출:

```
awscurl --service monitoring --region us-east-1 \
    'https://monitoring.us-east-1.amazonaws.com/api/v1/label/@resource.service.name/values'
```

## 샘플 응답
<a name="CloudWatch-PromQL-API-GetLabels-Response"></a>

성공적인 응답은 표준 Prometheus JSON 봉투를 사용합니다. `data` 필드는 문자열의 배열입니다.

`/api/v1/labels`에 대한 응답:

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": [
        "__name__",
        "@aws.account",
        "@aws.region",
        "@resource.service.name",
        "@resource.cloud.region",
        "InstanceId"
    ]
}
```

`/api/v1/label/{{label_name}}/values`에 대한 응답:

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": [
        "myservice",
        "checkout-api",
        "billing-worker"
    ]
}
```