# 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"}`。不支持不带指标名称等值匹配器的选择器。除精确匹配外，标签匹配器还支持不等于 (`!=`)、正则表达式匹配 (`=~`) 和正则表达式否定匹配 (`!~`)。可以一次或多次指定 `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` 请求使用正则表达式匹配选择器。解码后的 `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"
}
]
}
```