阿里云首页 时序数据库 TSDB

写入数据

请求路径和方法

请求路径

请求方法

描述

/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"
}
}
]

写入模式及其响应内容

根据写入时指定请求参数,TSDB支持四种模式的写入,分别如下所示:

  • 极简模式

    写入时在 api/put 后不带任何参数。此时TSDB写入成功会返回 204 表示成功; 写入失败时会返回错误码以及对应的错误消息,但不会带更多信息。

    适用于一般性的业务监控数据上报的场景。

  • 统计模式

    写入时在 api/put 后带上 summary 。此时TSDB写入成功或失败时会按下述响应内容返回成功的数据点数和失败的数据点数方便业务端进行统计

    名称

    数据类型

    描述

    success

    Integer

    写入成功的数据点数

    failed

    Integer

    未能成功写入的数据点数

    示例如下:

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

    注意

    在统计模式下。对于一个 api/put 请求中写入的一批数据,要么全部成功;要么全部失败。失败时返回的 failed 本质就是该批次的全部数据点数。

    该模式适用于一般性业务监控数据上报时对于上报数据存在统计需求时的场景。

  • 详细模式

    本质上是上述统计模式的扩展模式。写入时在 api/put 后带上 details。 此时TSDB写入或失败时,会按下述响应内容返回成功的数据点数以及导致失败的直接原因。

    名称

    数据类型

    描述

    success

    Integer

    写入成功的数据点数。

    failed

    Integer

    未写入的数据点数。

    errors

    Array

    描述引起写入失败直接原因的数组。其中只会包含第一个引发失败的数据点及其失败原因

    示例如下:

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

    注意

    在详细模式下。对于一个 api/put 请求中写入的一批数据,仍然是要么全部成功;要么全部失败。而且返回的errors中只会返回第一个引发失败的数据点及其失败原因(直接原因),该批次的其他数据点不会包含在 errors 中,只会体现在统计信息 failed

    该模式适用于业务监控数据上报时对于上报数据存在统计需求且需要失败定位时的场景。

  • 容错模式

    写入时在 api/put 后带上 ignoreErrors。 此时TSDB写入时,会保证一个请求的一批数据中尽量写入。即使这个批次中存在一些非法数据时,对于其他合法数据尽力写入成功。返回时,会将该批次数据中写入失败的数据全部返回。返回的响应内容和指定 details 时相同,只是此时通过 errors 字段返回的将是该一批次数据中所有的失败数据,未被返回的数据可以认为写入成功。

    名称

    数据类型

    描述

    success

    Integer

    写入成功的数据点数。

    failed

    Integer

    未写入的数据点数。

    errors

    Array

    描述该批次数据中所有未能成功写入的数据点数组及其各自的失败原因。

    示例如下:

    注意

    在容错模式下,一个批次中存在部分数据写入失败时,TSDB响应的返回码仍然是 200。除非发生因底层存储异常等严重错误导致全量数据失败时,才会返回200以外的返回码。该模式下返回的failed 就是真实失败的数据点数

    该模式适用于业务监控数据上报时对于上报数据的完整性存在需求,对于失败数据希望进行修复重试时的场景。