# GetLabels
`GetLabels` オペレーションは、メトリクスストアに存在するラベル名、または特定のラベル名の値を返します。
有効な HTTP 動詞
`/api/v1/labels` の場合は `GET`、`POST`。
`/api/v1/label/{{label_name}}/values` 用の `GET`。
有効な URI:
`/api/v1/labels` — ラベル名のリストを返します。
`/api/v1/label/{{label_name}}/values` — 指定されたラベルの値のリストを返します。
完全なリクエスト URL は、AWS リージョンの CloudWatch モニタリングホストを、`https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/labels` などのオペレーションパスと組み合わせたものです。エンドポイント、署名、必要となる IAM アクセス許可については、「[PromQL クエリ](CloudWatch-PromQL-Querying.md)」を参照してください。
## URL クエリパラメータ
次のパラメータは、`GET` リクエストの URL クエリ文字列、または `POST` リクエストのフォームエンコードされた本文フィールドとして渡されます。
| パラメータ | 適用対象 | 説明 |
| --- | --- | --- |
| `match[]` | [Both] (両方) | オプション。結果の計算時に考慮されるシリーズを制限するシリーズセレクタ。セレクタは、完全一致 (`=`)、等しくない (`!=`)、正規表現一致 (`=~`)、正規表現一致の否定 (`!~`) をサポートします。セレクタを組み合わせるには、`match[]` を 1 回または複数回指定します。セレクタ構文の詳細については、「[PromQL クエリ](CloudWatch-PromQL-Querying.md)」を参照してください。 |
| `start` | [Both] (両方) | オプション。RFC 3339 タイムスタンプまたは Unix タイムスタンプとして考慮する時間範囲の開始。 |
| `end` | [Both] (両方) | オプション。RFC 3339 タイムスタンプまたは Unix タイムスタンプとして考慮する時間範囲の終了。 |
| `limit` | [Both] (両方) | オプション。`1` から `10000` までの返される一意のラベルの最大数。`limit` を指定しない場合、CloudWatch は最大数 (10,000) まで返します。「[結果の制限](#CloudWatch-PromQL-API-GetLabels-Limits)」を参照してください。 |
## 必要な IAM 許可
いずれかのパスで `GetLabels` を呼び出すには、呼び出し元の ID に次の IAM アクションが必要です。
+ `cloudwatch:ListMetrics`
すべての PromQL オペレーションの完全な IAM アクションマッピングについては、「[PromQL の IAM アクセス許可](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)」を参照してください。
## 結果の制限
単一の `/api/v1/labels` または `/api/v1/label/{{label_name}}/values` レスポンスは、最大 **10,000 個のラベル**を返すことができます。結果の個数を少なくするようにリクエストするには、`1` から `10000` の値で `limit` パラメータを渡します。`limit` を指定しない場合、CloudWatch は最大数を返します。
一致するラベルが上限を超えると、レスポンスは打ち切られ、標準の Prometheus `warnings` フィールドにメッセージが含まれます。HTTP ステータスコードは `200` のままです。
TPS、同時実行数、24 時間スキャンウィンドウを含む PromQL 制限の完全なリストについては、「[PromQL の制限と規制](CloudWatch-PromQL.md#CloudWatch-PromQL-Limits)」を参照してください。
## リクエスト例
`POST` リクエストと空の本文を持つすべてのラベル名を一覧表示します。
```
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
```
同じ呼び出しに `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'
```
セレクタに一致するラベル名を一覧表示します。セレクタと時間範囲は、リクエスト本文のフォームエンコードされたフィールドとして次のように渡されます。
```
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'
```
`@resource.service.name` ラベルの値を一覧表示します。ラベル名は URL パスの一部であり、パーセントエンコードされています (`@` → `%40`)。このパスは `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
```
同じ呼び出しに `awscurl` を使用:
```
awscurl --service monitoring --region us-east-1 \
'https://monitoring.us-east-1.amazonaws.com/api/v1/label/@resource.service.name/values'
```
## レスポンス例
正常なレスポンスでは、標準の Prometheus JSON エンベロープが使用されます。`data` フィールドは文字列の配列です。
`/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"
]
}
```
`/api/v1/label/{{label_name}}/values` のレスポンス:
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "success",
"data": [
"myservice",
"checkout-api",
"billing-worker"
]
}
```