时序数据读写
更新时间：2025-08-21
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按具体错误来定 |
请求示例
Plain Text
1POST /api/v2/write?bucket=a387d62200000049&precision=us HTTP/1.1
2Authorization: bce-auth-v1/{table-access-key}/2024-09-05T07:13:39Z/1800/content-type;database;host;x-bce-date/{signature}
3Content-Type: text/plain; charset=utf-8
4DataBase: test1
5Host: bts.yq.baidubce.com
6x-bce-date: 2024-09-05T07:13:39Z
7
8electricityMeter,device=d1001 current=53.1792,voltage=286,phase=0.957236 1725520419709028
9electricityMeter,device=d1002 current=30.8156,voltage=246,phase=0.256283 1725520419709028
10electricityMeter,device=d1003 current=64.3472,voltage=242,phase=0.975878 1725520419709028响应示例
Plain Text
1HTTP/1.1 204 No Content
2Date: Thu, 05 Sep 2024 07:13:39 GMT
3Content-Type: text/plain; charset=utf-8
4x-bce-request-id: c98e427f-8284-4756-9e87-c491fcffcd6eQuery接口
描述
根据特定条件读取时序数据。
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一一对应，可多个 |
示例：
Plain Text
1,result,table,_start,_stop,_time,_value,_field,_measurement,cpu
2,_result,5,2023-08-09T03:42:51.38409928Z,2023-09-08T03:42:51.38409928Z,2023-09-08T03:39:25.265674349Z,1,value1,measurementTest,cpu3
3,_result,5,2023-08-09T03:42:51.38409928Z,2023-09-08T03:42:51.38409928Z,2023-09-08T03:39:45.032854422Z,2,value1,measurementTest,cpu3
4,_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语句查询
Plain Text
1POST /api/v2/query?db=test1 HTTP/1.1
2Accept: application/csv
3Authorization: bce-auth-v1/{table-access-key}/2024-09-05T07:26:04Z/1800/accept;content-type;database;host;x-bce-date/{signature}
4Content-Length: {payloadSizeBytes}
5Content-Type: application/vnd.flux
6DataBase: test1
7Host: bts.yq.baidubce.com
8x-bce-date: 2024-09-05T07:26:04Z
9
10from (bucket: "test1")
11 |> range(start:2024-09-05T07:26:03Z)
12 |> filter(fn: (r) => r["_field"] == "voltage")请求示例，SQL语句查询
Plain Text
1POST /api/v2/query?db=test1 HTTP/1.1
2Accept: application/csv
3Authorization: bce-auth-v1/{table-access-key}/2024-09-05T07:26:04Z/1800/accept;content-type;database;host;x-bce-date/{signature}
4Content-Length: {payloadSizeBytes}
5Content-Type: application/vnd.influxql
6DataBase: test1
7Host: bts.yq.baidubce.com
8x-bce-date: 2024-09-05T07:26:04Z
9
10q=SELECT voltage FROM electricityMeter WHERE time >= '2024-09-05T07:26:03Z'响应示例
Plain Text
1HTTP/1.1 200 OK
2Date: Thu, 05 Sep 2024 07:26:04 GMT
3Content-Type: text/csv; charset=utf-8
4Content-Length: {resultSize}
5x-bce-request-id: 3127eeb8-1bdd-4129-b2b0-072d2d00442f
6
7,result,table,_start,_stop,_time,_value,_field,_measurement,
8,_result,0,2024-09-05T07:26:03.000000000Z,2024-09-05T07:26:04.144064000Z,2024-09-05T07:26:03.714251000Z,23.000000,voltage,electricityMeter
9,_result,0,2024-09-05T07:26:03.000000000Z,2024-09-05T07:26:04.144064000Z,2024-09-05T07:26:03.714252000Z,169.000000,voltage,electricityMeter
10,_result,0,2024-09-05T07:26:03.000000000Z,2024-09-05T07:26:04.144064000Z,2024-09-05T07:26:03.714253000Z,92.000000,voltage,electricityMeter
11,_result,0,2024-09-05T07:26:03.000000000Z,2024-09-05T07:26:04.144064000Z,2024-09-05T07:26:03.714254000Z,130.000000,voltage,electricityMeter
12,_result,0,2024-09-05T07:26:03.000000000Z,2024-09-05T07:26:04.144064000Z,2024-09-05T07:26:03.714255000Z,244.000000,voltage,electricityMeter