数据API接口说明

写入data point

方法 API 说明
POST /v1/datapoint 写入data point

请求参数

参数名称 参数类型 是否必须 说明
datapoints List<Datapoint> 必须 datapoint列表,由Datapoint对象组成的数组

Datapoint对象

参数名称 参数类型 是否必须 说明
metric String 必须 metric的名称
field String 可选 field的名称,默认名称为value。不同的field支持不同的数据类型写入。对于同一个field,如果写入了某个数据类型的value之后,相同的field不允许写入其他数据类型
tags Object 必须 data point对应的所有tag,Object中的一对key-value表示一个tag的key-value
type String 可选 目前支持Long/Double/String/Bytes。代表value字段的类型,如果不填会根据解析出来的类型为准。bytes是种特殊类型,表示value是经过base64编码后的String,TSDB存储时会反编码成byte数组存储。
timestamp Int 可选 Unix时间戳,单位是毫秒;如果timestamp为空,value不为空,timestamp自动填入系统当前时间;如果timestamp的位数小于等于10位,将认为精度是秒,自动乘以1000;timestamp+value与values两者必须二选一
value Int/Double/String 可选 data point的值,timestamp+value与values两者必须二选一。当写入的metric、field、tags、timestamp都相同时,后写入的value会覆盖先写入的value
values List<List<Any>> 可选 对于相同的metric+tags的data point,可以通过合并成一个values的List来减少payload,values是个二维数组,里面的一维必须是两个元素,第一个元素是timestamp,类型是Int,第二个元素是value,类型是Int/Double/String;如果timestamp的位数小于等于10位,将认为精度是秒,自动乘以1000

请求示例

POST /v1/datapoint HTTP/1.1
HOST: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

{
    "datapoints": [{
        "metric": "cpu_idle",
        "tags": {
            "host": "server1",
            "rack": "rack1"
        },
        "timestamp": 1465376157007,
        "value": 51
    }, {
        "metric": "cpu_idle",
        "tags": {
            "host": "server2",
            "rack": "rack2"
        },
        "values": [
            [1465376269769, 67],
            [1465376325057, 60]
        ]
    }]
}

返回示例

HTTP/1.1 204 No Content
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

获取metric列表

方法 API 说明
GET /v1/metric 获取database中所有的metric的列表

返回参数

参数名称 参数类型 说明
metrics List<String> metric的列表

请求示例

GET /v1/metric HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

返回示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "metrics": [
        "cpu_idle",
        "mem_used"
    ]
}

获取field列表

方法 API 说明
GET /v1/metric/{metric}/field 获取database中metric的field列表

返回参数

参数名称 参数类型 说明
fields Object field列表,Object的每个key对应一个field的key,Object的每个value都是Object类型的,表示该field的类型

请求示例

GET /v1/metric/wind/field HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

返回示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "fields": {
        "power": {
            "type": "String"
            },
        "direction": {
            "type": "Number"
        }
    }
}

获取tag列表

方法 API 说明
GET /v1/metric/{metric}/tag 获取metric对应的所有tag的key和value列表

请求参数

参数名称 参数类型 是否必须 说明
metric String 必须 metric的名称
start Int 可选 查询一段时间的所有tag,此为起始时间,默认为0
end Int 可选 查询一段时间的所有tag,此为结束时间,默认为263 - 1

返回参数

参数名称 参数类型 说明
tags Object tag列表,Object的每个key对应一个tag的key,Object的每个value都是List<String>类型的,表示该tag的所有value的列表

请求示例

GET /v1/metric/cpu_idle/tag HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

返回示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "tags": {
        "host": ["server1", "server2"],
        "rack": ["rack1", "rack2"]
    }
}

查询data point

注意:

若单次查询时间超过50s,系统将自动终止本次查询。如果出现查询超时,可以采取以下措施优化查询:

  1. 减少单次请求中query个数
  2. 缩短单个query中起止时间的间隔
  3. 减少单个query涉及到的时间序列数目
  4. 对数据进行预处理
方法 API 说明
GET /v1/datapoint?query={json} 查询data point,查询参数编码在query参数中
PUT /v1/datapoint?query 查询data point,查询参数在body中

请求参数

参数名称 参数类型 是否必须 说明
queries List<Query> 必须 查询条件列表,由Query对象组成的数组
disablePresampling Boolean 可选 是否禁用预处理结果查询,默认false

Query对象

