时序时空数据库TSDB

    数据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,是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"
            },
            "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?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的列表

    请求示例

    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 可选 结束时间,可以是绝对时间或者是相对时间,默认为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 放在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接口说明