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

A operação `QueryMetrics` avalia uma consulta instantânea do PromQL em um único momento ou em um intervalo de tempo.

Verbos HTTP válidos:  
`GET`, `POST`

URIs válidos  
`/api/v1/query`: avalia uma consulta instantânea em um único momento.  
`/api/v1/query_range`: avalia uma consulta em um intervalo de tempo.

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/query`. 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-QueryMetrics-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 | 
| --- | --- | --- | 
| `query` | Ambos | Obrigatório. A string da expressão PromQL a ser avaliada. A expressão deve selecionar uma métrica pelo nome — por exemplo, `{"http.server.active_requests"}` ou `{__name__="http.server.active_requests"}`. A seleção de séries somente por rótulos, sem um nome de métrica, não é suportada. | 
| `time` | `/api/v1/query` | Opcional. Carimbo de data e hora de avaliação como carimbo de data e hora RFC 3339 ou Unix. O padrão é a hora atual do servidor. | 
| `start` | `/api/v1/query_range` | Obrigatório. Início do intervalo de tempo, como um carimbo de data e hora RFC 3339 ou Unix. | 
| `end` | `/api/v1/query_range` | Obrigatório. Fim do intervalo de tempo, como um carimbo de data e hora RFC 3339 ou Unix. | 
| `step` | `/api/v1/query_range` | Obrigatório. Largura da etapa de resolução da consulta em formato `duration` ou como número de segundos em ponto flutuante. | 
| `limit` | Ambos | Opcional. Número máximo de séries temporais exclusivas a serem retornadas, de `1` a `500`. Caso você não especifique `limit`, o CloudWatch retornará até o máximo (500). Consulte [Limite de resultados](#CloudWatch-PromQL-API-QueryMetrics-Limits). | 

**Duração**

A `duration` em uma API compatível com o Prometheus é um número, seguido imediatamente por uma das seguintes unidades:
+ `ms` milissegundos
+ `s` segundos
+ `m` minutos
+ `h` horas
+ `d` dias, supondo que um dia sempre tenha 24h
+ `w` semanas, supondo que uma semana sempre tenha 7 dias
+ `y` anos, supondo que um ano sempre tenha 365 dias

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

Para chamar `QueryMetrics`, a identidade de chamada deve ter as duas ações do IAM a seguir:
+ `cloudwatch:GetMetricData`
+ `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-QueryMetrics-Limits"></a>

Uma única resposta `/api/v1/query` ou `/api/v1/query_range` pode retornar até **500 séries temporais exclusivas**. Para solicitar menos resultados, passe o parâmetro `limit` com um valor de `1` para `500`. Caso você não especifique `limit`, o CloudWatch retornará até o máximo.

Quando as séries 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).

## Exemplo de solicitação
<a name="CloudWatch-PromQL-API-QueryMetrics-Sample"></a>

A solicitação `POST` a seguir passa a expressão PromQL em um corpo codificado em formulário. Caracteres especiais como `{`, `}` e `"` são codificados por porcentagem.

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

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

## Exemplo de resposta
<a name="CloudWatch-PromQL-API-QueryMetrics-Response"></a>

Uma resposta bem-sucedida usa o envelope JSON padrão do Prometheus:

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

Quando o conjunto de resultados excede o limite por chamada, o CloudWatch retorna uma matriz `result` truncada e inclui uma mensagem no campo `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"
    ]
}
```