写入数据

更新时间： 2019/05/07 21:37

功能介绍

向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参数下生效