文档首页/云监控服务 CES/API参考/API/云资源监控/指标管理/查询指标列表 - ListMetrics
更新时间：2026-01-20 GMT+08:00
查看PDF
分享

查询指标列表 - ListMetrics

功能介绍

查询系统当前可监控指标列表，可以指定指标命名空间、指标名称、维度、排序方式，起始记录和最大记录条数过滤查询结果。

须知：

云服务资源删除后，会保留3个小时的数据缓存，在3小时之内还能查到资源对应的监控指标，属于正常现象。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

  • 如果使用角色与策略授权，具体权限要求请参见权限和授权项。
  • 如果使用身份策略授权，需具备如下身份策略权限。

    授权项

    访问级别

    资源类型（*为必须）

    条件键

    别名

    依赖的授权项

    ces:metrics:list

    List

    -

    -

    -

    -

URI

GET /V1.0/{project_id}/metrics

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数解释:

项目ID。用于明确项目归属，配置后可通过该ID查询项目下资产，可以通过调用API获取，也可以从控制台获取。获取方式请参见获取项目ID。

约束限制:

不涉及。

取值范围:

长度为[1,64]个字符。

默认取值:

不涉及。

表2 Query参数

参数

是否必选

参数类型

描述

namespace

否

String

参数解释

服务命名空间，样例：弹性云服务器的命名空间为SYS.ECS。

各服务命名空间请参阅支持监控的服务列表。

约束限制

不涉及

取值范围

格式为service.item，service和item以点号拼接组成。

service和item必须以字母（大写或小写）开头，后面可以跟零个或多个字母（大写或小写）、数字、下划线（_），长度为[3,32]个字符

默认取值

不涉及

metric_name

否

String

参数解释

资源的监控指标名称，样例：弹性云服务器监控指标中的cpu_util。

各服务资源的指标名称，请参阅具体云服务的文档。您可以直接从支持监控的服务列表页面导航至相应文档。

约束限制

不涉及

取值范围

必须以字母（大写或小写）开头，后面可以跟零个或多个字母（大写或小写）、数字、下划线（_）、连字符 （-），长度为[1,96]个字符

默认取值

不涉及

dim.0

否

String

参数解释

指标的第一个维度，目前最多支持4个维度，维度格式为dim.{i}=key,value。样例：instance_id,6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d

各服务资源的维度名称，请参阅具体云服务的文档。您可以直接从支持监控的服务列表页面导航至相应文档。

约束限制

不涉及

取值范围

dim.0=key,value，由key、value以逗号拼接组成。

key必须以字母（大写或小写）开头，后面可以跟零个或多个字母（大写或小写）、数字、下划线（）、连字符（-），长度为[1,32]个字符 value由多个字母（大写或小写）、数字、下划线（）、连字符（-）、点（.）、斜杠（/）、井号（#）、英文左括号（(）、英文右括号（)）组合而成，首个字符可以包含星号（*），但不能以连字符（-）开头，长度为[1,256]个字符

默认取值

不涉及

dim.1

否

String

参数解释

指标的第二个维度，目前最多支持4个维度，维度格式为dim.{i}=key,value。样例：instance_id,6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d

各服务资源的维度名称，请参阅具体云服务的文档。您可以直接从支持监控的服务列表页面导航至相应文档。

约束限制

不涉及

取值范围

dim.1=key,value，由key、value以逗号拼接组成。

key必须以字母（大写或小写）开头，后面可以跟零个或多个字母（大写或小写）、数字、下划线（）、连字符（-），长度为[1,32]个字符 value由多个字母（大写或小写）、数字、下划线（）、连字符（-）、点（.）、斜杠（/）、井号（#）、英文左括号（(）、英文右括号（)）组合而成，首个字符可以包含星号（*），但不能以连字符（-）开头，长度为[1,256]个字符

默认取值

不涉及

dim.2

否

String

参数解释

指标的第三个维度，目前最多支持4个维度，维度格式为dim.{i}=key,value。样例：instance_id,6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d

各服务资源的维度名称，请参阅具体云服务的文档。您可以直接从支持监控的服务列表页面导航至相应文档。

约束限制

不涉及

取值范围

dim.2=key,value，由key、value以逗号拼接组成。

key必须以字母（大写或小写）开头，后面可以跟零个或多个字母（大写或小写）、数字、下划线（）、连字符（-），长度为[1,32]个字符 value由多个字母（大写或小写）、数字、下划线（）、连字符（-）、点（.）、斜杠（/）、井号（#）、英文左括号（(）、英文右括号（)）组合而成，首个字符可以包含星号（*），但不能以连字符（-）开头，长度为[1,256]个字符

默认取值

不涉及

dim.3

否

String

参数解释

指标的第四个维度，目前最多支持4个维度，维度格式为dim.{i}=key,value。样例：instance_id,6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d

各服务资源的维度名称，请参阅具体云服务的文档。您可以直接从支持监控的服务列表页面导航至相应文档。

