批量查询监控数据
功能介绍
批量查询指定时间范围内指定指标的指定粒度的监控数据，目前最多支持500个指标的批量查询（即请求体参数metrics属性数组长度最大500），最多返回指标数据点3000个（即响应参数metrics属性对应对象datapoints属性累加最多返回3000个数据点）。
调试
您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。
URI
POST /V1.0/{project_id}/batch-query-metric-data
- 参数说明
表1 参数说明 名称
是否必选
说明
project_id
是
项目ID。
获取方式请参见获取项目ID。
请求消息
- 单次POST请求消息体大小不能超过512KB，否则请求会被服务端拒绝。
- 对于不同的period取值和查询的指标数量，其对应的默认最大查询区间(to - from)也不同，计算规则为“指标数量 * (to - from) / 监控周期 ≤ 3000”。
监控周期：请求参数period属性对应的值，需要转为毫秒值。
3000：响应体中的所有datapoints（指标数据列表）总和。
- 当period值为“1”时，监控周期为60*1000ms=60000ms。
- 当period值为"300" 时，监控周期为300*1000ms=300000ms。
- 当period值为"1200" 时，监控周期为1200*1000ms=1200000ms。
- 当period值为"3600" 时，监控周期为3600*1000ms=3600000ms。
- 当period值为"14400" 时，监控周期为14400*1000ms=14400000ms。
- 当period值为"86400" 时，监控周期为86400*1000ms=86400000ms。
例如批量查询300个指标，监控周期为60000ms，可算出(to - from)最大值为"600000"，若设定的请求参数使(to - from)超出最大值，from值会自动调整为"to-600000"。
- 请求参数
表2 请求参数 名称
是否必选
参数类型
说明
metrics
是
Arrays of objects
指标数据。数组长度最大500。
详细参数请参见表3。
from
是
Long
查询数据起始时间，UNIX时间戳，单位毫秒。建议from的值相对于当前时间向前偏移至少1个周期。由于聚合运算的过程是将一个聚合周期范围内的数据点聚合到周期起始边界上，如果将from和to的范围设置在聚合周期内，会因为聚合未完成而造成查询数据为空，所以建议from参数相对于当前时间向前偏移至少1个周期。以5分钟聚合周期为例：假设当前时间点为10:35，10:30~10:35之间的原始数据会被聚合到10:30这个点上，所以查询5分钟数据点时from参数应为10:30。
说明：云监控会根据所选择的聚合粒度向前取整from参数。
to
是
Long
查询数据截止时间UNIX时间戳，单位毫秒。from必须小于to。
period
是
String
监控数据粒度。
枚举值，取值范围：
- "1"，原始数据
- "300"，5分钟粒度
- "1200"，20分钟粒度
- "3600"，1小时粒度
- "14400"，4小时粒度
- "86400"，1天粒度
filter
是
String
数据聚合方式，支持的聚合方式如下:
- average：聚合周期内指标数据的平均值。
- max：聚合周期内指标数据的最大值。
- min：聚合周期内指标数据的最小值。
- sum：聚合周期内指标数据的求和值。
- variance：聚合周期内指标数据的方差。
filter参数的值不会影响原始数据（period为1）的查询结果。
表3 metrics字段数据结构说明 名称
是否必选
参数类型
说明
namespace
是
String
查询服务的命名空间，各服务命名空间请参考支持监控的服务列表。
格式为service.item；service和item必须是字符串，必须以字母开头，只能包含0-9/a-z/A-Z/_，service.item总长度最短为3，最大为32。
metric_name
是
String
指标ID，例如弹性云服务器的监控指标CPU使用率，对应的metric_name为cpu_util。各服务监控指标请参考支持监控的服务列表 中的监控指标参考文档列。
字符格式必须以字母开头，只能包含0-9/a-z/A-Z/_-，字符长度最短为1，最大为64。
dimensions
是
Arrays of objects
指标维度列表。数组最大长度为4。
单个维度为json对象，结构说明如下：
{
"name": "instance_id",
"value": "33328f02-3814-422e-b688-bfdba93d4050"
}
详细说明请参见表4。
表4 dimensions字段数据结构说明 名称
是否必选
参数类型
说明
name
是
String
监控维度名称，例如弹性云服务器的维度为instance_id。各服务维度请参考支持监控的服务列表，可参考维度中key字段。
必须以字母开头，只能包含0-9/a-z/A-Z/_/-，长度最短为1，最大为32。
value
是
String
维度取值，例如弹性云服务器的ID。可通过调用查询指标列表接口，在其响应体的相关指标数据中获取
必须以字母或数字开头，只能包含0-9/a-z/A-Z/_/-，长度最短为1，最大为256。
- 对于dimensions字段里value的值，可通过调用查询指标列表接口，在其响应体的相关指标数据中获取。
- 对于OBS相关指标数据，当进行了相关OBS接口操作时可查询到相关指标数据，否则查询结果为空。
- 对于EVS相关指标数据，disk_name维度下，它的返回值有云服务器实例ID-盘符名和云服务器实例ID-volume-卷ID两种。
- 云服务器实例ID-盘符名，例如：6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d-vda(vda为盘符名)。
- 云服务器实例ID-volume-卷ID，例如：6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d-volume-31f45764-38b3-44ad-aaca-4015c83371e6。
- 请求样例
请求样例一：查看维度是instance_id为07d878a9-2243-4e84-aeef-c47747d18024和mount_point为012bec14bc176310c19f40e384fd629b的弹性云服务器中操作系统的磁盘使用率，在2019-04-30 20:00:00到2019-04-30 22:00:00时间内，原始数据的平均值。
{ "from": 1556625600000, "to": 1556632800000, "period": "1", "filter": "average", "metrics": [{ "dimensions": [{ "name": "instance_id", "value": "07d878a9-2243-4e84-aeef-c47747d18024" }, { "name": "mount_point", "value": "012bec14bc176310c19f40e384fd629b" }], "metric_name": "disk_usedPercent", "namespace": "AGT.ECS" }] }请求样例二：查看维度是instance_id为238764d4-c4e1-4274-88a1-5956b057766b的弹性云服务器中操作系统的内存使用率，在2019-04-30 20:00:00到2019-04-30 22:00:00时间内，原始数据的平均值。
{ "from": 1556625600000, "to": 1556632800000, "period": "1", "filter": "average", "metrics": [{ "dimensions": [{ "name": "instance_id", "value": "238764d4-c4e1-4274-88a1-5956b057766b" }], "metric_name": "mem_usedPercent", "namespace": "AGT.ECS" }] }请求样例三：查看维度是instance_id为faea5b75-e390-4e2b-8733-9226a9026070,faea5b75-e390-4e2b-8733-9226a9026071,faea5b75-e390-4e2b-8733-9226a9026072,faea5b75-e390-4e2b-8733-9226a9026073,faea5b75-e390-4e2b-8733-9226a9026074的弹性云服务器的监控数据cpu_util，在2024-08-21 00:00:00到2024-08-21 23:59:59时间内，原始数据的平均值。查询5个指标，监控周期为60000ms，可算出(to - from)最大值为"36000000"，设定的请求参数to - from=86399000超出最大值36000000。根据公式：“指标数量 * (to - from) / 监控周期 ≤ 3000”。请求参数的from值会自动调整为to-36000000=1724219999000。
{ "metrics": [ { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026070" } ], "metric_name": "cpu_util" }, { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026071" } ], "metric_name": "cpu_util" }, { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026072" } ], "metric_name": "cpu_util" }, { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026073" } ], "metric_name": "cpu_util" }, { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026074" } ], "metric_name": "cpu_util" }, ], "from": 1724169600000, "to": 1724255999000, "period": "1", "filter": "average" }请求样例四：查看维度是instance_id为faea5b75-e390-4e2b-8733-9226a9026070的弹性云服务器的监控数据cpu_util和维度instance_id为06b4020f-461a-4a52-84da-53fa71c2f42b的弹性云服务器的监控数据network_vm_connections，在2019-04-30 20:00:00到2019-04-30 22:00:00时间内，原始数据的平均值。{ "metrics": [ { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026070" } ], "metric_name": "cpu_util" }, { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "06b4020f-461a-4a52-84da-53fa71c2f42b" } ], "metric_name": "network_vm_connections" } ], "from": 1556625600000, "to": 1556632800000, "period": "1", "filter": "average" }请求样例五：查看维度是rds_cluster_id为3c8cc15614ab46f5b8743317555e0de2in01的关系性数据库的监控数据rds021_myisam_buf_usage和维度是rds_cluster_id为3b2fa8b55a9b4adca3713962a9d31884in01的关系性数据库的监控数据rds021_myisam_buf_usage，在2019-04-30 20:00:00到2019-04-30 22:00:00时间内，原始数据的求和值。{ "metrics": [ { "namespace": "SYS.RDS", "dimensions": [ { "name": "rds_cluster_id", "value": "3c8cc15614ab46f5b8743317555e0de2in01" } ], "metric_name": "rds021_myisam_buf_usage" }, { "namespace": "SYS.RDS", "dimensions": [ { "name": "rds_cluster_id", "value": "3b2fa8b55a9b4adca3713962a9d31884in01" } ], "metric_name": "rds021_myisam_buf_usage" } ], "from": 1556625600000, "to": 1556632800000, "period": "1", "filter": "sum" }请求样例六：查看维度是instance_id为cd841102-f6b1-407d-a31f-235db796dcbb和proc为b28354b543375bfa94dabaeda722927f的主机监控的监控数据proc_specified_count，在2019-04-30 20:00:00到2019-04-30 22:00:00时间内，周期为20分钟时，指标数据的最小值。{ "metrics": [ { "namespace": "AGT.ECS", "dimensions": [ { "name": "instance_id", "value": "cd841102-f6b1-407d-a31f-235db796dcbb" }, { "name": "proc", "value": "b28354b543375bfa94dabaeda722927" } ], "metric_name": "proc_specified_count" } ], "from": 1556625600000, "to": 1556632800000, "period": "1200", "filter": "min" }
响应消息
- 响应参数
表5 响应参数 名称
参数类型
说明
metrics
Arrays of objects
指标数据。
详细参数请参见表6。
表6 metrics字段数据结构说明 名称
参数类型
说明
unit
String
指标单位。
datapoints
Arrays of objects
指标数据列表。由于查询数据时，云监控会根据所选择的聚合粒度向前取整from参数，所以datapoints中包含的数据点有可能会多于预期，最多返回3000个数据点（响应参数metrics属性对应对象datapoints属性累加最多返回3000个数据点）。
详细参数请参见表8。
namespace
String
指标命名空间，格式为service.item；service和item必须是字符串，必须以字母开头，只能包含0-9/a-z/A-Z/_，service.item总长度最短为3，最大为32。
dimensions
Arrays of objects
指标维度列表。
单个维度为json对象，结构说明如下：
{
"name": "instance_id",
"value": "33328f02-3814-422e-b688-bfdba93d4050"
}
详细参数请参见表7。
metric_name
String
指标名称，必须以字母开头，只能包含0-9/a-z/A-Z/_，长度最短为1，最大为64。
表7 dimensions字段数据结构说明 名称
参数类型
说明
name
String
监控维度名称，例如弹性云服务器的维度为instance_id。各服务维度请参考支持监控的服务列表，可参考维度中key字段。
必须以字母开头，只能包含0-9/a-z/A-Z/_/-，长度最短为1，最大为32。
value
String
维度取值，例如弹性云服务器的ID。
必须以字母或数字开头，只能包含0-9/a-z/A-Z/_/-，长度最短为1，最大为256。
- 响应样例
响应样例一：维度是instance_id为faea5b75-e390-4e2b-8733-9226a9026070的弹性云服务器的监控数据cpu_util的平均值和维度是instance_id为06b4020f-461a-4a52-84da-53fa71c2f42b的弹性云服务器的监控数据network_vm_connections的平均值。
{ "metrics": [ { "namespace": "SYS.ECS", "metric_name": "cpu_util", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026070" } ], "datapoints": [ { "average": 0.69, "timestamp": 1556625610000 }, { "average": 0.7, "timestamp": 1556625715000 } ], "unit": "%" }, { "namespace": "SYS.ECS", "metric_name": "network_vm_connections", "dimensions": [ { "name": "instance_id", "value": "06b4020f-461a-4a52-84da-53fa71c2f42b" } ], "datapoints": [ { "average": 1, "timestamp": 1556625612000 }, { "average": 3, "timestamp": 1556625717000 } ], "unit": "count" } ] }响应样例二：维度是rds_cluster_id为3c8cc15614ab46f5b8743317555e0de2in01的关系性数据库和维度是rds_cluster_id为3b2fa8b55a9b4adca3713962a9d31884in01的关系性数据库的监控数据rds021_myisam_buf_usage的求和值。{ "metrics": [ { "unit": "Ratio", "datapoints": [ { "sum": 0.07, "timestamp": 1556625628000 }, { "sum": 0.07, "timestamp": 1556625688000 } ], "namespace": "SYS.RDS", "dimensions": [ { "name": "rds_cluster_id", "value": "3c8cc15614ab46f5b8743317555e0de2in01" } ], "metric_name": "rds021_myisam_buf_usage" }, { "unit": "Ratio", "datapoints": [ { "sum": 0.06, "timestamp": 1556625614000 }, { "sum": 0.07, "timestamp": 1556625674000 } ], "namespace": "SYS.RDS", "dimensions": [ { "name": "rds_cluster_id", "value": "3b2fa8b55a9b4adca3713962a9d31884in01" } ], "metric_name": "rds021_myisam_buf_usage" } ] }响应样例三：维度是instance_id为cd841102-f6b1-407d-a31f-235db796dcbb和proc为b28354b543375bfa94dabaeda722927f的主机监控的监控数据rds021_myisam_buf_usage的最小值。{ "metrics": [ { "unit": "Ratio", "datapoints": [ { "min": 0, "timestamp": 1556625612000 }, { "min": 0, "timestamp": 1556625672000 } ], "namespace": "AGT.ECS", "dimensions": [ { "name": "instance_id", "value": "cd841102-f6b1-407d-a31f-235db796dcbb" }, { "name": "proc", "value": "b28354b543375bfa94dabaeda722927f" } ], "metric_name": "rds021_myisam_buf_usage" } ] }
返回值
错误码
请参考返回错误码说明。
常见问题
请参考批量查询监控数据常见问题。
