请求路径和方法

请求路径 请求方法 描述
/api/put POST 一次写入多个数据点。

请求参数

名称 类型 是否必需 描述 默认值 举例
summary 无类型 是否返回摘要信息 false /api/put?summary
details 无类型 是否返回详细信息 false /api/put?details
sync_timeout Integer 超时时间,单位毫秒,0为永不超时 0 /api/put/?sync&sync_timeout=60000
注意
  • 所有“无类型”的参数,只要提供,都被视为 true,比如 summary=false 以及 summary=true 都被当做 summary=true。
  • 如果 details 和 summary 都设置,API 将返回 details 信息。

请求内容

数据点格式为 JSON 格式,各参数说明如下:

名称 类型 是否必需 是否有使用限制 描述 举例
metric String 只可包含大小写英文字母、中文、数字,以及特殊字符 -_./():,[]=‘# 存储的指标名 sys.cpu
timestamp Long 时间戳;单位为秒或者毫秒,判断规则详见下面的时间戳说明。 1499158925
value Long,Double,String,Boolean 数据点值 42.5, true
tags Map 可以包含大小写英文字母、中文、数字,以及特殊字符 -_./():,[]=‘# Tagk 和 Tagv 是字符串键值对,至少一个键值对 {“host”:”web01”},非字符串类型的tagk,tagv会强制转换为字符串类型
时间戳说明
本说明适用于读写数据(/api/put)和查询数据(api/query) 两个接口。时间戳的单位可以是秒或者毫秒。时序引擎可以通过数值大小来判断时间戳的单位,规则如下:
  • 时间戳区间为 [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,+∞):判断为非法时间戳区间。
数据点值说明

在写入数据类型的约束方面,采用metric的方式限定数据类型。比如下述两批次的写入是被允许的。这是因为两批次数据虽然都包含不相同的etric,因此允许写入不同的数据类型。

1.  [{"metric":"fakemetric1", "tags":{"tagk":"tagv1"},"timestamp":1514736000, "value":"val"}, {"metric":"fakemetric1", "tags":{"tagk":"tagv1"},"timestamp":1514736030, "value":"val2"}]
2.  [{"metric":"fakemetric2", "tags":{"tagk":"tagv2"},"timestamp":1514736000, "value":12.34}, {"metric":"fakemetric2", "tags":{"tagk":"tagv2"},"timestamp":1514736030, "value":34.56}]

String数值类型的数据值可以为任意字符,支持JSON字符串存储,最大为20KB。

Tags说明

向一条时间线写入数据时,其Tagkey的个数存在上限。根据时序引擎实例规格不同,Tagkey的个数上限如下所示:

实例规格 单时间线 Tagkey 数上限(个)
mLarge 16
Large 16
3xLarge 20
4xLarge 20
6xLarge 20
12xLarge 20
24xLarge 24
48xLarge 24
96xLarge 24

写入数据示例

请求: POST /api/put
请求体:
1. [
2.    {
3.        "metric": "sys.cpu.nice",
4.        "timestamp": 1346846400,
5.        "value": 18,
6.        "tags": {
7.           "host": "web01",
8.           "dc": "lga"
9.        }
10.    },
11.    {
12.        "metric": "sys.cpu.nice",
13.        "timestamp": 1346846400,
14.        "value": 9,
15.        "tags": {
16.           "host": "web02",
17.           "dc": "lga"
18.        }
19.    },
20.    {
21.        "metric": "sys.cpu.alter",
22.        "timestamp": 1346846400,
23.        "value": "High CPU Load",
24.        "tags": {
25.           "host": "web03",
26.           "dc": "lga"
27.        }
28.    },
29.    {
30.        "metric": "sys.cpu.nice",
31.        "timestamp": 1346846400,
32.        "value": true,
33.        "tags": {
34.           "host": "web04",
35.           "dc": "lga"
36.        }
37.    }
38. ]

响应说明

如果所有数据点写入成功,返回码为204,如果有部分写入失败,返回码400,响应内容为具体错误信息。如果请求参数包含 summary 或者 details,返回信息包括如下属性:
名称 数据类型 描述
success Integer 写入成功的数据点数
failed Integer 未写入的数据点数
Array 一个描述哪些数据点未写入以及其原因的数组,仅在指定 details 有效。
响应示例

指定 summary 的响应示例:

请求:POST /api/put?summary

请求体:

1. [
2.    {
3.        "metric": "sys.cpu.nice",
4.        "timestamp": 1346846400,
5.        "value": 9,
6.        "tags": {
7.           "host": "web02",
8.           "dc": "lga"
9.        }
10.  }
11. ]
响应内容:
1.   {
2.        "failed": 1,
3.        "success": 0
4.    }

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

指定 details 的返回示例:

请求: POST /api/put?details

请求体:

1.    [
2.        {
3.                      "metric": "sys.cpu.nice",
4.                      "timestamp": 1365465600,
5.                      "value": "NaN",
6.                      "tags": {
7.                          "host": "web01"
8.                      }
9.        }
10.    ]
响应内容:
1.    {
2.        "errors": [
3.            {
4.                "datapoint": {
5.                    "metric": "sys.cpu.nice",
6.                    "timestamp": 1365465600,
7.                    "value": "NaN",
8.                    "tags": {
9.                        "host": "web01"
10.                    }
11.                },
12.                "error": "Unable to parse value to a number"
13.            }
14.        ],
15.        "failed": 1,
16.        "success": 0
17.    }

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