数据API接口说明
更新时间：2025-08-22
写入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 |
Plain Text
1POST /v1/datapoint HTTP/1.1
2HOST: {database}.tsdb.iot.gz.baidubce.com
3Authorization: {authorization}
4Content-Type: application/json; charset=utf-8
5x-bce-date: 2016-06-08T16:49:51Z
6
7{
8 "datapoints": [{
9 "metric": "cpu_idle",
10 "tags": {
11 "host": "server1",
12 "rack": "rack1"
13 },
14 "type": "Long",
15 "timestamp": 1465376157007,
16 "value": 51
17 }, {
18 "metric": "cpu_idle",
19 "tags": {
20 "host": "server2",
21 "rack": "rack2"
22 },
23 "type": "Long",
24 "values": [
25 [1465376269769, 67],
26 [1465376325057, 60]
27 ]
28 }]
29}返回示例
Plain Text
1HTTP/1.1 204 No Content
2x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7获取metric列表
| 方法 | API | 说明 |
|---|---|---|
| GET | /v1/metric | 获取database中所有的metric的列表 |
返回参数
| 参数名称 | 参数类型 | 说明 |
|---|---|---|
| metrics | List<String> | metric的列表 |
请求示例
Plain Text
1GET /v1/metric HTTP/1.1
2Host: {database}.tsdb.iot.gz.baidubce.com
3Authorization: {authorization}
4Content-Type: application/json; charset=utf-8
5x-bce-date: 2016-06-08T16:49:51Z返回示例
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7
4
5{
6 "metrics": [
7 "cpu_idle",
8 "mem_used"
9 ]
10} 获取field列表
| 方法 | API | 说明 |
|---|---|---|
| GET | /v1/metric/{metric}/field | 获取database中metric的field列表 |
返回参数
| 参数名称 | 参数类型 | 说明 |
|---|---|---|
| fields | Object | field列表，Object的每个key对应一个field的key，Object的每个value都是Object类型的，表示该field的类型 |
请求示例
Plain Text
1GET /v1/metric/wind/field HTTP/1.1
2Host: {database}.tsdb.iot.gz.baidubce.com
3Authorization: {authorization}
4Content-Type: application/json; charset=utf-8
5x-bce-date: 2016-06-08T16:49:51Z返回示例
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7
4
5{
6 "fields": {
7 "power": {
8 "type": "String"
9 },
10 "direction": {
11 "type": "Number"
12 }
13 }
14} 获取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，此为结束时间，默认为263 - 1 |
返回参数
| 参数名称 | 参数类型 | 说明 |
|---|---|---|
| tags | Object | tag列表，Object的每个key对应一个tag的key，Object的每个value都是List<String>类型的，表示该tag的所有value的列表 |
请求示例
Plain Text
1GET /v1/metric/cpu_idle/tag HTTP/1.1
2Host: {database}.tsdb.iot.gz.baidubce.com
3Authorization: {authorization}
4Content-Type: application/json; charset=utf-8
5x-bce-date: 2016-06-08T16:49:51Z返回示例
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7
4
5{
6 "tags": {
7 "host": ["server1", "server2"],
8 "rack": ["rack1", "rack2"]
9 }
10}查询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值 |
| 参数名称 | 参数类型 | 是否必须 | 说明 |
|---|---|---|---|
| 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和其他查询条件冲突，不能同时存在。 |
| 参数名称 | 参数类型 | 是否必须 | 说明 |
|---|---|---|---|
| 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" |
| 参数名称 | 参数类型 | 是否必须 | 说明 |
|---|---|---|---|
| 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时有此项 |
单域请求示例
Plain Text
1PUT /v1/datapoint?query HTTP/1.1
2Host: {database}.tsdb.iot.gz.baidubce.com
3Authorization: {authorization}
4Content-Type: application/json; charset=utf-8
5x-bce-date: 2016-06-08T16:49:51Z
6
7{
8 "queries": [{
9 "metric": "cpu_idle",
10 "field": "test",
11 "filters": {
12 "start": "1 hour ago",
13 "tags": {
14 "host": ["server1", "server2"]
15 },
16 "value": ">= 10"
17 },
18 "groupBy": [{
19 "name": "Tag",
20 "tags": ["rack"]
21 }],
22 "limit": 1000,
23 "aggregators": [{
24 "name": "Sum",
25 "sampling": "10 minutes"
26 }]
27 }],
28 "disablePresampling": false
29} 单域返回示例
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7
4
5{
6 "results": [{
7 "metric": "cpu_idle",
8 "field": "test",
9 "rawCount": 1000,
10 "groups": [{
11 "groupInfos": [{
12 "name": "Tag",
13 "tags": {
14 "rack": "rack1"
15 }
16 }],
17 "values": [
18 [1465718968506, 10],
19 [1465718985346, 12],
20 [1465718992879, 15]
21 ]
22 }],
23 "presamplingRuleId": "21"
24 }]
25}多域请求示例
Plain Text
1PUT /v1/datapoint?query HTTP/1.1
2Host: {database}.tsdb.iot.gz.baidubce.com
3Authorization: {authorization}
4Content-Type: application/json; charset=utf-8
5x-bce-date: 2016-06-08T16:49:51Z
6
7{
8 "queries": [{
9 "metric": "cpu_idle",
10 "fields": ["field1","field2"],
11 "tags": ["rack"],
12 "filters": {
13 "fields": [{
14 "field": "field1",
15 "value": ">= 10"
16 },{
17 "field": "field2",
18 "value": "<= 10"
19 }],
20 "start": "1 hour ago",
21 "tags": {
22 "host": ["server1", "server2"]
23 },
24 },
25 "groupBy": [{
26 "name": "Tag",
27 "tags": ["rack"]
28 }],
29 "limit": 1000,
30 "aggregators": [{
31 "name": "Sum",
32 "sampling": "10 minutes"
33 }]
34 }],
35 "disablePresampling": false
36} 多域返回示例
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7
4
5{
6 "results": [{
7 "metric": "cpu_idle",
8 "fields": ["field1","field2"],
9 "tags": ["rack"],
10 "rawCount": 1000,
11 "groups": [{
12 "groupInfos": [{
13 "name": "Tag",
14 "tags": {
15 "rack": "rack1"
16 }
17 }],
18 "values": [
19 [1465718968506, 10, 1.0, "rack1"],
20 [1465718985346, 12, 2.0, "rack1"],
21 [1465718992879, 15, 11.0, "rack1"]
22 ]
23 }],
24 }]
25}或查询请求示例
Plain Text
1PUT /v1/datapoint?query HTTP/1.1
2Host: {database}.tsdb.iot.gz.baidubce.com
3Authorization: {authorization}
4Content-Type: application/json; charset=utf-8
5x-bce-date: 2016-06-08T16:49:51Z
6
7{
8 "queries": [{
9 "metric": "cpu_idle",
10 "fields": ["field1","field2"],
11 "tags": ["rack"],
12 "filters": {
13 "or": [{
14 "fields": [{
15 "field": "field1",
16 "value": ">= 10"
17 },{
18 "field": "field2",
19 "value": "<= 10"
20 }],
21 "start": "1 hour ago"
22 },{
23 "tags":[{
24 "tag": "rack",
25 "in": ["rack1", "rack2"]
26 }],
27 "start": "2 hour ago"
28 }]
29 },
30 "groupBy": [{
31 "name": "Tag",
32 "tags": ["rack"]
33 }],
34 "limit": 1000,
35 "aggregators": [{
36 "name": "Sum",
37 "sampling": "10 minutes"
38 }]
39 }]
40 "disablePresampling": false
41} 或查询返回示例
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7
4
5{
6 "results": [{
7 "metric": "cpu_idle",
8 "fields": ["field1","field2"],
9 "tags": ["rack"],
10 "rawCount": 1000,
11 "groups": [{
12 "groupInfos": [{
13 "name": "Tag",
14 "tags": {
15 "rack": "rack1"
16 }
17 }],
18 "values": [
19 [1465718968506, 10, 1.0, "rack1"],
20 [1465718985346, 12, 2.0, "rack1"],
21 [1465718992879, 15, 11.0, "rack1"]
22 ]
23 }],
24 }]
25}插值请求示例
Plain Text
1PUT /v1/datapoint?query HTTP/1.1
2Host: {database}.tsdb.iot.gz.baidubce.com
3Authorization: {authorization}
4Content-Type: application/json; charset=utf-8
5x-bce-date: 2016-06-08T16:49:51Z
6
7{
8 "queries": [{
9 "metric": "cpu_idle",
10 "filters": {
11 "start": "1 hour ago"
12 "tags": {
13 "host": ["server1"]
14 }
15 },
16 "fill": {
17 "type": "Linear",
18 "interval": "5 minutes",
19 "maxWriteInterval": "30 minutes"
20 }
21 }]
22}插值返回示例
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7
4
5{
6 "results": [{
7 "metric": "cpu_idle",
8 "field": "value",
9 "rawCount": 2,
10 "groups": [{
11 "groupInfos": [],
12 "values": [
13 [1499072400000, 20.4],
14 [1499072700000, 17.85],
15 [1499073000000, 15.3],
16 [1499073300000, 22.95],
17 [1499073600000, 30.6],
18 [1499073900000, 38.25],
19 [1499074200000, 45.9],
20 [1499074500000, 53.55],
21 [1499074800000, 61.2],
22 [1499075100000, 61.2],
23 [1499075400000, 61.2],
24 [1499075700000, 61.2]
25 ]
26 }]
27 }]
28}标签匹配请求示例
Plain Text
1PUT /v1/datapoint?query HTTP/1.1
2Host: {database}.tsdb.iot.gz.baidubce.com
3Authorization: {authorization}
4Content-Type: application/json; charset=utf-8
5x-bce-date: 2016-06-08T16:49:51Z
6
7{
8 "queries": [{
9 "metric": "cpu_idle",
10 "tags": ["tag1"],
11 "filters": {
12 "start": "1 hour ago"
13 "tags": [{
14 "tag": "tag1",
15 "like": "value%"
16 }]
17 }
18 }]
19}标签匹配返回示例
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7
4
5{
6 "results": [{
7 "metric": "cpu_idle",
8 "field": "value",
9 "tags": ["tag1"],
10 "rawCount": 2,
11 "groups": [{
12 "groupInfos": [],
13 "values": [
14 [1499072400000, 20.4, "value1"],
15 [1499072700000, 17.85, "value2"]
16 ]
17 }]
18 }]
19}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的名称 |
请求示例
Plain Text
1GET /v1/row?sql=select%20%2A%20from%20metric HTTP/1.1
2Host: {database}.tsdb.iot.gz.baidubce.com
3Authorization: {authorization}
4Content-Type: application/json; charset=utf-8
5x-bce-date: 2016-06-08T16:49:51Z 返回示例
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7
4
5{
6 "columns": [{
7 "name": "time"
8 },{
9 "name": "field1",
10 },{
11 "name": "tag1"
12 }],
13 "rows": [
14 [1499072400000, 20.4, "value1"],
15 [1499072700000, 17.85, "value2"]
16 ]
17}