KairosDB REST API

KairosDB REST API提供了对一系列已存在的指标名、标记名和值、存储指标数据点和查询指标数据点的操作。

可以通过制定的指标名称和时间范围来查询数据点，并可以任选一个或多个标记。查询可以对数据进行处理操作，如聚合，平均值，最小值和最大值的计算。

所有的POST值和返回信息都以JSON格式表示。

添加数据点

方法：POST

地址：http://[host]:[port]/api/v1/datapoints

如果使用压缩，需要设置内容类型为application/gzip。

body格式：

描述：

• name: 指标名必需唯一。
• datapoints：数据点的数组。每个数据点包含一个时间戳和值。
• tags：标记字段是一系列属性列表。至少需要一个标记。当查询指标时，使用标记缩小查询。
• type: 类型识别自定义数据类型。

返回结果：

• 成功：返回204，不包含内容。
• 失败：如果请求无效返回400 Bad Request。
  如果发生错误返回500 Internal Server Error
  
  { "errors": [ "Connect to 10.92.4.1:4242 timed out" ] }

  1 2 3 4 5

  {      "errors" : [        "Connect to 10.92.4.1:4242 timed out"      ]    }

删除数据点

对指定的查询的数据点执行删除操作。聚合和分组不受影响。

删除设计的目的是，执行查询验证返回的数据点是否正常，对有问题的数据点删除。

注意：删除操作只对Cassandra和H2存储有效。

方法：POST

地址：http://[host]:[port]/api/v1/datapoints/delete

body格式：一个查询操作

返回结果：

• 成功：返回204，不包含内容。
• 失败：如果请求无效返回400 Bad Request。
  如果发生错误返回500 Internal Server Error
  
  { "errors": [ "Connect to 10.92.4.1:4242 timed out" ] }

  1 2 3 4 5

  {      "errors" : [        "Connect to 10.92.4.1:4242 timed out"      ]    }

删除指标

删除指定的指标以及与其相关的数据点。

只对Cassandra和H2数据库有效。

方法：DELETE

地址：http://[host]:[port]/api/v1/metric/{metric_name}

body格式：None

返回结果：

• 成功：返回204，不包含内容。
• 失败：如果请求无效返回400 Bad Request。
  如果发生错误返回500 Internal Server Error
  
  { "errors": [ "Connect to 10.92.4.1:4242 timed out" ] }

  1 2 3 4 5

  {      "errors" : [        "Connect to 10.92.4.1:4242 timed out"      ]    }

列出所有指标名

方法：GET

地址：http://[host]:[port]/api/v1/metricnames

body格式：None

返回结果：

成功返回200和查询结果。

列出所有标记名

方法：GET

地址：http://[host]:[port]/api/v1/tagnames

body格式：None

返回结果：

成功返回200和查询结果。

列出所有标记值

方法：GET

地址：http://[host]:[port]/api/v1/tagvalues

body格式：None

返回结果：

成功返回200和查询结果。

查询指标

返回基于一系列标准指标值的列表，也返回一系列的所有标记和标记值的数据点。

时间范围内可以以绝对或相对时间值来指定。绝对时间值，以毫秒为单位。相对时间值被指定为整数持续时间和单位。单位有：“milliseconds”, “seconds”, “minutes”, “hours”, “days”, “weeks”, “months”, “years”。结束时间是可选的。如果不指定结束时间，结束时间被假定为现在。

grouping

查询的结果可以被组合在一起。有三种方式对数据进行分组：tags、time range、value。时间范围或值的分组可以减缓查询。

Aggregators

Filtering

通过制定的标记来进行数据过滤。返回的数据将只包含有指定标签的相关数据点。

方法：POST

地址：http://[host]:[port]/api/v1/datapoints/query

body格式：

查询属性：

必须指定start_absolute或start_relative，但不能同时使用。

cache_time：查询结果缓存周期。如果相同的查询在缓存周期内，将从缓存中返回数据。

指标属性：

name: 返回数据点的指标名称。必需的。

aggregators：这是聚合的有序数组。如果没有指定聚合器，则所有的数据点被返回。默认聚合器有：avg、dev、histogram、least_squares、max、min、rate、sum。

