应用编程接口 - REST API - 《Apache IoTDB 用户手册 (V0.13.x)》

RESTful 服务
- 开启RESTful 服务
- 鉴权
- 接口
  - ping
  - query
  - nonQuery
  - insertTablet
- 配置

RESTful 服务

IoTDB 的 RESTful 服务可用于查询、写入和管理操作，它使用 OpenAPI 标准来定义接口并生成框架。

开启RESTful 服务

RESTful 服务默认情况是关闭的

开发者

找到sever模块中org.apache.iotdb.db.conf.rest 下面的IoTDBRestServiceConfig类，修改enableRestService=true即可。 - 使用者

找到IoTDB安装目录下面的conf/iotdb.properties文件，将 enable_rest_service 设置为 true 以启用该模块。

1. enable_rest_service=true

鉴权

除了检活接口 /ping，RESTful 服务使用了基础（basic）鉴权，每次 URL 请求都需要在 header 中携带 'Authorization': 'Basic ' + base64.encode(username + ':' + password)。

示例中使用的用户名为：root，密码为：root，对应的 Basic 鉴权 Header 格式为

1. Authorization: Basic cm9vdDpyb2901

若用户名密码认证失败，则返回如下信息：

HTTP 状态码：401

返回结构体如下

1. { 2. "code": 600, 3. "message": "WRONG_LOGIN_PASSWORD_ERROR" 4. } - 若未设置 Authorization，则返回如下信息：

HTTP 状态码：401

返回结构体如下

1. { 2. "code": 603, 3. "message": "UNINITIALIZED_AUTH_ERROR" 4. }

接口

ping

ping 接口可以用于线上服务检活。

请求方式：GET

请求路径：<http://ip:port/ping>

请求示例：

1. $ curl http://127.0.0.1:18080/ping

返回的 HTTP 状态码：

200：当前服务工作正常，可以接收外部请求。
503：当前服务出现异常，不能接收外部请求。

响应参数：

参数名称	参数类型	参数描述
code	integer	状态码
message	string	信息提示

响应示例：

HTTP 状态码为 200 时：

1. { 2. "code": 200, 3. "message": "SUCCESS_STATUS" 4. } - HTTP 状态码为 503 时：

1. { 2. "code": 500, 3. "message": "thrift service is unavailable" 4. }

/ping 接口访问不需要鉴权。

query

query 接口可以用于处理数据查询和元数据查询。

请求方式：POST

请求头：application/json

请求路径：<http://ip:port/rest/v1/query>

参数说明:

参数名称	参数类型	是否必填	参数描述
sql	string	是
rowLimit	integer	否	一次查询能返回的结果集的最大行数。如果不设置该参数，将使用配置文件的 `rest_query_default_row_size_limit` 作为默认值。当返回结果集的行数超出限制时，将返回状态码 `411`。

响应参数:

参数名称	参数类型	参数描述
expressions	array	用于数据查询时结果集列名的数组，用于元数据查询时为`null`
columnNames	array	用于元数据查询结果集列名数组，用于数据查询时为`null`
timestamps	array	时间戳列，用于元数据查询时为`null`
values	array	二维数组，第一维与结果集列名数组的长度相同，第二维数组代表结果集的一列

请求示例如下所示：

提示:为了避免OOM问题，不推荐使用select * from root.xx.** 这种查找方式。

请求示例表达式查询:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select s3, s4, s3 + 1 from root.sg27 limit 2"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": [
3. "root.sg27.s3",
4. "root.sg27.s4",
5. "root.sg27.s3 + 1"
6. ],
7. "columnNames": null,
8. "timestamps": [
9. 1635232143960,
10. 1635232153960
11. ],
12. "values": [
13. [
14. 11,
15. null
16. ],
17. [
18. false,
19. true
20. ],
21. [
22. 12.0,
23. null
24. ]
25. ]
26. }

请求示例 show child paths:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show child paths root"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "child paths"
5. ],
6. "timestamps": null,
7. "values": [
8. [
9. "root.sg27",
10. "root.sg28"
11. ]
12. ]
13. }

请求示例 show child nodes:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show child nodes root"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "child nodes"
5. ],
6. "timestamps": null,
7. "values": [
8. [
9. "sg27",
10. "sg28"
11. ]
12. ]
13. }

请求示例 show all ttl:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show all ttl"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "storage group",
5. "ttl"
6. ],
7. "timestamps": null,
8. "values": [
9. [
10. "root.sg27",
11. "root.sg28"
12. ],
13. [
14. null,
15. null
16. ]
17. ]
18. }

请求示例 show ttl:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show ttl on root.sg27"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "storage group",
5. "ttl"
6. ],
7. "timestamps": null,
8. "values": [
9. [
10. "root.sg27"
11. ],
12. [
13. null
14. ]
15. ]
16. }

