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

A operação `GetLabels` retorna os nomes de rótulos que estão presentes no armazenamento de métricas ou retorna os valores de um nome de rótulo específico.

Verbos HTTP válidos:  
`GET`, `POST` para `/api/v1/labels`.  
`GET` para `/api/v1/label/{{label_name}}/values`.

URIs válidos  
`/api/v1/labels`: retorna uma lista de nomes de rótulos.  
`/api/v1/label/{{label_name}}/values`: retorna uma lista de valores para o rótulo especificado.

O URL completo da solicitação combina o host de monitoramento do CloudWatch para a região da AWS com o caminho da operação, por exemplo `https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/labels`. Para obter mais informações sobre endpoints, assinaturas e as permissões necessárias do IAM, consulte [Consultas do PromQL](CloudWatch-PromQL-Querying.md).

## Parâmetros da consulta de URL
<a name="CloudWatch-PromQL-API-GetLabels-Parameters"></a>

Os parâmetros a seguir são transmitidos na string de consulta de URL para solicitações `GET` ou como campos de corpo codificados em formulário para solicitações `POST`.


| Parâmetro | Aplica-se a | Descrição | 
| --- | --- | --- | 
| `match[]` | Ambos | Opcional. Um seletor de séries que restringe quais séries são consideradas ao calcular o resultado. Seletores compatíveis com correspondência exata (`=`), não igual (`!=`), correspondência regex (`=~`) e correspondência regex negativa (`!~`). Especifique `match[]` uma ou mais vezes para combinar seletores. Para mais informações sobre sintaxe de seletores, consulte [Consultas do PromQL](CloudWatch-PromQL-Querying.md). | 
| `start` | Ambos | Opcional. Início do intervalo de tempo a ser considerado, como um carimbo de data e hora RFC 3339 ou Unix. | 
| `end` | Ambos | Opcional. Fim do intervalo de tempo a ser considerado, como um carimbo de data e hora RFC 3339 ou Unix. | 
| `limit` | Ambos | Opcional. Número máximo de rótulos exclusivos a serem retornados, de `1` a `10000`. Caso você não especifique `limit`, o CloudWatch retornará até o máximo (10.000). Consulte [Limite de resultados](#CloudWatch-PromQL-API-GetLabels-Limits). | 

## Permissões obrigatórias do IAM
<a name="CloudWatch-PromQL-API-GetLabels-IAM"></a>

Para chamar `GetLabels` em qualquer um dos caminhos, a identidade da chamada deve ter a seguinte ação do IAM:
+ `cloudwatch:ListMetrics`

Para obter o mapeamento completo das ações do IAM para todas as operações do PromQL, consulte [Permissões do IAM para o PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM).

## Limite de resultados
<a name="CloudWatch-PromQL-API-GetLabels-Limits"></a>

Uma única resposta `/api/v1/labels` ou `/api/v1/label/{{label_name}}/values` pode retornar até **10.000 rótulos**. Para solicitar menos resultados, passe o parâmetro `limit` com um valor de `1` para `10000`. Caso você não especifique `limit`, o CloudWatch retornará até o máximo.

Quando os rótulos correspondentes excedem o limite, a resposta é truncada e uma mensagem é incluída no campo `warnings` padrão do Prometheus. O código de status do HTTP permanece em `200`.

Para obter a lista completa dos limites do PromQL, incluindo TPS, simultaneidade e janelas de verificação de 24 horas, consulte [Limites e restrições do PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-Limits).

## Amostra de solicitações
<a name="CloudWatch-PromQL-API-GetLabels-Sample"></a>

Liste todos os nomes de etiquetas com uma solicitação `POST` e um corpo vazio:

```
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
```

A mesma chamada com `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'
```

Liste os nomes dos rótulos que correspondem a um seletor. O seletor e o intervalo de tempo são passados como campos codificados no formulário no corpo da solicitação:

```
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'
```

Liste os valores do rótulo `@resource.service.name`. O nome do rótulo faz parte do caminho do URL e é codificado por porcentagem (`@` → `%40`). Esse caminho suporta somente `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
```

A mesma chamada com `awscurl`:

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

## Exemplo de respostas
<a name="CloudWatch-PromQL-API-GetLabels-Response"></a>

Uma resposta bem-sucedida usa o envelope JSON padrão do Prometheus. O campo `data` é uma matriz de strings.

Resposta 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"
    ]
}
```

Resposta para `/api/v1/label/{{label_name}}/values`:

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

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