8.2 OpenTSDB API
8.2.1 OpenTSDB API 简介
OpenTSDB提供了基于HTTP或HTTPS的应用程序接口。请求方式是通过向资源对应的 路径发送标准的HTTP请求，请求包含GET、POST方法。它的接口与开源OpenTSDB保 持一致，请参见https://opentsdb.net/docs/build/html/api_http/index.html。
请求以及响应实体的类型为：application/JSON 请求以及响应实体的编码为：ISO-8859-1
说明
HTTP协议本身有安全风险，HTTPS是安全协议，建议使用HTTPS连接方式。
OpenTSDB的常用API主要有：
●
写入数据
●
查询数据
●
查询first数据
●
查询last数据
●
管理数据生命周期
获取 OpenTSDB 链接地址
在调用OpenTSDB API之前，请先按照如下步骤获取OpenTSDB链接地址：
登录表格存储服务管理控制台，在左侧导航树单击“集群模式”，选中需要访问的集 群并单击集群名称，进入集群基本信息页面，在“集群信息”区域下方找到
“OpenTSDB链接地址”，如下图所示：
图
8-1 OpenTSDB 链接地址
8.2.2 写入数据
功能介绍
向OpenTSDB数据库中写入数据，支持在一个请求中将多个数据写入OpenTSDB，多 个数据之间可以不相关，每个数据都会被单独处理，其中一条数据出现错误不会影响 其他数据的写入。但如果一个请求中有大量数据点，则API可能需要很长时间才能响 应。
URI
● URI格式 a. 写入数据
POST {OpenTSDB URL}/api/put b. 写入数据并返回概要信息
POST {OpenTSDB URL}/api/put?summary c. 写入数据并返回详细信息
POST {OpenTSDB URL}/api/put?details 说明
如果summary和details标志同时存在于查询字符串，该API将响应detailed信息。
d. 写入数据并等待数据刷入磁盘
POST {OpenTSDB URL}/api/put?sync 说明
强烈建议使用sync参数，否则API将不会等待数据写入成功即返回响应，存在数据丢 失的风险。
e. 写入数据等待数据刷入磁盘，并设置超时时间（毫秒）。当发生超时时，使 用details标志将会返回成功和失败的数据点数量。
POST {OpenTSDB URL}/api/put?sync&sync_timeout=60000
请求
● 请求样例：单数据点写入
{ "metric": "sys.cpu.nice", "timestamp": 1346846400,
"value": 18,
属性名 类型 是否必
tags Map 是 Tagk和Tagv
的键值对 ● 只能包含大小写英文字
success Integer 写入成功的数据点数量 failed Integer 写入失败的数据点数量
errors Array 写入失败的具体数据点的值及原因，仅在details参数 下生效
状态码
POST {OpenTSDB URL}/api/query
请求
start Integer 是 起始时间，单位秒。查询结果包含该时 间的值。
说明建议使用4334400秒到4291718400秒之间 的时间，即从1970/02/20 12:00:00到 2106/01/01 00:00:00，也可以为0。否则可 能导致查询结果不正确。
名称 类型 是否
queries Array 是 可以有多个查询，请参见表8-4。
delete Boolean 否 如果为true,符合条件的查询结果数据都 会被删除。
说明
删除数据是以一小时的数据为单位的。即 查询结果关联的所有小时的数据都会被删 除。
noAnnotations Boolean 否 是否返回注释信息。
● true：不返回。
showTSUIDs Boolean 否 是否在结果中返回与时间序列关联的 TSUID。
showSummary Boolean 否 是否在结果中返回时间摘要，详细信息 请参见https://opentsdb.net/docs/
名称 类型 是否 必须
描述
showStats Boolean 否 是否在结果中返回详细时间，详细信息 请参见https://opentsdb.net/docs/
build/html/user_guide/query/
stats.html
● true：返回。
● false：不返回。
默认为false。
showQuery Boolean 否 是否返回带查询结果的原始子查询。
● true：返回。
● false：不返回。
默认为false。
msResolution Boolean 否 默认情况下，查询结果中的时间戳是以 秒为单位的。如果设置为true，则查询 结果中的时间戳以毫秒为单位。
returnCount Boolean 否 是否返回查询结果的数量。
● true：返回。
● false：不返回。
默认值为false。
reverse Boolean 否 是否以时间倒序的方式返回查询结果。
● true：是。
● false：否。
默认值为false。
onlyDelete Boolean 否 ● true：符合查询条件的结果数据都 会被删除，但不返回查询结果。
● false：该参数无效。
默认值为false。
returnBoolean Boolean 否 是否将查询返回的“value”数据值转 换为布尔值。
● true：是，如果“value”数据值大 于0，则转换为true，如果
“value”数据值等于或小于0，则 转换为false。
● false：否。
默认值为false。
表
8-4 子查询参数说明
名称 类型 是否必
须
描述
aggregator String 是 聚合函数，请参见•aggregator说明。
metric String 是 指标项。
rate Boolean 否 是否返回倾斜率。
● true：返回。
● false：不返回。
默认为false。
downsample String 否 降时间精度采样，请参见
•downsample说明。
filters List 否 过滤器，可以设置多个过滤器，每个 过滤器的格式请参见•filter参数说明。
explicitTags Boolean 否 是否只返回filter指定的tag。
● true：返回。
● false：不返回。
默认为false。
useMultiGets Boolean 否 是否使用MultiGet方式查询数据，默 认为false。只有当“filters”的
“type”为“literal_or”，同时
“explicitTags”为“true”时才会起 作用。
valueFilter String 否 指定值过滤的表达式。请参见
•valueFilter说明。
– “Interval” ：时间数值，“units”为时间单位，s秒，m分，h小时，d天。
示例：1h ， 30m， 24h
– “aggregator” ：聚合策略，将一段时间点聚合为一个数据点的策略。参见
•aggregator说明。
– “fill policy” : 补值策略，当使用aggregator计算一段时间内的汇聚值时，
遇到中间缺少的数据点时，会使用一定的策略补充数据。补值策略请参见表
8-5。
表
8-5 补值策略参数
算子 描述 补值方式 ep99r3 用R-3方法计算的99%都
大于
线性插值
ep99r7 用R-7方法计算的99%都 大于
线性插值
ep999r3 用R-3方法计算的99.9%
都大于
线性插值
ep999r7 用R-7方法计算的99.9%
都大于
线性插值
first 取第一个值
-last 取最后一个值
-mimmin 最小值 补最大值
mimmax 最大值 补最小值
min 最小值 线性插值
max 最大值 线性插值
none 不做计算 补0
p50 50%的值都大于 线性插值
p75 75%的值都大于 线性插值
p90 90%的值都大于 线性插值
p95 95%的值都大于 线性插值
p99 99%的值都大于 线性插值
p999 99.9%的值都大于 线性插值
sum 求和 线性插值
zimsum 求和 补0
说明
R-3，R-7 method见https://en.wikipedia.org/wiki/Quantile。
●
filter参数说明
表
8-7 filter 参数
名称 类型 是否必
须
描述 示例
type String 是 filter类型，参见表8-8 regexp
名称 类型 是否必 须
描述 示例
tagk String 是 要做filter的tag名 host
filter String 是 filter的表达式值 web[0-9]+.la x.mysite.com groupBy Boolea
n 否 是否对tagv做groupBy，默
认false false
not_key tagk不等于 {"type":"not_key","tagk":"host","filter"
:"","groupBy":false}
●
valueFilter说明
根据设置的数值条件表达式，对最终的返回数据点进行过滤。支持 ">", "<", "=",
"<=", ">=", "!=","&&","||"等操作符。
其中 ">", "<", "=", "<=", ">=", "!=",都是单目操作符，用于操作数字；"&&","||"是 双目操作符，用于操作表达式。
表达式例子如下：
a. 只返回value大于或等于10的的结果：>=10
名称 描述 globalAnnotation
s 时间跨度内的全局注释
count 如果查询请求中设置了“returnCount”为“true”，那么
“count”才会返回，表示查询结果的数量。
状态码
状态码请参见响应码。