请求示例 show functions:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show functions"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "function name",
5. "function type",
6. "class name (UDF)"
7. ],
8. "timestamps": null,
9. "values": [
10. [
11. "ABS",
12. "ACOS",
13. "ASIN",
14. ...
15. ],
16. [
17. "built-in UDTF",
18. "built-in UDTF",
19. "built-in UDTF",
20. ...
21. ],
22. [
23. "org.apache.iotdb.db.query.udf.builtin.UDTFAbs",
24. "org.apache.iotdb.db.query.udf.builtin.UDTFAcos",
25. "org.apache.iotdb.db.query.udf.builtin.UDTFAsin",
26. ...
27. ]
28. ]
29. }

请求示例 show timeseries:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show timeseries"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "timeseries",
5. "alias",
6. "storage group",
7. "dataType",
8. "encoding",
9. "compression",
10. "tags",
11. "attributes"
12. ],
13. "timestamps": null,
14. "values": [
15. [
16. "root.sg27.s3",
17. "root.sg27.s4",
18. "root.sg28.s3",
19. "root.sg28.s4"
20. ],
21. [
22. null,
23. null,
24. null,
25. null
26. ],
27. [
28. "root.sg27",
29. "root.sg27",
30. "root.sg28",
31. "root.sg28"
32. ],
33. [
34. "INT32",
35. "BOOLEAN",
36. "INT32",
37. "BOOLEAN"
38. ],
39. [
40. "RLE",
41. "RLE",
42. "RLE",
43. "RLE"
44. ],
45. [
46. "SNAPPY",
47. "SNAPPY",
48. "SNAPPY",
49. "SNAPPY"
50. ],
51. [
52. null,
53. null,
54. null,
55. null
56. ],
57. [
58. null,
59. null,
60. null,
61. null
62. ]
63. ]
64. }

请求示例 show latest timeseries:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show latest timeseries"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "timeseries",
5. "alias",
6. "storage group",
7. "dataType",
8. "encoding",
9. "compression",
10. "tags",
11. "attributes"
12. ],
13. "timestamps": null,
14. "values": [
15. [
16. "root.sg28.s4",
17. "root.sg27.s4",
18. "root.sg28.s3",
19. "root.sg27.s3"
20. ],
21. [
22. null,
23. null,
24. null,
25. null
26. ],
27. [
28. "root.sg28",
29. "root.sg27",
30. "root.sg28",
31. "root.sg27"
32. ],
33. [
34. "BOOLEAN",
35. "BOOLEAN",
36. "INT32",
37. "INT32"
38. ],
39. [
40. "RLE",
41. "RLE",
42. "RLE",
43. "RLE"
44. ],
45. [
46. "SNAPPY",
47. "SNAPPY",
48. "SNAPPY",
49. "SNAPPY"
50. ],
51. [
52. null,
53. null,
54. null,
55. null
56. ],
57. [
58. null,
59. null,
60. null,
61. null
62. ]
63. ]
64. }

请求示例 count timeseries:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"count timeseries root.**"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "count"
5. ],
6. "timestamps": null,
7. "values": [
8. [
9. 4
10. ]
11. ]
12. }

请求示例 count nodes:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"count nodes root.** level=2"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "count"
5. ],
6. "timestamps": null,
7. "values": [
8. [
9. 4
10. ]
11. ]
12. }

请求示例 show devices:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show devices"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "devices",
5. "isAligned"
6. ],
7. "timestamps": null,
8. "values": [
9. [
10. "root.sg27",
11. "root.sg28"
12. ],
13. [
14. "false",
15. "false"
16. ]
17. ]
18. }

请求示例 show devices with storage group:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show devices with storage group"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "devices",
5. "storage group",
6. "isAligned"
7. ],
8. "timestamps": null,
9. "values": [
10. [
11. "root.sg27",
12. "root.sg28"
13. ],
14. [
15. "root.sg27",
16. "root.sg28"
17. ],
18. [
19. "false",
20. "false"
21. ]
22. ]
23. }

请求示例 list user:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"list user"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "user"
5. ],
6. "timestamps": null,
7. "values": [
8. [
9. "root"
10. ]
11. ]
12. }

请求示例原始聚合查询:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select count(*) from root.sg27"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": [
3. "count(root.sg27.s3)",
4. "count(root.sg27.s4)"
5. ],
6. "columnNames": null,
7. "timestamps": [
8. 0
9. ],
10. "values": [
11. [
12. 1
13. ],
14. [
15. 2
16. ]
17. ]
18. }

请求示例 group by level:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select count(*) from root.** group by level = 1"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "count(root.sg27.*)",
5. "count(root.sg28.*)"
6. ],
7. "timestamps": null,
8. "values": [
9. [
10. 3
11. ],
12. [
13. 3
14. ]
15. ]
16. }

