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

`GetLabels` 操作会返回指标存储中存在的标签名称，或返回特定标签名称的值。

有效的 HTTP 动词  
`GET`、`POST`（对于 `/api/v1/labels`）。  
用于 `/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 查询参数
<a name="CloudWatch-PromQL-API-GetLabels-Parameters"></a>

以下参数在 `GET` 请求的 URL 查询字符串中传递，或在 `POST` 请求中作为表单编码的请求体字段传递。


| 参数 | 适用于 | 说明 | 
| --- | --- | --- | 
| `match[]` | 二者 | 可选。一个序列选择器，用于限制在计算结果时要考虑的序列。选择器支持精确匹配 (`=`)、不等于 (`!=`)、正则表达式匹配 (`=~`) 和正则表达式否定匹配 (`!~`)。可以一次或多次指定 `match[]` 来组合选择器。有关选择器语法的更多信息，请参阅 [PromQL 查询](CloudWatch-PromQL-Querying.md)。 | 
| `start` | 二者 | 可选。要考虑的时间范围的开始时间，格式为 RFC 3339 时间戳或 Unix 时间戳。 | 
| `end` | 二者 | 可选。要考虑的时间范围的结束时间，格式为 RFC 3339 时间戳或 Unix 时间戳。 | 
| `limit` | 二者 | 可选。要返回的唯一标签的数量上限，范围为 `1` 到 `10000`。如果未指定 `limit`，CloudWatch 将返回数量上限（10,000）。请参阅[结果限制](#CloudWatch-PromQL-API-GetLabels-Limits)。 | 

## 所需的 IAM 权限
<a name="CloudWatch-PromQL-API-GetLabels-IAM"></a>

要在任一路径上调用 `GetLabels`，调用身份必须具有以下 IAM 操作：
+ `cloudwatch:ListMetrics`

有关所有 PromQL 操作的完整 IAM 操作映射，请参阅 [PromQL的 IAM 权限](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)。

## 结果限制
<a name="CloudWatch-PromQL-API-GetLabels-Limits"></a>

单个 `/api/v1/labels` 或 `/api/v1/label/{{label_name}}/values` 响应最多可以返回 **10,000 个标签**。要请求更少的结果，请传递 `limit` 参数，其值范围为 `1` 到 `10000`。如果未指定 `limit`，CloudWatch 会返回数量上限。

如果匹配的标签超出上限，响应会被截断，并在标准的 Prometheus `warnings` 字段中包含一条消息。HTTP 状态码保持为 `200`。

有关 PromQL 限制的完整列表，包括 TPS、并发和 24 小时扫描窗口，请参阅 [PromQL 限额和限制](CloudWatch-PromQL.md#CloudWatch-PromQL-Limits)。

## 示例请求
<a name="CloudWatch-PromQL-API-GetLabels-Sample"></a>

使用 `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'
```

## 示例响应
<a name="CloudWatch-PromQL-API-GetLabels-Response"></a>

成功的响应使用标准的 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"
    ]
}
```