# GetLabels
La operación `GetLabels` devuelve los nombres de etiquetas que están presentes en el almacén de métricas o devuelve los valores de un nombre de etiqueta específico.
Verbos HTTP válidos
`GET`, `POST` para `/api/v1/labels`
`GET` para `/api/v1/label/{{label_name}}/values`.
URI válidos
`/api/v1/labels`: devuelve la lista de nombres de etiquetas.
`/api/v1/label/{{label_name}}/values`: devuelve la lista de valores de etiquetas para la etiqueta especificada.
La URL de solicitud completa combina el host de supervisión de CloudWatch de la región de AWS con la ruta de operación, por ejemplo, `https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/labels`. Para obtener más información sobre los puntos de conexión, la firma y los permisos de IAM necesarios, consulte [Consultas PromQL](CloudWatch-PromQL-Querying.md).
## Parámetros de consulta de URL
Los siguientes parámetros se pasan en la cadena de consulta de la URL para las solicitudes `GET` o como campos de cuerpo codificados como formulario para las solicitudes `POST`.
| Parámetro | Aplica a | Descripción |
| --- | --- | --- |
| `match[]` | Ambos | Opcional. Un selector de serie que restringe las series que se tienen en cuenta al calcular el resultado. Los selectores admiten coincidencia exacta (`=`), distinto de (`!=`), coincidencia de expresión regular (`=~`) y coincidencia de expresión regular negativa (`!~`). Especifique `match[]` una o más veces para combinar los selectores. Para obtener más información sobre la sintaxis de los selectores, consulte [Consultas PromQL](CloudWatch-PromQL-Querying.md). |
| `start` | Ambos | Opcional. Inicio del intervalo de tiempo que se debe tener en cuenta, como una marca de tiempo RFC 3339 o una marca de tiempo de Unix. |
| `end` | Ambos | Opcional. Final del intervalo de tiempo que se debe tener en cuenta, como una marca de tiempo RFC 3339 o una marca de tiempo de Unix. |
| `limit` | Ambos | Opcional. Número máximo de etiquetas únicas que se devolverán, de `1` a `10000`. Si no especifica `limit`, CloudWatch devuelve el máximo (10 000). Consulte [Límite de resultados](#CloudWatch-PromQL-API-GetLabels-Limits). |
## Permisos de IAM necesarios
Para llamar a `GetLabels` en cualquier ruta, la identidad que hace la llamada debe tener la siguiente acción de IAM:
+ `cloudwatch:ListMetrics`
Para ver la asignación completa de acciones de IAM para todas las operaciones de PromQL, consulte [Permisos de IAM para PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM).
## Límite de resultados
Una sola respuesta `/api/v1/labels` o `/api/v1/label/{{label_name}}/values` puede devolver hasta **10 000 etiquetas**. Para solicitar menos resultados, pase el parámetro `limit` con un valor comprendido entre `1` y `10000`. Si no especifica `limit`, CloudWatch devuelve el máximo.
Cuando las etiquetas coincidentes superan el límite, la respuesta se trunca y se incluye un mensaje en el campo `warnings` de Prometheus estándar. El código de estado HTTP continúa siendo `200`.
Para ver la lista completa de los límites de PromQL, incluidos el TPS, la simultaneidad y los periodos de escaneo de 24 horas, consulte [Límites y restricciones de PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-Limits).
## Solicitudes de ejemplo
Enumere todos los nombres de etiqueta con una solicitud `POST` y un cuerpo vacío:
```
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
```
La misma llamada con `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'
```
Enumere los nombres de etiqueta que coincidan con un selector. El selector y el intervalo de tiempo se pasan como campos codificados como formulario en el cuerpo de la solicitud:
```
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'
```
Enumere los valores de la etiqueta `@resource.service.name`. El nombre de la etiqueta forma parte de la ruta de la URL y está codificado como porcentaje (`@` → `%40`). Esta ruta solo admite `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
```
La misma llamada con `awscurl`:
```
awscurl --service monitoring --region us-east-1 \
'https://monitoring.us-east-1.amazonaws.com/api/v1/label/@resource.service.name/values'
```
## Respuestas de ejemplo
Una respuesta correcta utiliza el sobre JSON estándar de Prometheus. El campo `data` es una matriz de cadenas.
Respuesta para `/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"
]
}
```
Respuesta para `/api/v1/label/{{label_name}}/values`:
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "success",
"data": [
"myservice",
"checkout-api",
"billing-worker"
]
}
```