约束限制

不涉及

取值范围

dim.3=key,value，由key、value以逗号拼接组成。

key必须以字母（大写或小写）开头，后面可以跟零个或多个字母（大写或小写）、数字、下划线（）、连字符（-），长度为[1,32]个字符 value由多个字母（大写或小写）、数字、下划线（）、连字符（-）、点（.）、斜杠（/）、井号（#）、英文左括号（(）、英文右括号（)）组合而成，首个字符可以包含星号（*），但不能以连字符（-）开头，长度为[1,256]个字符

默认取值

不涉及

start

否

String

参数解释

分页起始值，格式为：namespace.metric_name.key:value

例如：start=SYS.ECS.cpu_util.instance_id:d9112af5-6913-4f3b-bd0a-3f96711e004d

约束限制

不涉及

取值范围

首次传空字符串，后续请求传递上一页返回值内的marker字段，作为下一页请求的分页起始值

默认取值

不涉及

limit

否

Integer

参数解释

单次查询的条数限制

约束限制

不涉及

取值范围

条数限制为[1,1000]

默认取值

1000

order

否

String

参数解释

用于标识结果的排序方法

约束限制

不涉及

取值范围

枚举值：

  • asc 升序

  • desc 降序

默认取值

asc

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

Content-Type

否

String

参数解释:

发送的实体的MIME类型。

约束限制:

不涉及。

取值范围:

长度为[1,64]个字符。

默认取值:

默认使用 application/json; charset=UTF-8，如果API是对象、镜像上传等接口，媒体类型可按照流类型的不同进行确定。

X-Auth-Token

否

String

参数解释:

用户Token。

约束限制:

不涉及。

取值范围:

长度为[1,16384]个字符。

默认取值:

不涉及。

响应参数

状态码：200

表4 响应Body参数

参数

参数类型

描述

metrics

Array of MetricInfoList objects

参数解释

指标信息列表

meta_data

MetricListMetaDataResp object

参数解释：

查询结果元数据信息，包括分页信息等

表5 MetricInfoList

参数

参数类型

描述

dimensions

Array of MetricsDimensionResp objects

参数解释

指标维度

metric_name

String

参数解释

指标名称

取值范围

不涉及

namespace

String

参数解释

服务命名空间

取值范围

不涉及

unit

String

参数解释

指标单位

取值范围

不涉及

表6 MetricsDimensionResp

参数

参数类型

描述

name

String

参数解释

资源维度，如：弹性云服务器，则维度为instance_id；目前最大支持4个维度，各服务资源的维度名称，请参阅具体云服务的文档。您可以直接从支持监控的服务列表页面导航至相应文档。

取值范围

由字母开头，后面可以包含字母、数字、_或-，长度为[1,32]个字符

value

String

参数解释

资源维度值，为资源的实例ID，如：4270ff17-aba3-4138-89fa-820594c39755。

取值范围

长度为[1,256]个字符

表7 MetricListMetaDataResp

参数

参数类型

描述

count

Integer

参数解释：

当前返回结果条数。

取值范围：

不涉及

total

Integer

参数解释：

总条数。

取值范围：

不涉及

marker

String

参数解释：

下一个开始的标记，用于分页。

取值范围：

不涉及

状态码：400

表8 响应Body参数

参数

参数类型

描述

-

String

请求错误。

状态码：401

表9 响应Body参数

参数

参数类型

描述

-

String

未提供认证信息，或认证信息错误。

状态码：403

表10 响应Body参数

参数

参数类型

描述

-

String

请求页面被禁止访问。

状态码：408

表11 响应Body参数

参数

参数类型

描述

-

String

请求超出了服务器的等待时间。

状态码：429

表12 响应Body参数

参数

参数类型

描述

-

String

请求过多。

状态码：500

表13 响应Body参数

参数

参数类型

描述

-

String

请求未完成，服务异常。

状态码：503

表14 响应Body参数

参数

参数类型

描述

-

String

系统暂时不可用，请求受限。

请求示例

/V1.0/{project_id}/metrics?namespace=SYS.ECS&metric_name=cpu_util&dim.0=instance_id,6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d&limit=10&order=desc

响应示例

状态码：200

OK

{
  "metrics" : [ {
    "namespace" : "SYS.ECS",
    "dimensions" : [ {
      "name" : "instance_id",
      "value" : "d9112af5-6913-4f3b-bd0a-3f96711e004d"
    } ],
    "metric_name" : "cpu_util",
    "unit" : "%"
  } ],
  "meta_data" : {
    "count" : 1,
    "marker" : "SYS.ECS.cpu_util.instance_id:d9112af5-6913-4f3b-bd0a-3f96711e004d",
    "total" : 7
  }
}

状态码

状态码

描述

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

408

Request Timeout

429

Too Many Requests

500

Internal Server Error

503

Service Unavailable

错误码

请参见错误码。

父主题：指标管理

相关文档