请求示例 group by:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select count(*) from root.sg27 group by([1635232143960,1635232153960),1s)"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": [
3. "count(root.sg27.s3)",
4. "count(root.sg27.s4)"
5. ],
6. "columnNames": null,
7. "timestamps": [
8. 1635232143960,
9. 1635232144960,
10. 1635232145960,
11. 1635232146960,
12. 1635232147960,
13. 1635232148960,
14. 1635232149960,
15. 1635232150960,
16. 1635232151960,
17. 1635232152960
18. ],
19. "values": [
20. [
21. 1,
22. 0,
23. 0,
24. 0,
25. 0,
26. 0,
27. 0,
28. 0,
29. 0,
30. 0
31. ],
32. [
33. 1,
34. 0,
35. 0,
36. 0,
37. 0,
38. 0,
39. 0,
40. 0,
41. 0,
42. 0
43. ]
44. ]
45. }

请求示例 last:

1. curl -H "Content-Type:application/json"  -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select last s3 from root.sg27"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "expressions": null,
3. "columnNames": [
4. "timeseries",
5. "value",
6. "dataType"
7. ],
8. "timestamps": [
9. 1635232143960
10. ],
11. "values": [
12. [
13. "root.sg27.s3"
14. ],
15. [
16. "11"
17. ],
18. [
19. "INT32"
20. ]
21. ]
22. }

请求示例 disable align:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select * from root.sg27 disable align"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "code": 407,
3. "message": "disable align clauses are not supported."
4. }

请求示例 align by device:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select count(s3) from root.sg27 align by device"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "code": 407,
3. "message": "align by device clauses are not supported."
4. }

请求示例 select into:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select s3, s4 into root.sg29.s1, root.sg29.s2 from root.sg27"}' http://127.0.0.1:18080/rest/v1/query

响应示例:

1. {
2. "code": 407,
3. "message": "select into clauses are not supported."
4. }

nonQuery

请求方式：POST

请求头：application/json

请求路径：<http://ip:port/rest/v1/nonQuery>

参数说明:

参数名称	参数类型	是否必填	参数描述
sql	string	是

请求示例:

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"set storage group to root.ln"}' http://127.0.0.1:18080/rest/v1/nonQuery

响应参数:

参数名称	参数类型	参数描述
code	integer	状态码
message	string	信息提示

响应示例：

1. {
2. "code": 200,
3. "message": "SUCCESS_STATUS"
4. }

insertTablet

请求方式：POST

请求头：application/json

请求路径：<http://ip:port/rest/v1/insertTablet>

参数说明:

参数名称	参数类型	是否必填	参数描述
timestamps	array	是	时间列
measurements	array	是	测点名称
dataTypes	array	是	数据类型
values	array	是	值列，每一列中的值可以为 `null`
isAligned	boolean	是	是否是对齐时间序列
deviceId	boolean	是	设备名称

请求示例：

1. curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"timestamps":[1635232143960,1635232153960],"measurements":["s3","s4"],"dataTypes":["INT32","BOOLEAN"],"values":[[11,null],[false,true]],"isAligned":false,"deviceId":"root.sg27"}' http://127.0.0.1:18080/rest/v1/insertTablet

响应参数：

参数名称	参数类型	参数描述
code	integer	状态码
message	string	信息提示

响应示例：

1. {
2. "code": 200,
3. "message": "SUCCESS_STATUS"
4. }

配置

配置位于 iotdb-rest.properties 中。

将 enable_rest_service 设置为 true 以启用该模块，而将 false 设置为禁用该模块。默认情况下，该值为 false。

1. enable_rest_service=true

仅在 enable_rest_service=true 时生效。将 rest_service_port设置为数字（1025~65535），以自定义REST服务套接字端口。默认情况下，值为 18080。

1. rest_service_port=18080

一次查询能返回的结果集最大行数。当返回结果集的行数超出参数限制时，您只会得到在行数范围内的结果集，且将得到状态码411。

1. rest_query_default_row_size_limit=10000

缓存客户登录信息的过期时间（用于加速用户鉴权的速度，单位为秒，默认是8个小时）

1. cache_expire=28800

缓存中存储的最大用户数量（默认是100）

1. cache_max_num=100

缓存初始容量（默认是10）

1. cache_init_num=10

REST Service 是否开启 SSL 配置，将 enable_https 设置为 true 以启用该模块，而将 false 设置为禁用该模块。默认情况下，该值为 false。

1. enable_https=false

keyStore 所在路径（非必填）

1. key_store_path=

keyStore 密码（非必填）

1. key_store_pwd=

trustStore 所在路径（非必填）

1. trust_store_path=

trustStore 密码（非必填）

1. trust_store_pwd=

SSL 超时时间，单位为秒

1. idle_timeout=5000