所有聚合允许缩减像素采样，除了rate和div。

缩减像素采样可以让你减少数据点的采样率和在一段较长的时间聚集这些值。 缩减像素采样值是一个整数值，单位有："milliseconds", "seconds", "minutes", "hours", "days", "weeks", "months", "years"。

tags: 标记缩小搜索范围。仅仅指标包含该标记并且匹配其中的值则被返回。可选的。

group_by：所得到的数据点可以由一个或多个标记，时间范围，值，或由这三种的组合进行分组。

在查询中的“GROUP_BY”属性的一个或多个分组的数组。每个分组有一个名称和附加属性。

exclude_tags：默认情况下，查询的结果包括与数据点相关联的标记和标记值。如果exclude_tags为true，标记将排除在外。

结果返回：

• 成功：返回200代码
  
  { "queries": [ { "sample_size": 14368, "results": [ { "name": "abc_123", "group_by": [ { "name": "tag", "tags": [ "host" ], "group": { "host": "server1" } } ], "tags": { "host": [ "server1" ], "type": [ "bar" ] }, "values": [ [ 1364968800000, 11019 ], [ 1366351200000, 2843 ] ] } ] } ] }

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41

  {      "queries" : [          {              "sample_size" : 14368 ,              "results" : [                  {                      "name" : "abc_123" ,                      "group_by" : [                          {                              "name" : "tag" ,                              "tags" : [                                  "host"                              ] ,                              "group" : {                                  "host" : "server1"                              }                          }                      ] ,                      "tags" : {                          "host" : [                              "server1"                          ] ,                          "type" : [                              "bar"                          ]                      } ,                      "values" : [                          [                              1364968800000 ,                              11019                          ] ,                          [                              1366351200000 ,                              2843                          ]                      ]                  }              ]          }      ] }

• 失败：
  如果请求无效返回400 Bad Request
  如果检索数据发生错误返回500 Internal Server Error
  
  { "errors": [ "metrics[0].aggregate must be one of MIN,SUM,MAX,AVG,DEV", "metrics[0].sampling.unit must be one of SECONDS,MINUTES,HOURS,DAYS,WEEKS,YEARS" ] }

  1 2 3 4 5 6

  {        "errors" : [            "metrics[0].aggregate must be one of MIN,SUM,MAX,AVG,DEV" ,            "metrics[0].sampling.unit must be one of  SECONDS,MINUTES,HOURS,DAYS,WEEKS,YEARS"        ]    }

 查询指标标记

仅仅返回标记信息。

目前，不能在HBase数据库上实现。

Filtering：通过指定的标记来过滤返回标记。

方法：POST

地址：http://[host]:[port]/api/v1/datapoints/query/tags

body格式：

查询属性：必须指定start_absolute或start_relative，但不能同时使用。同样，可以指定任一end_absolute或end_relative，但不能同时使用。如果未指定任一结束时间则当是当前时间。

指标属性：

name: 返回指定指标的数据点。必需的。

tags：缩小搜索范围，仅返回指标包含该标记并匹配该值。可选的。

返回结果：

• 成功：
  
  { "results": [ { "name": "abc_123", "tags": { "host": ["server1","server2"], "type": ["bar"] } }, { "name": "xyz_123", "tags": { "host": ["server1","server2"], "type": ["bar"] } } ] }

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

  {        "results" : [            {                "name" : "abc_123" ,                "tags" : {                    "host" : [ "server1" , "server2" ] ,                    "type" : [ "bar" ]                }            } ,            {                "name" : "xyz_123" ,                "tags" : {                    "host" : [ "server1" , "server2" ] ,                    "type" : [ "bar" ]                }            }        ]    }

• 失败：
  如果请求无效返回400 Bad Request.
  如果检索数据发生错误返回500 Internal Server Error

 版本信息

返回KairosDB版本信息。

方法：GET

地址：http://[host]:[port]/api/v1/version

body格式：None

返回结果：

• 成功：
  
  { "version": "KairosDB 0.9.4" }

  1 2 3

  {    "version" : "KairosDB 0.9.4" }

转载请注明：成长的对话 » KairosDB REST API