参数名称 参数类型 是否必须 说明
metric String 必须 需要查询的metric的名称
field String 可选 需要查询的metric的field名称,默认名称为value
fields List<String> 可选 需要查询的metric的field的列表。fields和field冲突,不能同时存在。
tags List<String> 可选 需要查询的metric的tag的key列表
filters Object 必须 过滤条件,类型为Filters
groupBy List<GroupBy> 可选 分组条件,由GroupBy对象组成的数组
limit Int 可选 返回的data point数目限制,不填时默认为1,000,000
aggregators List<Aggregator> 可选 聚合条件,由Aggregator对象组成的数组
order String 可选 支持Asc和Desc,默认是Asc
fill Object 可选 插值选项,类型为Fill,插值只作用于原始数据,每个时间序列单独进行插值
fills List<Fill> 可选 多个插值选项,由Fill对象组成的数组。fills和fill冲突,不能同时存在。如果存在对于同一个域有多个插值,那么对于这个域只有第一个插值生效,譬如第一个fill是对全部插值,第二个fill是对a进行插值,那么对于a只有第一个fill生效
marker String 可选 用于分页查询,从marker开始返回,应使用上一次查询返回的nextMarker值

Filters对象

参数名称 参数类型 是否必须 说明
start Int/String 必须 起始时间,可以是绝对时间(即时间戳,类型为Int,单位为毫秒),也可以是相对时间(类型为String,如"5 days ago")。对于绝对时间,如果位数少于等于10位,将认为精度是秒,自动乘以1000。
注意:包含or时,最外层start不可填写,单个filter内部start为必须。
end Int/String 可选 结束时间,可以是绝对时间或者是相对时间,默认为263 - 1。对于绝对时间,如果位数少于等于10位,将认为精度是秒,自动乘以1000
tags Object 可选 可以是一个Object,Object的每个key对应一个tag的key,Object的每个value都是List<String>类型的,表示该tag的需要匹配的value的列表
可以是TagFilter对象组成的列表
value String 可选 单field查询的值过滤,分为符号和值两部分
符号支持=,!=,>,<,>=和<=
值允许Number(包括long和double)、String和Tag,其中String需包含于单引号中;Tag为tag的key,不加单引号,过滤时会被自动解析为对应的类型(譬如field的类型是Number,该tag的value会被解析为Number)
例如:"> 111" 或 "< 11.1" 或 "= 'abc'" 或 "> threshold"
fields List<FieldFilter> 可选 多field查询的值过滤,由FieldFilter对象组成的数组,fields和value冲突,不能同时存在。
or List<Filters> 可选 或filter查询条件,or和其他查询条件冲突,不能同时存在。

FieldFilter对象

参数名称 参数类型 是否必须 说明
field String 必须 需要过滤的metric的field名称
value String 必须 多field查询的值过滤,分为符号和值两部分
符号支持=,!=,>,<,>=和<=
值允许Number(包括long和double)、String和Tag,其中String需包含于单引号中;Tag为tag的key,不加单引号,过滤时会被自动解析为对应的类型(譬如field的类型是Number,该tag的value会被解析为Number)
例如:"> 111" 或 "< 11.1" 或 "= 'abc'" 或 "> threshold"

TagFilter对象

参数名称 参数类型 是否必须 说明
tag String 必须 需要过滤的metric的tag的key
in List<String> 可选 可以包含的tag的value列表,即tag的value只需要是in中的任何一个值。不可与notIn和like同时存在
notIn List<String> 可选 需要过滤的tag的value列表,即tag的value不能是notIn中的任何一个值。不可与in和like同时存在
like String 可选 需要匹配的规则,“%”匹配任意数量的字符,“_”匹配单个字符,转义字符为“/”;不可与in和notIn同时存在

GroupBy对象

参数名称 参数类型 是否必须 说明
name String 必须 分组方式,目前仅支持Tag
tags List<String> 可选 按照哪些tag进行分组,name为Tag时必填

Aggregator对象

参数名称 参数类型 是否必须 说明
name String 必须 聚合的方式,目前支持Avg、Dev、Count、First、Last、LeastSquares、Max、Min、Percentile、Sum、Diff、Div、Scale、Rate、AdjacentUnique
sampling String 可选 采样的时间长度,如"10 minutes"。支持自然日历对齐的查询,时间单位需增加字符“c”,如“1 hc”,详细请参考时间单位页面。name为Avg、Dev、Count、First、Last、LeastSquares、Max、Min、Percentile、Sum时才需填此项,若不填写则sampling为整个查询时间范围。
percentile Double 可选 百分数,取值范围为(0,1],如0.1表示10%,name为Percentile时必填
divisor Double 可选 除数,name为Div时必填
factor Double 可选 倍数,name为Scale时必填
timeUnit String 可选 时间单位,name为Rate时必填

