# GetSeries
`GetSeries` オペレーションは、ラベルが 1 つまたは複数のセレクタと一致する時系列のリストを返します。
有効な HTTP 動詞
`GET`, `POST`
有効な URI
`/api/v1/series`
完全なリクエスト URL は、AWS リージョンの CloudWatch モニタリングホストを、`https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/series` などのオペレーションパスと組み合わせたものです。エンドポイント、署名、必要となる IAM アクセス許可については、「[PromQL クエリ](CloudWatch-PromQL-Querying.md)」を参照してください。
## URL クエリパラメータ
次のパラメータは、`GET` リクエストの URL クエリ文字列、または `POST` リクエストのフォームエンコードされた本文フィールドとして渡されます。
| パラメータ | 説明 |
| --- | --- |
| `match[]` | 必須。返す時系列をフィルタリングするシリーズセレクタ。各セレクタには、`{"http.server.active_requests"}` や `{__name__="http.server.active_requests"}` など、メトリクス名での完全一致 (`=`) を含める必要があります。メトリクス名の一致を含まないセレクタはサポートされていません。完全一致に加えて、ラベルマッチャーは、等しくない (`!=`)、正規表現一致 (`=~`)、正規表現一致の否定 (`!~`) もサポートしています。セレクタを組み合わせるには、`match[]` を 1 回または複数回指定します。セレクタ構文の詳細については、「[PromQL クエリ](CloudWatch-PromQL-Querying.md)」を参照してください。 |
| `start` | 必須。RFC 3339 タイムスタンプまたは Unix タイムスタンプとして考慮する時間範囲の開始。 |
| `end` | 必須。RFC 3339 タイムスタンプまたは Unix タイムスタンプとして考慮する時間範囲の終了。 |
| `limit` | オプション。返される一意の時系列の最大数 (`1` から `10000` まで)。`limit` を指定しない場合、CloudWatch は最大数 (10,000) まで返します。「[結果の制限](#CloudWatch-PromQL-API-GetSeries-Limits)」を参照してください。 |
## 必要な IAM 許可
`GetSeries` を呼び出すには、呼び出し元の ID に次の IAM アクションが必要です。
+ `cloudwatch:ListMetrics`
すべての PromQL オペレーションの完全な IAM アクションマッピングについては、「[PromQL の IAM アクセス許可](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)」を参照してください。
## 結果の制限
単一の `/api/v1/series` レスポンスで最大 **10,000 個の一意の時系列**を返すことができます。結果の個数を少なくするようにリクエストするには、`1` から `10000` の値で `limit` パラメータを渡します。`limit` を指定しない場合、CloudWatch は最大数を返します。
一致するシリーズが上限を超えると、レスポンスは打ち切られ、標準の Prometheus `warnings` フィールドにメッセージが含まれます。HTTP ステータスコードは `200` のままです。
TPS、同時実行数、24 時間スキャンウィンドウを含む PromQL 制限の完全なリストについては、「[PromQL の制限と規制](CloudWatch-PromQL.md#CloudWatch-PromQL-Limits)」を参照してください。
## リクエスト例
次の `POST` リクエストでは、完全一致セレクタを使用します。セレクタ、`start`、および `end` は、リクエスト本文のフォームエンコードされたフィールドとして渡されます。`{`、`}`、`"`、`,` などの特殊文字はパーセントエンコードされています。デコードされた `match[]` 値は `{"http.server.active_requests","@resource.service.name"="myservice"}` です。
```
POST /api/v1/series 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
match%5B%5D=%7B%22http.server.active_requests%22%2C%22%40resource.service.name%22%3D%22myservice%22%7D&start=1780662000&end=1780665600
```
次の `POST` リクエストでは、正規表現一致セレクタを使用します。デコードされた `match[]` 値は `{"http.server.active_requests","@aws.region"=~"us-.*"}` です。
```
POST /api/v1/series 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
match%5B%5D=%7B%22http.server.active_requests%22%2C%22%40aws.region%22%3D~%22us-.*%22%7D&start=1780662000&end=1780665600
```
同じ呼び出しに `awscurl` を使用:
```
awscurl --service monitoring --region us-east-1 \
-X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/series' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'match[]={"http.server.active_requests","@aws.region"=~"us-.*"}&start=1780662000&end=1780665600'
```
## レスポンス例
正常なレスポンスでは、標準の Prometheus JSON エンベロープが使用されます。`data` フィールドはラベルマップの配列で、一致する系列ごとに 1 つずつです。
```
HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Type: application/json
{
"status": "success",
"data": [
{
"__name__": "http.server.active_requests",
"@resource.service.name": "myservice",
"@aws.region": "us-east-1"
},
{
"__name__": "http.server.active_requests",
"@resource.service.name": "myservice",
"@aws.region": "us-west-2"
}
]
}
```