请求路径和方法
请求路径 | 请求方法 | 描述 |
---|---|---|
/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的方式限定数据类型。比如下述两批次的写入是被允许的。这是因为两批次数据虽然都包含不相同的metric,因此允许写入不同的数据类型。
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字符串存储,最大为20 KB。
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 | 未写入的数据点数 |
details | 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字段指定。