请求路径和方法

请求参数

注意：

• 所有“无类型”的参数，只要提供，都被视为 true，比如 summary=false 以及 summary=true 都被当做 summary=true。
• 如果 details 和 summary 都设置，API 将返回 details 信息。

请求内容

数据点格式为 JSON 格式，各参数说明如下：

时间戳说明

本说明适用于读写数据 (/api/put) 和查询数据 (api/query) 两个接口。

时间戳的单位可以是秒或者毫秒。TSDB 会通过数值大小来判断时间戳的单位，规则如下：

• 时间戳区间为 [4294768,9999999999]: 判断为秒，表示的时间区间为: [1970-02-20 00:59:28, 2286-11-21 01:46:39]
• 时间戳区间为 [10000000000,9999999999999]：判断为毫秒，表示的时间区间为: [1970-04-27 01:46:40.000, 2286-11-21 01:46:39.999]
• 时间戳区间为 (-∞,4294768)和(9999999999999,+∞)：判断为非法时间戳区间

数据点值说明

• 同一时间线只允许写入同一种数据类型
• String数值类型的数据值可以为任意字符，支持JSON字符串存储，最大为20KB

Tags说明

• 向一条时间线写入数据时，其Tagkey的个数存在上限。根据TSDB实例规格不同，Tagkey的个数上限如下所示：

写入数据示例

请求：POST/api/put

请求体：

[
    {
        "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"
        }
    },
    {
        "metric": "sys.cpu.alter",
        "timestamp": 1346846400,
        "value": "High CPU Load",
        "tags": {
           "host": "web03",
           "dc": "lga"
        }
    },
    {
        "metric": "sys.cpu.nice",
        "timestamp": 1346846400,
        "value": true,
        "tags": {
           "host": "web04",
           "dc": "lga"
        }
    }
]

响应说明

如果所有数据点写入成功，返回码为204，如果有部分写入失败，返回码400，响应内容为具体错误信息。

如果请求参数包含 summary 或者 details，返回信息包括如下属性：

响应示例

指定 summary 的响应示例：

请求：POST/api/put?summary

请求体：

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

响应内容：

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

表示0个点写入成功，1个点写入失败。

指定 details 的返回示例：

请求：POST/api/put?details

请求体：

    [
        {
                      "metric": "sys.cpu.nice",
                      "timestamp": 1365465600,
                      "value": "NaN",
                      "tags": {
                          "host": "web01"
                      }
        }
    ]

响应内容：

    {
        "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
    }

表示0个点写入成功，1个点写入失败。失败的点由 datapoint 指定。该点写入失败的原因由 error 字段指定。