View a markdown version of this page

GetSeries - Amazon CloudWatch
URL 查询参数所需的 IAM 权限结果限制示例请求示例响应

GetSeries

GetSeries 操作会返回标签匹配一个或多个选择器的时间序列列表。

有效的 HTTP 动词

GET, POST

有效的 URI

/api/v1/series

完整的请求 URL 由 AWS 区域的 CloudWatch 监控主机与操作路径组合而成，例如 https://monitoring.AWS Region.amazonaws.com/api/v1/series。有关端点、签名和所需 IAM 权限的信息，请参阅 PromQL 查询。

URL 查询参数

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

参数 说明

match[]

必需。一个序列选择器，用于筛选要返回的时间序列。每个选择器必须包含指标名称的精确匹配 (=)，例如 {"http.server.active_requests"} 或 {__name__="http.server.active_requests"}。不支持不带指标名称等值匹配器的选择器。除精确匹配外，标签匹配器还支持不等于 (!=)、正则表达式匹配 (=~) 和正则表达式否定匹配 (!~)。可以一次或多次指定 match[] 来组合选择器。有关选择器语法的更多信息，请参阅 PromQL 查询。

start

必需。要考虑的时间范围的开始时间，格式为 RFC 3339 时间戳或 Unix 时间戳。

end

必需。要考虑的时间范围的结束时间，格式为 RFC 3339 时间戳或 Unix 时间戳。

limit

可选。要返回的唯一时间序列的数量上限，范围为 1 到 10000。如果未指定 limit，CloudWatch 将返回数量上限（10,000）。请参阅结果限制。

所需的 IAM 权限

要调用 GetSeries，调用身份必须具有以下 IAM 操作：

  • cloudwatch:ListMetrics

有关所有 PromQL 操作的完整 IAM 操作映射，请参阅 PromQL的 IAM 权限。

结果限制

单个 /api/v1/series 响应最多可返回 10,000 个唯一时间序列。要请求更少的结果，请传递 limit 参数，其值范围为 1 到 10000。如果未指定 limit，CloudWatch 会返回数量上限。

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

有关 PromQL 限制的完整列表，包括 TPS、并发和 24 小时扫描窗口，请参阅 PromQL 限额和限制。

示例请求

以下 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"
        }
    ]
}