本文已参与「新人创作礼」活动，一起开启掘金创作之路。

HTTP API

由于OpenTSDB没有支持Java的SDK进行调用，所以基于Java开发OpenTSDB的调用将要依靠HTTP请求的方式进行。下面就先介绍下部分HTTP API的特性：

数据写入

写入特性

• 为了节省传输带宽，提高传输效率，该接口可以实现批量写入多个属于不同时序的点；
• 写入请求处理时 ，毫无关系的点分开单独处理，即使其中一个点存储失败，也不会影响其他点的保存；
• 一次请求的点过多，响应请求的速度会变慢。当HTTP请求体的大小超过一定限制，可以进行分块传输（Chunked Transfer），OpenTSDB可以通过对 tsd.http.request.enable_chunked 的配置设置为true（默认为false），即可使OpenTSDB 支持 HTTP 的 Chunked Transfer Encoding。
• tsd.mode 的配置对写入操作有影响，配置 ro 表示只读状态，配置 rw 表示读写状态，当写入操作一直失败时，可以确认此配置项。

写入请求可选参数

• /api/put：根据 url 参数的不同，可以选择是否获取详细的信息。
  • 通过POST方式插入数据，JSON格式，例如

  {
      "metric":"self.test", 
      "timestamp":1456123787, 
      "value":20, 
      "tags":{
          "host":"web1"
      }
  }
  

• /api/put?summary：返回写入操作的概述信息（包括失败和成功的个数）

  {
      "failed": 0,
      "success": 1
  }
  

• /api/put?details：返回写入操作的详细信息

  {
      "errors": [],
      "failed": 0,
      "success": 1
  }
  

• /api/put?sync：写入操作为同步写入，即所有点写入完成（成功或失败）才向客户端返回响应，默认为异步写入。
• /api/put?sync_timeout：同步写入的超时时间。

查询数据

• /api/query：可以选择 Get 或者 Post 两种方式，推荐使用 Post 方式，

  • 请求JSON 格式

  {
      "start": 1456123705,        // 该查询的起始时间
      "end": 1456124985,          // 该查询的结束时间
      "globalAnnotation": false,  // 查询结果中是否返回 global annotation
      "noAnnotations": false,     // 查询结果中是否返回 annotation
      "msResolution": false,      // 返回的点的精度是否为毫秒级，如果该字段为false，
      						    // 则同一秒内的点将按照 aggregator 指定的方式聚合得到该秒的最终值
      "showTSUIDs": true,         // 查询结果中是否携带 tsuid
      "showQuery": true,          // 查询结果中是否返回对应的子查询
      "showSummary": false,       // 查询结果中是否携带此次查询时间的一些摘要信息
      "showStats": false,         // 查询结果中是否携带此次查询时间的一些详细信息
      "delete": false,            // 注意:如果该值设为true，则所有符合此次查询条件的点都会被删除
      "queries": [
         // 子查询，为一个数组，可以指定多条相互独立的子查询
      ]
  }
  

  • Metric Query 类型子查询：指定完整的 metric、tag 及聚合信息。
    • metric 和 tags 是用于过滤的查询条件。

  {
  	"metric": "JVM_Heap_Memory_Usage_MB",	// 查询使用的 metric
  	"aggregator": "sum",					// 使用的聚合函数
  	"downsample": "30s-avg",				// 采样时间间隔和采样函数
  	"tags": {								// tag组合，在OpenTSDB 2.0 中已经标记为废弃
  											// 推荐使用下面的 filters 字段
  		"host": "server01"
  	},
  	"filters": [],							// TagFilter，下面将详细介绍 Filter 相关的内容
  	"explicitTags": false,					// 查询结果是否只包含 filter 中出现的 tag
  	"rate": false,							// 是否将查询结果转换成 rate
  	"rateOption": {}						// 记录了 rate 相关的参数，具体参数后面会进行介绍
  	
  }
  

  • TSUIDS Query 类型子查询（可看做 Metric Query 的优化）：指定一条或多条 tsuid，不再指定 metric、tag 等。

  {
  	"aggregator": "sum", 	// 使用的聚合函数
  	"tsuids": [				// 查询的 tsuids 集合，这里的 tsuids 可理解为
  							// 时序数据库的 id
  		"123",
  		"456"
  	]
  }
  

  • 返回字符串也为json格式

  [
      {
          "metric": "self.test",
          "tags": {},
          "aggregateTags": [
              "host"
          ],
          "dps": {
              "1456123785": 10,
              "1456123786": 10
          }
      },
      {
          "metric": "self.test",
          "tags": {
              "host": "web1"
          },
          "aggregateTags": [],
          "dps": {
              "1456123784": 10,
              "1456123786": 15
          }
      }
  ]