日历对齐的规则如下:

如果查询的时间范围是 6月15日12:12:12.000 - 9月17日11:11:11.000,通过“自然日历对齐”查询,采样周期1月,则生成4个值。

第1个值是6月15日12:12:12.000 - 6月30日23:59:59.999的聚合值,

第2个值是7月1日00:00:00.000 - 7月31日23:59:59.999的聚合值,

第3个值是8月1日00:00:00.000 - 8月31日23:59:59.999的聚合值,

第4个值是9月1日00:00:00.000 - 9月17日11:11:11.000 的聚合值。

Fill对象

参数名称 参数类型 是否必须 说明
type String 必须 插值类型,目前支持Linear(线性插值)、Previous(按前一个值插值)、Fixed(固定值插值)
interval String 必须 插值间隔,一个时间序列在此间隔内没有值则进行插值,格式请参考时间单位
maxWriteInterval String 可选 最大写入间隔,一个时间序列的数据最大写入间隔(在此间隔内必然有值),默认为0。格式请参考时间单位
系统会尝试查找从(start - maxWriteInterval)到start,以及end到(end + maxWriteInterval)的点。
如果(start - maxWriteInterval)到start找不到点,则start到end间第一个点之前的缺少的点会按第一个点的值进行插值;
如果end到(end + maxWriteInterval)找不到点,则start到end间最后一个点之后的缺少的点会按最后一个点的值进行插值。
type为Fixed时忽略该参数
value Int/Double/String 可选 固定值插值所插入的固定值,type为Fixed时必填
field String 可选 需要插值的field,不填此参数默认为对所有field进行插值

返回参数

参数名称 参数类型 说明
results List<Result> 结果列表,与queries一一对应,由Result对象组成的数组

Result对象

参数名称 参数类型 说明
metric String 结果的metric名称
field String 结果的field名称
fields List<String> 结果的fields列表
tags List<String> 结果的tags列表
rawCount Int 原始的data point数目
consumedCount Int 扫描计费的data point数目
groups List<Group> 结果的分组列表,由Group对象组成的数组
truncated Boolean 是否所有数据都返回了,true表示后面还有数据,false表示后面已经没有数据,默认是false
当使用了groupBy或aggregators时,没有此项
nextMarker String 用于分页查询,获取下一批数据所需要传递的marker值,当truncated为true时才有此项
presamplingRuleId String 预处理规则命中ID,没有参数表示没有命中

Group对象

参数名称 参数类型 说明
groupInfos List<GroupInfo> 该分组的信息,由GroupInfo对象组成的数组
values List<List<Any>> 时间与值的序列,二维数组,第一个元素是timestamp,类型是Int,后面多个元素是field对应的value,个数为fields的个数,类型是Int/Double/String。之后多个元素是tag对应的value,个数为tags的个数,类型是String。

GroupInfo对象

参数名称 参数类型 说明
name String 分组方式,目前仅支持Tag
tags Object 该分组的tag,Object中的一对key-value表示一个tag的key-value,name为Tag时有此项

单域请求示例

PUT /v1/datapoint?query HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

{
    "queries": [{
        "metric": "cpu_idle",
        "field": "test",
        "filters": {
            "start": "1 hour ago",
            "tags": {
                "host": ["server1", "server2"]
            },
            "value": ">= 10"
        },
        "groupBy": [{
            "name": "Tag",
            "tags": ["rack"]
        }],
        "limit": 1000,
        "aggregators": [{
            "name": "Sum",
            "sampling": "10 minutes"
        }]    
    }],
    "disablePresampling": false
}

单域返回示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "results": [{
        "metric": "cpu_idle",
        "field": "test",
        "rawCount": 1000,
        "groups": [{
            "groupInfos": [{
                "name": "Tag",
                "tags": {
                    "rack": "rack1"
                }
            }],
            "values": [
                [1465718968506, 10],
                [1465718985346, 12],
                [1465718992879, 15]
            ]
        }],
        "presamplingRuleId": "21"
    }]
}

多域请求示例

PUT /v1/datapoint?query HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

{
    "queries": [{
        "metric": "cpu_idle",
        "fields": ["field1","field2"],
        "tags": ["rack"],
        "filters": {
            "fields": [{
                    "field": "field1",
                    "value": ">= 10"
                },{
                    "field": "field2",
                    "value": "<= 10"
            }],
            "start": "1 hour ago",
            "tags": {
                "host": ["server1", "server2"]
            },
        },
        "groupBy": [{
            "name": "Tag",
            "tags": ["rack"]
        }],
        "limit": 1000,
        "aggregators": [{
            "name": "Sum",
            "sampling": "10 minutes"
        }]
    }],
    "disablePresampling": false
}

