数据API接口说明

更新时间：2022-07-19

写入data point

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

请求参数

参数名称	参数类型	是否必须	说明
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/BigDecimal。代表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，是unix时间戳，类型是Int，第二个元素是value，类型是Int/Double/String；如果timestamp的位数小于等于10位，将认为精度是秒，自动乘以1000

**请求示例** HOST中{database}字段表示数据库名称

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"
        },
        "type": "Long",
        "timestamp": 1465376157007,
        "value": 51
    }, {
        "metric": "cpu_idle",
        "tags": {
            "host": "server2",
            "rack": "rack2"
        },
        "type": "Long",
        "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?start=0&end=1562573168000	获取metric对应的所有tag的key和value列表

请求参数

参数名称	参数类型	是否必须	说明
metric	String	必须	metric的名称
start	Int	可选	查询一段时间的所有tag，此为起始时间，默认为0
end	Int	可选	查询一段时间的所有tag，此为结束时间，默认为2⁶³ - 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对象组成的数组
offset	Int	可选	数据分页，查询返回数据点的偏移量，不填默认为0
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	可选	结束时间，可以是绝对时间或者是相对时间，默认为2⁶³ - 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 放在get请求中时需要进行url encode

返回参数

参数名称	参数类型	说明
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"]
    ]
}

介绍

管理API接口说明

百度智能云

时序时空数据库 TSDB

时序时空数据库 TSDB

数据API接口说明

写入data point

获取metric列表

获取field列表

获取tag列表

查询data point

SQL查询接口