本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

`GetLabels` 操作會傳回指標存放區中存在的標籤名稱，或傳回特定標籤名稱的值。

有效的 HTTP 動詞  
`GET`，`POST`適用於 `/api/v1/labels`。  
`GET` 適用於 `/api/v1/label/{{label_name}}/values`。

有效的 URIs  
`/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[]` | 兩者 | 選用。序列選取器，可限制運算結果時要考慮的序列。選取器支援完全相符 (`=`)、不等於 (`!=`)、regex 相符 (`=~`) 和負 regex 相符 ()`!~`。指定`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"
    ]
}
```