多域返回示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "results": [{
        "metric": "cpu_idle",
        "fields": ["field1","field2"],
        "tags": ["rack"],
        "rawCount": 1000,
        "groups": [{
            "groupInfos": [{
                "name": "Tag",
                "tags": {
                    "rack": "rack1"
                }
            }],
            "values": [
                [1465718968506, 10, 1.0, "rack1"],
                [1465718985346, 12, 2.0, "rack1"],
                [1465718992879, 15, 11.0, "rack1"]
            ]
        }],
    }]
}

或查询请求示例

PUT /v1/datapoint?query HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

{
    "queries": [{
        "metric": "cpu_idle",
        "fields": ["field1","field2"],
        "tags": ["rack"],
        "filters": {
            "or": [{
                "fields": [{
                        "field": "field1",
                        "value": ">= 10"
                    },{
                        "field": "field2",
                        "value": "<= 10"
                 }],
                "start": "1 hour ago"
            },{
                "tags":[{
                     "tag": "rack",
                     "in": ["rack1", "rack2"]
                 }],
                "start": "2 hour ago"
            }]
        },
        "groupBy": [{
            "name": "Tag",
            "tags": ["rack"]
        }],
        "limit": 1000,
        "aggregators": [{
            "name": "Sum",
            "sampling": "10 minutes"
        }]
    }]
    "disablePresampling": false
}

或查询返回示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "results": [{
        "metric": "cpu_idle",
        "fields": ["field1","field2"],
        "tags": ["rack"],
        "rawCount": 1000,
        "groups": [{
            "groupInfos": [{
                "name": "Tag",
                "tags": {
                    "rack": "rack1"
                }
            }],
            "values": [
                [1465718968506, 10, 1.0, "rack1"],
                [1465718985346, 12, 2.0, "rack1"],
                [1465718992879, 15, 11.0, "rack1"]
            ]
        }],
    }]
}

插值请求示例

PUT /v1/datapoint?query HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

{
    "queries": [{
        "metric": "cpu_idle",
        "filters": {
            "start": "1 hour ago"
            "tags": {
                "host": ["server1"]
            }
        },
        "fill": {
            "type": "Linear",
            "interval": "5 minutes",
            "maxWriteInterval": "30 minutes"
        }
    }]
}

插值返回示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "results": [{
        "metric": "cpu_idle",
        "field": "value",
        "rawCount": 2,
        "groups": [{
            "groupInfos": [],
            "values": [
                [1499072400000, 20.4],
                [1499072700000, 17.85],
                [1499073000000, 15.3],
                [1499073300000, 22.95],
                [1499073600000, 30.6],
                [1499073900000, 38.25],
                [1499074200000, 45.9],
                [1499074500000, 53.55],
                [1499074800000, 61.2],
                [1499075100000, 61.2],
                [1499075400000, 61.2],
                [1499075700000, 61.2]
            ]
        }]
    }]
}

标签匹配请求示例

PUT /v1/datapoint?query HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

{
    "queries": [{
        "metric": "cpu_idle",
        "tags": ["tag1"],
        "filters": {
            "start": "1 hour ago"
            "tags": [{
                "tag": "tag1",
                "like": "value%"
            }]
        }
    }]
}

标签匹配返回示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "results": [{
        "metric": "cpu_idle",
        "field": "value",
        "tags": ["tag1"],
        "rawCount": 2,
        "groups": [{
            "groupInfos": [],
            "values": [
                [1499072400000, 20.4, "value1"],
                [1499072700000, 17.85, "value2"]
            ]
        }]
    }]
}

SQL查询接口

方法 API 说明
GET /v1/row?sql={statement} 使用ANSI SQL查询时序数据

请求参数

参数名称 参数类型 是否必须 说明
sql String 必须 ASIC语法的 SQL 查询语句,Eg. select * from metric

返回参数

参数名称 参数类型 说明
Columns List<Column> SQL查询的schema信息,由Column对象组成的数组
rows List<List<Object>> SQL查询的结果列表,由Object对象组成的二维数组

Column对象

参数名称 参数类型 说明
name String Column的名称

请求示例

GET /v1/row?sql=select%20%2A%20from%20metric HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

返回示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "columns": [{
        "name": "time"
    },{
        "name": "field1",
    },{
        "name": "tag1"
    }],
    "rows": [
        [1499072400000, 20.4, "value1"],
        [1499072700000, 17.85, "value2"]
    ]
}