时序数据读写接口
更新时间:2024-10-11
Write接口
描述
向bucket中写入时序数据。
请求
uri | /api/v2/write | |
Verb | POST | |
Header | ||
Query参数 | ||
Body | line protol格式的数据 | curl --request POST \ "https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/write?bucket=YOUR_BUCKET&precision=us" \   --header "Authorization: IAM认证串" \    --header "DataBase: database名称" \    --header "Content-Type: text/plain; charset=utf-8" \    --header "Accept: application/json" \   --data-binary '      airSensors,sensor_id=TLM0201 temperature=73.97,humidity=35.231032,co=0.484493615 1630424257000000      airSensors,sensor_id=TLM0202 temperature=75.30,humidity=35.651929,co=0.514105826 1630424257000000' |
写入数据格式
- line protocol基本组成
注:如果field set有多个field,每个field会被解析成一个point,如上面这行写入,会被解析成以下两个point
measurement,tag1=val1,tag2=val2 field1="v1" 1694505151372
measurement,tag1=val1,tag2=val2 field2=1i 1694505151372
组成项 | required/optional | 数据类型 | |
---|---|---|---|
measurement | required | String | |
tagset | tag key | optional | String |
tag value | optional | String | |
field set | field key | required | String |
field value | required | Float | Integer | UInteger | String | Boolean | |
timestamp | optional(如不提供,将使用后端系统时间戳) | Unix timestamp |
- 数据类型
数据类型 | 说明 | 示例 |
---|---|---|
Float | 64位 IEEE-754 浮点数字,支持科学计数法 | 1.0、1、-1.234456e+78 |
Integer | 64位有符号整数,数字后加上i进行标识 | 1i、12485903i、-12485903i |
UInteger | 64位无符号整数,数字后加上u进行标识 | 1u、12485903u |
String | 字符串,长度限制64KB | ""fieldVal"", ""123"" |
Boolean | 布尔类型变量 | True:t, T, true, True, TRUE False:f, F, false, False, FALSE |
响应
定义 | 示例 |
---|---|
成功无响应体,响应码204 | - |
失败响应 |
{ "code":"unauthorized", "message": "unauthorized access" } |
响应码
响应码 | 定义 | 响应内容 |
---|---|---|
204 | 写入请求已经queue进队列,会异步进行写入,不代表写入已经完成 | 无 |
400 | Bad Request | code按具体错误来定 message按具体错误来定 |
401 | Unauthorized | "code": "unauthorized", message按具体错误来定 |
404 | Not Found | "code": "not found" message按具体错误来定 |
413 | 请求体过大 | "code":"request too large" message按具体错误来定 |
429 | 请求过多 | "code": "too many requests", <message按具体错误来定> |
500 | 服务内部错误 | "code": "internal error" message按具体错误来定 |
503 | 服务暂不可用 响应中的Retry-After头域会展示下次可写的时间 |
"code": "service unavailable", message按具体错误来定 |
请求示例
POST /api/v2/write?bucket=a387d62200000049&precision=us HTTP/1.1
Authorization: bce-auth-v1/{table-access-key}/2024-09-05T07:13:39Z/1800/content-type;database;host;x-bce-date/{signature}
Content-Type: text/plain; charset=utf-8
DataBase: test1
Host: bts.yq.baidubce.com
x-bce-date: 2024-09-05T07:13:39Z
electricityMeter,device=d1001 current=53.1792,voltage=286,phase=0.957236 1725520419709028
electricityMeter,device=d1002 current=30.8156,voltage=246,phase=0.256283 1725520419709028
electricityMeter,device=d1003 current=64.3472,voltage=242,phase=0.975878 1725520419709028
响应示例
HTTP/1.1 204 No Content
Date: Thu, 05 Sep 2024 07:13:39 GMT
Content-Type: text/plain; charset=utf-8
x-bce-request-id: c98e427f-8284-4756-9e87-c491fcffcd6e
Query接口
描述
根据特定条件读取时序数据。
Flux格式
采用Flux语句查询
请求
uri | /api/v2/query | |
Verb | POST | |
Header | ||
Body | application/vnd.flux(flux查询) | curl --request POST \ https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/query \ --header 'Authorization: IAM认证串' \ --header "DataBase: database名称" \ --header 'Accept: application/csv' \ --header 'Content-type: application/vnd.flux' \ --data 'from(bucket:"example-bucket")       |> range(start: -12)       |> filter(fn: (r) => r._measurement == "example-measurement")       |> aggregateWindow(every: 1h, fn: mean)' |
application/vnd.influxql(influx查询) | SELECT voltage FROM electricityMeter WHERE time >= '2023-12-20T5:37:32Z' |
SQL格式
采用SQL语句查询
请求
uri | /api/v2/query | |
Verb | POST | |
Query参数 | db | bucket |
请求头参数 | Accept | string |
Content-Type | string |
|
Authorization | IAM认证串 | |
请求体 | q | 要执行的sql sql格式:q = "SELECT fields/* from $measurement [ where ][ group_by ] [ order_by ] [ limit ][ offset ] [ slimit ] [ soffset ] [ timezone ] " 特别说明:  1. 当前暂不支持group by, order by, limit, offset, slimit, soffset, timezone等语句  2. 使用tag value作为where查询条件的时候,必须显示指定tagkey的类型,例如:SELECT field1 FROM measurement WHERE cpu::tag=k2  3. 带时间范围的查询示例:     a. SELECT voltage FROM electricityMeter WHERE time >= '2023-12-20T5:37:32Z'     b. SELECT voltage FROM electricityMeter WHERE time >= '2023-12-20T5:37:32Z' AND time < NOW()     c. SELECT voltage FROM electricityMeter WHERE time >= '2023-12-20T5:37:32Z' AND time < '2023-12-20T5:38:12Z'     d. SELECT voltage FROM electricityMeter WHERE device::tag = 'd1002' AND time >= '2023-12-20T5:37:32Z'     e. SELECT voltage FROM electricityMeter WHERE device::tag = 'd1002' AND time >= '2023-12-20T5:37:32Z' AND time < now()     f. SELECT voltage FROM electricityMeter WHERE device::tag = 'd1002' AND time >= '2023-12-20T5:37:32Z' AND time < '2023-12-20T5:38:12Z' |
响应
定义 | 示例 |
---|---|
成功响应 | 见下【查询数据格式】 |
失败响应 |
{ "code": "unauthorized", "message": "unauthorized access" } |
查询数据格式
一期我们用csv作为返回格式
一个table内部Row返回顺序规则
每个table内部由一个表头+多条Row组成,表头和Row都满足csv格式,一个table对应唯一一个满足用户Query条件的Series,在给定时间范围内的多条Row组成,且按照时间戳从小到大排列
_result | table_index | start_time | stop_time | time | value | field_name | measurement_name | tagvalue |
固定值 | 从0开始的table序号 | 用户指定的起始时间戳 | 用户指定的截止时间戳 | 写入时间戳 | field_key对应的field_value | field_key 只有一个 |
具体measurement | 跟表头的tagkey一一对应,可多个 |
示例:
,result,table,_start,_stop,_time,_value,_field,_measurement,cpu
,_result,5,2023-08-09T03:42:51.38409928Z,2023-09-08T03:42:51.38409928Z,2023-09-08T03:39:25.265674349Z,1,value1,measurementTest,cpu3
,_result,5,2023-08-09T03:42:51.38409928Z,2023-09-08T03:42:51.38409928Z,2023-09-08T03:39:45.032854422Z,2,value1,measurementTest,cpu3
,_result,5,2023-08-09T03:42:51.38409928Z,2023-09-08T03:42:51.38409928Z,2023-09-08T03:40:30.430551015Z,3,value1,measurementTest,cpu3
响应码
响应码 | 定义 | 响应内容 |
---|---|---|
200 | 成功 | 见上述【查询数据格式】 |
400 | Bad Request | code:按具体错误来定 |
401 | Unauthorized | "code"": "unauthorized" "message": "unauthorized access" |
404 | Not Found | "code": "not found" message按具体错误来定 |
429 | 请求过多 | "code": "too many requests" message按具体错误来定 |
500 | 服务内部错误 | "code"": "internal error" message按具体错误来定 |
请求示例,Flux语句查询
POST /api/v2/query?db=test1 HTTP/1.1
Accept: application/csv
Authorization: bce-auth-v1/{table-access-key}/2024-09-05T07:26:04Z/1800/accept;content-type;database;host;x-bce-date/{signature}
Content-Length: {payloadSizeBytes}
Content-Type: application/vnd.flux
DataBase: test1
Host: bts.yq.baidubce.com
x-bce-date: 2024-09-05T07:26:04Z
from (bucket: "test1")
|> range(start:2024-09-05T07:26:03Z)
|> filter(fn: (r) => r["_field"] == "voltage")
请求示例,SQL语句查询
POST /api/v2/query?db=test1 HTTP/1.1
Accept: application/csv
Authorization: bce-auth-v1/{table-access-key}/2024-09-05T07:26:04Z/1800/accept;content-type;database;host;x-bce-date/{signature}
Content-Length: {payloadSizeBytes}
Content-Type: application/vnd.influxql
DataBase: test1
Host: bts.yq.baidubce.com
x-bce-date: 2024-09-05T07:26:04Z
q=SELECT voltage FROM electricityMeter WHERE time >= '2024-09-05T07:26:03Z'
响应示例
HTTP/1.1 200 OK
Date: Thu, 05 Sep 2024 07:26:04 GMT
Content-Type: text/csv; charset=utf-8
Content-Length: {resultSize}
x-bce-request-id: 3127eeb8-1bdd-4129-b2b0-072d2d00442f
,result,table,_start,_stop,_time,_value,_field,_measurement,
,_result,0,2024-09-05T07:26:03.000000000Z,2024-09-05T07:26:04.144064000Z,2024-09-05T07:26:03.714251000Z,23.000000,voltage,electricityMeter
,_result,0,2024-09-05T07:26:03.000000000Z,2024-09-05T07:26:04.144064000Z,2024-09-05T07:26:03.714252000Z,169.000000,voltage,electricityMeter
,_result,0,2024-09-05T07:26:03.000000000Z,2024-09-05T07:26:04.144064000Z,2024-09-05T07:26:03.714253000Z,92.000000,voltage,electricityMeter
,_result,0,2024-09-05T07:26:03.000000000Z,2024-09-05T07:26:04.144064000Z,2024-09-05T07:26:03.714254000Z,130.000000,voltage,electricityMeter
,_result,0,2024-09-05T07:26:03.000000000Z,2024-09-05T07:26:04.144064000Z,2024-09-05T07:26:03.714255000Z,244.000000,voltage,electricityMeter