Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

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

Die `QueryMetrics` Operation wertet eine PromQL-Sofortabfrage zu einem bestimmten Zeitpunkt oder wertet eine Abfrage über einen bestimmten Zeitraum aus.

Gültige HTTP-Verben  
`GET`, `POST`

Gültige URIs  
`/api/v1/query`— wertet eine Sofortabfrage zu einem einzigen Zeitpunkt aus.  
`/api/v1/query_range`— wertet eine Abfrage über einen bestimmten Zeitraum aus.

Die vollständige Anfrage-URL kombiniert beispielsweise `https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/query` den CloudWatch Überwachungshost für die AWS Region mit dem Operationspfad. Informationen zu Endpunkten, Signierung und erforderlichen IAM-Berechtigungen finden Sie unter. [PromQL abfragen](CloudWatch-PromQL-Querying.md)

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

Die folgenden Parameter werden in der URL-Abfragezeichenfolge für `GET` Anfragen oder als formularkodierte Textfelder für Anfragen übergeben. `POST`


| Parameter | Gilt für | Description | 
| --- | --- | --- | 
| `query` | beides | Erforderlich Die auszuwertende PromQL-Ausdruckszeichenfolge. Der Ausdruck muss eine Metrik anhand des Namens auswählen — zum Beispiel `{"http.server.active_requests"}` oder. `{__name__="http.server.active_requests"}` Die Auswahl von Datenreihen nur anhand von Labels ohne Metriknamen wird nicht unterstützt. | 
| `time` | `/api/v1/query` | Optional. Testzeitstempel als RFC 3339-Zeitstempel oder Unix-Zeitstempel. Standardmäßig wird die aktuelle Serverzeit verwendet. | 
| `start` | `/api/v1/query_range` | Erforderlich Beginn des Zeitbereichs, als RFC 3339-Zeitstempel oder Unix-Zeitstempel. | 
| `end` | `/api/v1/query_range` | Erforderlich Ende des Zeitbereichs, als RFC 3339-Zeitstempel oder Unix-Zeitstempel. | 
| `step` | `/api/v1/query_range` | Erforderlich Schrittweite der Abfrageauflösung, im `duration` Format oder als Gleitkommazahl in Sekunden. | 
| `limit` | beides | Optional. Maximale Anzahl eindeutiger Zeitreihen, die zurückgegeben werden sollen, von bis. `1` `500` Wenn Sie nichts angeben`limit`, wird bis zum Maximum (500) CloudWatch zurückgegeben. Siehe [Limit für Ergebnisse](#CloudWatch-PromQL-API-QueryMetrics-Limits). | 

**Duration (Dauer)**

A `duration` in einer Prometheus-compatible API ist eine Zahl, unmittelbar gefolgt von einer der folgenden Einheiten:
+ `ms` Millisekunden
+ `s` Sekunden
+ `m` Minuten
+ `h` Stunden
+ `d` Tage, vorausgesetzt, ein Tag hat immer 24 Stunden
+ `w` Wochen, vorausgesetzt, eine Woche hat immer 7 Tage
+ `y` Jahre, vorausgesetzt, ein Jahr hat immer 365 Tage

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

Um aufzurufen`QueryMetrics`, muss die aufrufende Identität über die beiden folgenden IAM-Aktionen verfügen:
+ `cloudwatch:GetMetricData`
+ `cloudwatch:ListMetrics`

Die vollständige IAM-Aktionszuordnung für alle PromQL-Operationen finden Sie unter. [IAM-Berechtigungen für PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)

## Limit für Ergebnisse
<a name="CloudWatch-PromQL-API-QueryMetrics-Limits"></a>

Eine einzelne `/api/v1/query_range` Antwort `/api/v1/query` oder Antwort kann bis zu **500 eindeutige Zeitreihen** zurückgeben. Um weniger Ergebnisse anzufordern, übergeben Sie den `limit` Parameter mit einem Wert von `1` bis`500`. Wenn Sie nichts angeben`limit`, wird bis zum Maximum CloudWatch zurückgegeben.

Wenn die übereinstimmende Serie die Obergrenze überschreitet, wird die Antwort gekürzt und eine Nachricht in das `warnings` Prometheus-Standardfeld aufgenommen. Der HTTP-Statuscode bleibt bestehen. `200`

Die vollständige Liste der PromQL-Grenzwerte, einschließlich TPS, Parallelität und 24-Stunden-Scanfenster, finden Sie unter. [Grenzen und Einschränkungen von PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-Limits)

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

Die folgende `POST` Anfrage übergibt den PromQL-Ausdruck in einem formularcodierten Text. Sonderzeichen wie, und sind `{` prozentkodiert`}`. `"`

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

Derselbe Anruf mit: `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"})'
```

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

Eine erfolgreiche Antwort verwendet den standardmäßigen Prometheus-JSON-Umschlag:

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

Wenn die Ergebnismenge die Obergrenze pro Anruf überschreitet, wird ein abgeschnittenes `result` Array CloudWatch zurückgegeben und eine Nachricht in das Feld aufgenommen: `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"
    ]
}
```