所有文档

          时序时空数据库 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"
                  },
                  "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,此为结束时间,默认为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接口说明