写入数据
功能介绍
向OpenTSDB数据库中写入数据，支持在一个请求中将多个数据写入OpenTSDB，多个数据之间可以不相关，每个数据都会被单独处理，其中一条数据出现错误不会影响其他数据的写入。但如果一个请求中有大量数据点，则API可能需要很长时间才能响应。
URI
- URI格式
- 写入数据
POST {OpenTSDB URL}/api/put
- 写入数据并返回概要信息
POST {OpenTSDB URL}/api/put?summary
- 写入数据并返回详细信息
POST {OpenTSDB URL}/api/put?details
说明：
如果summary和details标志同时存在于查询字符串，该API将响应detailed信息。
- 写入数据并等待数据刷入磁盘
POST {OpenTSDB URL}/api/put?sync
说明：
强烈建议使用sync参数，否则API将不会等待数据写入成功即返回响应，存在数据丢失的风险。
- 写入数据等待数据刷入磁盘，并设置超时时间（毫秒）。当发生超时时，使用details标志将会返回成功和失败的数据点数量。
POST {OpenTSDB URL}/api/put?sync&sync_timeout=60000
- 写入数据
请求
- 请求样例：单数据点写入
{ "metric": "sys.cpu.nice", "timestamp": 1346846400, "value": 18, "tags": { "host": "web01", "dc": "lga" } } - 请求样例：多数据点写入
[ { "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" } } ] - 参数说明
表1 请求参数说明 属性名
类型
是否必须
描述
限制
metric
String
是
指标项名
- 只能包含大小写英文字母，数字，“-”，“_”，“.”，“/”这些Unicode字符。
- 不允许包含空格及其它字符。
- 区分大小写。
timestamp
Integer
是
时间戳，单位：秒
- 以秒为单位的Unix/POSIX Epoch时间戳，从1970年1月1日00:00:00 UTC时间起经过的秒数。
说明：
时间戳建议使用4334400秒到4291718400秒之间的时间，即从1970/02/20 12:00:00到2106/01/01 00:00:00。
- 必须是整数。
- 不能超过13位数。
value
Integer,Long,Double,Boolean
是
数据值
整数，单精度浮点数（Float），双精度（Double）浮点数或者布尔值。
tags
Map
是
Tagk和Tagv的键值对
- 只能包含大小写英文字母，数字，“-”，“_”，“.”，“/”这些Unicode字符。
- 不允许包含空格及其它字符。
- 区分大小写。
- 最少1个，最多8个Tagk和TagV的键值对。
响应
- 响应样例： summary
{ "failed": 1, "success": 0 }响应样例：details
{ "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 } - 参数说明
表2 返回信息的属性 名称
类型
描述
success
Integer
写入成功的数据点数量
failed
Integer
写入失败的数据点数量
errors
Array
写入失败的具体数据点的值及原因，仅在details参数下生效
状态码
状态码请参见响应码
上一篇： OpenTSDB API简介
下一篇： 查询数据
