Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

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

`QueryMetrics`Operasi mengevaluasi kueri instan PromQL pada satu titik waktu, atau mengevaluasi kueri selama rentang waktu.

Kata kerja HTTP yang valid  
`GET`, `POST`

URI yang valid  
`/api/v1/query`— mengevaluasi kueri instan pada satu titik waktu.  
`/api/v1/query_range`— mengevaluasi kueri selama rentang waktu.

URL permintaan lengkap menggabungkan host CloudWatch pemantauan untuk AWS Wilayah dengan jalur operasi, misalnya`https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/query`. Untuk informasi tentang titik akhir, penandatanganan, dan izin IAM yang diperlukan, lihat. [Kueri PromQL](CloudWatch-PromQL-Querying.md)

## Parameter kueri URL
<a name="CloudWatch-PromQL-API-QueryMetrics-Parameters"></a>

Parameter berikut diteruskan dalam string kueri URL untuk `GET` permintaan, atau sebagai bidang isi yang dikodekan formulir untuk permintaan. `POST`


| Parameter | Berlaku untuk | Deskripsi | 
| --- | --- | --- | 
| `query` | Keduanya | Wajib. String ekspresi promQL untuk mengevaluasi. Ekspresi harus memilih metrik dengan nama — misalnya, `{"http.server.active_requests"}` atau`{__name__="http.server.active_requests"}`. Memilih seri hanya dengan label, tanpa nama metrik, tidak didukung. | 
| `time` | `/api/v1/query` | Tidak wajib. Stempel waktu evaluasi sebagai stempel waktu RFC 3339 atau stempel waktu Unix. Default ke waktu server saat ini. | 
| `start` | `/api/v1/query_range` | Wajib. Mulai dari rentang waktu, sebagai stempel waktu RFC 3339 atau stempel waktu Unix. | 
| `end` | `/api/v1/query_range` | Wajib. Akhir rentang waktu, sebagai stempel waktu RFC 3339 atau stempel waktu Unix. | 
| `step` | `/api/v1/query_range` | Wajib. Lebar langkah resolusi kueri, dalam `duration` format atau sebagai jumlah detik floating-point. | 
| `limit` | Keduanya | Tidak wajib. Jumlah maksimum deret waktu unik untuk dikembalikan, dari `1` ke`500`. Jika Anda tidak menentukan`limit`, CloudWatch kembali hingga maksimum (500). Lihat [Batas hasil](#CloudWatch-PromQL-API-QueryMetrics-Limits). | 

**Durasi**

A `duration` dalam Prometheus-compatible API adalah angka, diikuti langsung oleh salah satu unit berikut:
+ `ms`milidetik
+ `s` detik
+ `m`menit
+ `h` jam
+ `d`hari, dengan asumsi sehari selalu memiliki 24 jam
+ `w`minggu, dengan asumsi seminggu selalu memiliki 7d
+ `y`tahun, dengan asumsi satu tahun selalu memiliki 365d

## Izin IAM yang diperlukan
<a name="CloudWatch-PromQL-API-QueryMetrics-IAM"></a>

Untuk menelepon`QueryMetrics`, identitas panggilan harus memiliki kedua tindakan IAM berikut:
+ `cloudwatch:GetMetricData`
+ `cloudwatch:ListMetrics`

Untuk pemetaan tindakan IAM lengkap untuk semua operasi PromQL, lihat. [Izin IAM untuk PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)

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

Satu `/api/v1/query` atau `/api/v1/query_range` respons dapat mengembalikan hingga **500 deret waktu unik**. Untuk meminta hasil yang lebih sedikit, berikan `limit` parameter dengan nilai dari `1` ke`500`. Jika Anda tidak menentukan`limit`, CloudWatch kembali hingga maksimum.

Ketika seri yang cocok melebihi batas, respons terpotong dan pesan disertakan dalam bidang Prometheus standar. `warnings` Kode status HTTP tetap ada`200`.

Untuk daftar lengkap batas PromQL, termasuk TPS, konkurensi, dan jendela pemindaian 24 jam, lihat. [Batas dan batasan PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-Limits)

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

`POST`Permintaan berikut meneruskan ekspresi promQL dalam badan yang dikodekan formulir. Karakter khusus seperti`{`,`}`, dan `"` dikodekan persen.

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

Panggilan yang sama dengan`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"})'
```

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

Respons yang berhasil menggunakan amplop Prometheus JSON standar:

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

Ketika set hasil melebihi batas per panggilan, CloudWatch mengembalikan `result` array terpotong dan menyertakan pesan di bidang: `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"
    ]
}
```