本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# GetSeries
`GetSeries` 操作會傳回標籤符合一或多個選取器的時間序列清單。
有效的 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"}`。不支援沒有指標名稱相等相符項的選取器。除了完全相符之外，標籤比對程式也支援不等於 (`!=`)、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-GetSeries-Limits)。 |
## 所需的 IAM 許可
若要呼叫 `GetSeries`，呼叫身分必須具有下列 IAM 動作：
+ `cloudwatch:ListMetrics`
如需所有 PromQL 操作的完整 IAM 動作映射，請參閱 [PromQL 的 IAM 許可](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)。
## 結果限制
單一`/api/v1/series`回應最多可傳回 **10，000 個唯一的時間序列**。若要請求較少的結果，請將具有 值的 `limit` 參數傳遞`1`至 `10000`。如果您未指定 `limit`，CloudWatch 最多會傳回 上限。
當相符的序列超過上限時，回應會截斷，並在標準 Prometheus `warnings`欄位中包含訊息。HTTP 狀態碼保持 `200`。
如需 PromQL 限制的完整清單，包括 TPS、並行和 24 小時掃描時段，請參閱 [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`請求使用 regex 比對選取器。解碼`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` 欄位是標籤映射的陣列，每個相符的序列各一個。
```
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"
}
]
}
```