全部产品
弹性计算 会员服务 网络 安全 移动云 数加·大数据分析及展现 数加·大数据应用 管理与监控 云通信 阿里云办公 培训与认证 智能硬件
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 更多
高性能时间序列数据库 HiTSDB

写入数据

更新时间:2018-06-01 16:04:45

请求路径和方法

请求路径 请求方法 描述
/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”}

时间戳说明

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

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

  • 时间戳区间为 [4284768,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]
  • 时间戳区间为 (-∞,4284768)和(9999999999999,+∞):判断为非法时间戳区间

数据点值说明

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

写入数据示例

请求: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 未写入的数据点数
errors 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 字段指定。

本文导读目录