查询数据接口
更新时间：2025-08-20
接口描述
获取指定指标的一个或多个统计数据的时间序列数据。可获取云产品监控数据、站点监控数据或您推送的自定义监控数据。
接口限制
• 一次返回的数据点数目不能超过1440个。
请求结构
- 请求方法：GET
- 请求URL：/json-api/v1/metricdata/{userid}/{scope}/{metricName}?{Query参数}
- Query参数：dimensions={dimensions}&statistics[]={statistics1,statistics2,statistics3...}&periodInSecond={periodInSecond}&startTime={startTime}&endTime={endTime}
请求参数
| 名称 | 类型 | 描述 | 是否必须 | 参数位置 |
|---|---|---|---|---|
| userId | String | 租户ID | 是 | URL参数 |
| scope | String，仅限于使用如下字符集合："0~9、A~Z、a~z"、 "_" | 名字空间 | 是 | URL参数 |
| metricName | String，仅限于使用如下字符集合："0~9、A~Z、a~z"、 "_" | 监控指标名 | 是 | URL参数 |
| statistics[] | Statistics，按照statistics1,statistics2,statistics3格式，可选值为average,maximum,minimum,sum,sampleCount | 统计方法类型 | 是 | Query参数 |
| dimensions | String，由dimensionName:dimensionValue组成。当监控项具备多个维度时使用分号连接，例如dimensionName:dimensionValue;dimensionName:dimensionValue，相同维度只能指定一个维度值 | 维度列表 | 是 | Query参数 |
| startTime | DateTime,请参考日期与时间，UTC日期表示 | 查询起始时间 | 是 | Query参数 |
| endTime | DateTime,请参考日期与时间，UTC日期表示 | 查询截止时间 | 是 | Query参数 |
| periodInSecond | Integer，60的倍数，单位：秒（s） | 统计周期 | 是 | Query参数 |
参数解释
- 名字空间scope、监控项metric、统计方法Statistic、维度Dimension等的概念请参考核心概念。
响应参数
| 名称 | 类型 | 描述 |
|---|---|---|
| requestId | String | 请求标识 |
| code | String | 返回码 |
| message | String | 错误信息 |
| dataPoints | List（DataPoint） | 监控指标 |
DataPoint
| 名称 | 类型 | 描述 |
|---|---|---|
| average | double | 统计周期内监控项的平均值 |
| sum | double | 统计周期内监控项的和值 |
| minimum | double | 统计周期内监控项的最小值 |
| maximum | double | 统计周期内监控项的最大值 |
| sampleCount | Integer | 统计周期内监控项数据点数 |
| timestamp | DateTime,请参考日期与时间，UTC日期表示 | 监控项统计周期对应的时间 |
请求示例
为了展示的更清晰，对请求示例做了换行处理，在实际构造请求时URL路径及Query参数都在一行里。
Plain Text
1GET /json-api/v1/metricdata/fakeuser1ba678asdf8as7df6a5sdf67/BCE_BCC/CpuIdlePercent?
2dimensions=InstanceId:fakeid-2222-8888-1111-13a8469b1fb2
3&statistics[]=average,maximum,minimum
4&periodInSecond=60
5&startTime=2019-04-16T13:55:01Z
6&endTime=2019-04-16T14:00:01Z
7HTTP/1.1
8Host:bcm.bj.baidubce.com:80 响应示例
成功响应示例
在查询数据的时候，需要填写statistics[]参数，该参数的值决定了响应里一个dataPoint会有哪些属性。
当statistics[]=average时，返回结果示例如下：
Plain Text
1HTTP/1.1 200 OK
2x-bce-request-id: dwegvad4-dwea-4d3dsa-8ew2-4b7263fs1ecd
3Content-Type: application/json;charset=UTF-8
4{
5 "requestId": "17f101a7-67a8-4c2e-93d7-60c0d4a21f0c",
6 "code": "OK",
7 "message": "OK",
8 "dataPoints": [
9 {
10 "average": 2.24,
11 "timestamp": "2019-04-16T13:55:01Z"
12 },
13 {
14 "average": 0.22,
15 "timestamp": "2019-04-16T13:56:01Z"
16 },
17 {
18 "average": 0.19,
19 "timestamp": "2019-04-16T13:57:01Z"
20 },
21 {
22 "average": 0.18,
23 "timestamp": "2019-04-16T13:58:01Z"
24 },
25 {
26 "timestamp": "2019-04-16T13:59:01Z"
27 }
28 ]
29}当statistics[]=average,sum,minimum时，返回结果示例如下：
Plain Text
1HTTP/1.1 200 OK
2x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
3Content-Type: application/json;charset=UTF-8
4{
5 "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
6 "code": "OK",
7 "message": "OK",
8 "successList": [
9 {
10 "dataPoints": [
11 {
12 "average": 40359.0,
13 "sum": 80718.0,
14 ""minimum":39900.0,
15 "timestamp": "2019-04-23T00: 00: 00Z"
16 }
17 ]
18 }
19 ]
20}失败响应示例
当您的请求结构构造正确，但未找到对应的监控数据或输入参数不正确，BCM会为您返回200 OK的返回code，并在返回body体里具体展示错误原因。
情况一 未查询到数据。在请求中指定的用户、名字空间、监控项及维度下，从开始时间至结束时间内没有查询到监控数据。
当这种情况发生时，会为您返回对应的时间点，但没有监控数据
Plain Text
1HTTP/1.1 200 OK
2x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
3Content-Type: application/json;charset=UTF-8
4{
5 "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
6 "code": "OK",
7 "message": "OK",
8 "successList": [
9 {
10 "dataPoints": [
11 {
12 "timestamp": "2019-04-23T00: 00: 00Z"
13 }
14 ]
15 }
16 ]
17}情况二 参数不正确。下例为缺少endTime参数。
Plain Text
1HTTP/1.1 200 OK
2x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
3Content-Type: application/json;charset=UTF-8
4{
5 "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
6 "code": "INVALID_PARAMETER",
7 "message": "Required endTime parameter String is not present"
8}下例为维度参数中值的格式不正确。
Plain Text
1HTTP/1.1 200 OK
2x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
3Content-Type: application/json;charset=UTF-8
4{
5 "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
6 "code": "INVALID_PARAMETER_VALUE",
7 "message": "Wrong dimensions format, example: name:value;name:value"
8}