查询数据接口

接口描述

获取指定指标的一个或多个统计数据的时间序列数据。可获取云产品监控数据、站点监控数据或您推送的自定义监控数据。

接口限制

• 一次返回的数据点数目不能超过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 的格式 维度列表 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参数都在一行里。

GET  /json-api/v1/metricdata/fakeuser1ba678asdf8as7df6a5sdf67/BCE_BCC/CpuIdlePercent?
dimensions=InstanceId:fakeid-2222-8888-1111-13a8469b1fb2
&statistics[]=average,maximum,minimum
&periodInSecond=60
&startTime=2019-04-16T13:55:01Z
&endTime=2019-04-16T14:00:01Z
HTTP/1.1
Host:bcm.bj.baidubce.com:80

响应示例

成功响应示例

在查询数据的时候,需要填写statistics[]参数,该参数的值决定了响应里一个dataPoint会有哪些属性。

当statistics[]=average时,返回结果示例如下:

HTTP/1.1 200 OK
x-bce-request-id: dwegvad4-dwea-4d3dsa-8ew2-4b7263fs1ecd
Content-Type: application/json;charset=UTF-8
{
    "requestId": "17f101a7-67a8-4c2e-93d7-60c0d4a21f0c",
    "code": "OK",
    "message": "OK",
    "dataPoints": [
        {
            "average": 2.24,
            "timestamp": "2019-04-16T13:55:01Z"
        },
        {
            "average": 0.22,
            "timestamp": "2019-04-16T13:56:01Z"
        },
        {
            "average": 0.19,
            "timestamp": "2019-04-16T13:57:01Z"
        },
        {
            "average": 0.18,
            "timestamp": "2019-04-16T13:58:01Z"
        },
        {
            "timestamp": "2019-04-16T13:59:01Z"
        }
    ]
}

当statistics[]=average,sum,minimum时,返回结果示例如下:

HTTP/1.1 200 OK
x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
Content-Type: application/json;charset=UTF-8
{
    "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
    "code": "OK",
    "message": "OK",
    "successList": [
        {
            "dataPoints": [
                {
                    "average": 40359.0,
                    "sum": 80718.0,
                    ""minimum":39900.0,
                    "timestamp": "2019-04-23T00: 00: 00Z"
                }
            ]
        }
    ]
}

失败响应示例

当您的请求结构构造正确,但未找到对应的监控数据或输入参数不正确,BCM会为您返回200 OK的返回code,并在返回body体里具体展示错误原因。

情况一 未查询到数据。在请求中指定的用户、名字空间、监控项及维度下,从开始时间至结束时间内没有查询到监控数据。

当这种情况发生时,会为您返回对应的时间点,但没有监控数据

HTTP/1.1 200 OK
x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
Content-Type: application/json;charset=UTF-8
{
    "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
    "code": "OK",
    "message": "OK",
    "successList": [
        {
            "dataPoints": [
                {
                    "timestamp": "2019-04-23T00: 00: 00Z"
                }
            ]
        }
    ]
}

情况二 参数不正确。下例为缺少endTime参数。

HTTP/1.1 200 OK
x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
Content-Type: application/json;charset=UTF-8
{
    "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
    "code": "INVALID_PARAMETER",
    "message": "Required endTime parameter String is not present"
}

下例为维度参数中值的格式不正确。

HTTP/1.1 200 OK
x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
Content-Type: application/json;charset=UTF-8
{
    "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
    "code": "INVALID_PARAMETER_VALUE",
    "message": "Wrong dimensions format, example: name:value;name:value"
}