功能介绍

向OpenTSDB数据库中写入数据，支持在一个请求中将多个数据写入OpenTSDB，多个数据之间可以不相关，每个数据都会被单独处理，其中一条数据出现错误不会影响其他数据的写入。但如果一个请求中有大量数据点，则API可能需要很长时间才能响应。

URI

• URI格式
  1. 写入数据

     POST {OpenTSDB URL}/api/put

  2. 写入数据并返回概要信息

     POST {OpenTSDB URL}/api/put?summary

  3. 写入数据并返回详细信息

     POST {OpenTSDB URL}/api/put?details

     说明：

     如果summary和details标志同时存在于查询字符串，该API将响应detailed信息。

  4. 写入数据并等待数据刷入磁盘

     POST {OpenTSDB URL}/api/put?sync

     说明：

     强烈建议使用sync参数，否则API将不会等待数据写入成功即返回响应，存在数据丢失的风险。

  5. 写入数据等待数据刷入磁盘，并设置超时时间（毫秒）。当发生超时时，使用details标志将会返回成功和失败的数据点数量。

     POST {OpenTSDB URL}/api/put?sync&sync_timeout=60000

请求

• 请求样例：单数据点写入

  {
      "metric": "sys.cpu.nice",
      "timestamp": 1346846400,
      "value": 18,
      "tags": {
         "host": "web01",
         "dc": "lga"
      }
  }

• 请求样例：多数据点写入

  [
      {
          "metric": "sys.cpu.nice",
          "timestamp": 1346846400,
          "value": 18,
          "tags": {
             "host": "web01",
             "dc": "lga"
          }
      },
      {
          "metric": "sys.cpu.nice",
          "timestamp": 1346846400,
          "value": 9,
          "tags": {
             "host": "web02",
             "dc": "lga"
          }
      }
  ]

• 参数说明

  表1 请求参数说明

  属性名	类型	是否必须	描述	限制
  metric	String	是	指标项名	只能包含大小写英文字母，数字，“-”，“_”，“.”，“/”这些Unicode字符。 不允许包含空格及其它字符。 区分大小写。
  timestamp	Integer	是	时间戳，单位：秒	以秒为单位的Unix/POSIX Epoch时间戳，从1970年1月1日00:00:00 UTC时间起经过的秒数。 说明： 时间戳建议使用4334400秒到4291718400秒之间的时间，即从1970/02/20 12:00:00到2106/01/01 00:00:00。 必须是整数。 不能超过13位数。
  value	Integer,Long,Double,Boolean	是	数据值	整数，单精度浮点数（Float），双精度（Double）浮点数或者布尔值。
  tags	Map	是	Tagk和Tagv的键值对	只能包含大小写英文字母，数字，“-”，“_”，“.”，“/”这些Unicode字符。 不允许包含空格及其它字符。 区分大小写。 最少1个，最多8个Tagk和TagV的键值对。

响应

• 响应样例： summary

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

  响应样例：details

  {
      "errors": [
          {
              "datapoint": {
                  "metric": "sys.cpu.nice",
                  "timestamp": 1365465600,
                  "value": "NaN",
                  "tags": {
                      "host": "web01"
                  }
              },
              "error": "Unable to parse value to a number"
          }
      ],
      "failed": 1,
      "success": 0
  }

• 参数说明

  表2 返回信息的属性

  名称	类型	描述
  success	Integer	写入成功的数据点数量
  failed	Integer	写入失败的数据点数量
  errors	Array	写入失败的具体数据点的值及原因，仅在details参数下生效

状态码

状态码请参见响应码