数据写入接口

获取Token

在IoT时序数据库系统中我们加入了身份校验功能,因此在数据写入操作执行前,需要获得当前执行人的身份验证。以下为获取Token接口的详细介绍,相关代码可以参照示例工程HttpTsdAccessor类。

URL: /api/auth/token=token

请求类型: POST

请求头: Content-Type: application/x-www-form-urlencoded

请求参数列表:

名称 数据类型 Required 描述 示例
username String Required 用户名称 user_091
password String Required 密码 123456

响应:JSON类型

名称 数据类型 描述
token String 访问令牌

示例:

curl -l –H "Content-Type:application/x-www-form-urlencoded" -X POST "http://localhost:4242/api/auth/token?username=usr_01&password=password_01"

时序数据入库

以下为时序数据入库接口详细介绍,相关代码可参照示例工程PutData类。

URL: /api/put

请求类型: POST

请求参数列表:

名称 数据类型 Required 描述 默认值 QS 示例
summary Present Optional 是否返回summary信息 false summary /api/put?summary
details Present Optional 是否返回详细信息 false details /api/put?details
sync Boolean Optional 在返回结果之前是否等待数据刷写到存储 false sync /api/put?sync
sync_timeout Integer Optional 超时,单位毫秒,在返回错误之前等待数据刷写到存储的超时时长。当超时发生时,使用details标签将会告诉你多少数据点失败以及多少数据点成功。必须给定sync参数,此参数才会产生影响。值0意味着写不会超时。 0 sync_timeout /api/put/?sync&sync_timeout=60000
名称 数据类型 Required 描述 RW 示例
metric String Required 要存储的指标名称 W sys.cpu.nice
timestamp Integer Required Unix epoch风格的时间戳,毫秒或者秒级。时间戳不能包含非数字字符 W 1365465600
value Integer, Float, String Required 记录当前此数据点的值。它可能被引用或不被引用,并且必须符合OpenTSDB的值规则:../../user_guide/writing W 42.5
tags Map Required 标签名称/标签值对的映射。至少必须提供一对。 W {"host":"web01"}

响应:

名称 数据类型 描述
success Integer 成功排队等待存储的数据点的数量
failed Integer 无法排队存储的数据点的数量
error array 排队失败的数据点的列表,以及为什么。details只出现在响应中。

示例:

curl -l -H "Content-type: application/json" -H "Authorization: bearer token_value0001" -X POST -d '{"metric":"sys.cpu.user","timestamp":1346846400, "value":69,"tags":{"host":"webserver01","cpu":"0"}}' http://localhost:4242/api/put

数据查询接口

HTTP API查询

同数据写入时一样,在做数据查询前仍需要获取Token,在此对于接口不再介绍。查询接口为OpenTSDB提供的Qurey接口,以下为接口介绍。详细代码可参照示例工程QueryData类。

URL: /api/query

请求类型: POST

主要参数列表:

名称 数据类型 Required 描述 默认值 QS 示例
start String, Integer Required 查询数据的开始时间 start 1h-ago
end String, Integer Optional 查询数据的结束时间 当前时间 end 1s-ago
queries Array Required 一个或多个子查询用于选择要返回的时间序列。 m or tsuids 参照queries参数列表

Queries参数列表

名称 数据类型 Required 描述 示例
aggregator String Required 使用聚合函数名称。 sum
metric String Required 查询数据指标名称。 sys.cpu.0
tags Map Optional 查询数据标签名称。 "tags": { "host": "web*", "dc": "lga" }
filters List Optional 对于得到的查询数据进行过滤
downsample String Optional 利用此功能减少数据返回的数量 5m-avg

响应:

名称 描述
metric 检索数据指标名称
tags 检索数据标签名称
aggregateTags 检索时采用的聚合函数
DPS 检索得到的数据,由时间戳和值组成

示例:

curl -l -H "Content-type: application/json" -H "Authorization: bearer token_value0001" -X POST -d '{"start":1529980200, "queries":[{"aggregator":"none","metric":"sys.cpu.user","tags":{"host":"webserver01","cpu":"0"}}]}' http://localhost:4242/api/query