全部产品
云市场

单值数据写入

更新时间:2019-12-27 10:56:10

请求路径和方法

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

请求内容

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

名称 类型 是否必需 是否有使用限制 描述 举例
metric String 可以包含大小写英文字母、中文、数字,以及特殊字符 - _ . / ( ) : , [ ] = ' # 存储的指标名 sys.cpu
tags Map 可以包含大小写英文字母、中文、数字,以及特殊字符 - _ . / ( ) : , [ ] = ' # TagK 和 TagV 是字符串键值对,至少一个键值对 {"host":"web01"},非字符串类型的 TagK 和 TagV 会强制转换为字符串类型
timestamp Long 时间戳;单位为秒或者毫秒,判断规则详见下面的时间戳说明 1499158925
value Long, Double, String, Boolean 数据点值 42.5, true

时间戳说明

本说明适用于读写数据(/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 字符串存储,默认最大为 32766 Bytes

Tags 说明

  • 向一条时间线写入数据时,其 TagK 的个数存在上限,默认最大为 1000

写入数据示例

请求: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": 10,
  33. "tags": {
  34. "host": "web04",
  35. "dc": "lga"
  36. }
  37. }
  38. ]

响应说明

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