全部产品

写入数据

请求路径和方法

请求路径

请求方法

描述

/api/put

POST

一次写入多个数据点。

请求参数

名称

类型

是否必需

描述

默认值

举例

summary

无类型

是否返回摘要信息。

false

/api/put?summary

details

无类型

是否返回详细信息。

false

/api/put?details

sync_timeout

Integer

超时时间,单位毫秒,0为永不超时。

0

/api/put/?sync&sync_timeout=60000

ignoreErrors

无类型

是否忽略部分数据点的写入异常。

false

/api/put/?ignoreErrors

注意

  • 所有“无类型”的参数,只要提供,都被视为 true,比如 summary=false 以及 summary=true 都被当做 summary=true。

  • 如果 details 和 summary 都设置,API 将返回 details 信息。

请求内容

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

名称

类型

是否必需

是否有使用限制

描述

举例

metric

String

只可包含大小写英文字母、中文、数字,以及特殊字符 -_./():,[]=#

存储的指标名

sys.cpu。

说明

高可用版本支持的metric长度最多为255字节。

timestamp

Long

时间戳;单位为秒或者毫秒,判断规则详见下面的时间戳说明

1499158925

value

Long,Double,String,Boolean

数据点值

42.5, true

tags

Map

可以包含大小写英文字母、中文、数字,以及特殊字符 -_./():,[]=#

Tagk 和 Tagv 是字符串键值对,至少一个键值对

{“host”:”web01”},非字符串类型的tagk,tagv会强制转换为字符串类型

时间戳说明

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

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

  • 时间戳区间为 [4294968,4294967295]: 判断为秒,表示的时间区间为:[1970-02-20 01:02:48, 2106-02-07 14:28:15]。

  • 时间戳区间为 [4294967296,9999999999999]:判断为毫秒,表示的时间区间为:[1970-02-20 01:02:47.296, 2286-11-21 01:46:39.999]。

  • 时间戳区间为 (-∞,4294968)和(9999999999999,+∞):判断为非法时间戳区间。

数据点值说明

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

Tags说明

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

实例规格

单时间线 Tagkey 数上限(个)

mLarge

16

Large

16

3xLarge

20

4xLarge

20

6xLarge

20

12xLarge

20

24xLarge

24

48xLarge

24

96xLarge

24

写入数据示例

请求: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,返回信息包括如下属性:

名称

数据类型

描述

success

Integer

写入成功的数据点数。

failed

Integer

未写入的数据点数。

errors

Array

一个描述哪些数据点未写入以及其原因的数组,仅在指定 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 字段指定。