RestAPI V1

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

注意：自 V2.0.8.2 版本起，TimechoDB 安装包中默认不包含 REST 服务的 JAR 包，请使用该服务前联系天谋团队获取相应的 JAR 包，并放置于 timechodb_home/lib 或者 timechodb_home/ext/external_service 路径下。

1. 开启 RESTful 服务

Restful 服务默认情况是关闭的，开启 restful 功能需要找到 IoTDB 安装目录下的conf/iotdb-system.properties文件，将 enable_rest_service 设置为 true ，然后重启 datanode 进程。

 enable_rest_service=true

2. 鉴权

除了检活接口 /ping，RESTful 服务均使用基础（Basic）鉴权，所有请求都需要在 Header 中携带 Authorization 信息。

鉴权格式

Authorization: Basic <base64串>

其中 <base64串> 是 用户名:密码 直接做 Base64 编码的结果，其快速生成方式如下

Linux/macOS

echo -n "你的用户名:你的密码" | base64
eg: echo -n "root:TimechoDB@2021" | base64

Windows

# PowerShell
[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("用户名:密码"))
eg: [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("root:TimechoDB@2021"))

# CMD
powershell "[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"用户名:密码\"))"
eg: powershell "[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"root:TimechoDB@2021\"))"

鉴权示例

默认用户名 root，密码 TimechoDB@2021：

拼接字符串：root:TimechoDB@2021
Base64 编码后为：cm9vdDpUaW1lY2hvREJAMjAyMQ==
最终 Header：

Authorization: Basic cm9vdDpUaW1lY2hvREJAMjAyMQ==

错误说明

用户名/密码错误：返回 HTTP 状态码 801，内容：

{"code":801,"message":"WRONG_LOGIN_PASSWORD"}

未设置 Authorization：返回 HTTP 状态码 800，内容：

{"code":800,"message":"INIT_AUTH_ERROR"}

3. 接口定义

3.1 ping

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

请求方式：GET

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

请求示例：

curl http://127.0.0.1:18080/ping

返回的 HTTP 状态码：

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

响应参数：

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

响应示例：

HTTP 状态码为 200 时：

{  "code": 200,  "message": "SUCCESS_STATUS"}

HTTP 状态码为 503 时：

{  "code": 500,  "message": "thrift service is unavailable"}

注意：ping 接口访问不需要鉴权。

3.2 查询接口

请求地址：/rest/table/v1/query
请求方式：post
Request 格式

请求头:application/json

请求参数说明

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

Response 格式

参数名称	参数类型	参数描述
column_names	array	列名
data_types	array	每一列的类型
values	array	二维数组，第一维与结果集所有行，第二维数组代表结果集的每一行，每一个元素为一列，长度与column_names的长度相同。

请求示例

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"database":"test","sql":"select s1,s2,s3 from test_table"}' http://127.0.0.1:18080/rest/table/v1/query

响应示例：

{
    "column_names": [
        "s1",
        "s2",
        "s3"
    ],
    "data_types": [
        "STRING",
        "BOOLEAN",
        "INT32"
    ],
    "values": [
        [
            "a11",
            true,
            2024
        ],
        [
            "a11",
            false,
            2025
        ]
    ]
}

3.3 非查询接口

请求地址：/rest/table/v1/nonQuery
请求方式：post
Request 格式
- 请求头:application/json
- 请求参数说明

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

Response 格式

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

请求示例

#创建数据库
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"create database test","database":""}' http://127.0.0.1:18080/rest/table/v1/nonQuery
#在test库中创建表test_table
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"CREATE TABLE table1 (time TIMESTAMP TIME,region STRING TAG,plant_id STRING TAG,device_id STRING TAG,model_id STRING ATTRIBUTE,maintenance STRING ATTRIBUTE,temperature FLOAT FIELD,humidity FLOAT FIELD,status Boolean FIELD,arrival_time TIMESTAMP FIELD) WITH (TTL=31536000000)","database":"test"}' http://127.0.0.1:18080/rest/table/v1/nonQuery

响应示例：

{
  "code": 200,
  "message": "SUCCESS_STATUS"
}

3.4 批量写入接口

请求地址：/rest/table/v1/insertTablet
请求方式：post
Request 格式

请求头:application/json

请求参数说明

参数名称	参数类型	是否必填	参数描述
database	string	是	数据库名称
table	string	是	表名
column_names	array	是	列名
column_categories	array	是	列类别(TAG,FIELD,ATTRIBUTE)
data_types	array	是	数据类型
timestamps	array	是	时间列
values	array	是	值列，每一列中的值可以为 `null`二维数组第一层长度跟timestamps长度相同。第二层长度跟column_names长度相同

Response 格式

响应参数:

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

请求示例

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"database":"test","column_categories":["TAG","FIELD","FIELD"],"timestamps":[1739702535000,1739789055000],"column_names":["s1","s2","s3"],"data_types":["STRING","BOOLEAN","INT32"],"values":[["a11",true,2024],["a11",false,2025]],"table":"test_table"}' http://127.0.0.1:18080/rest/table/v1/insertTablet

响应示例

{
  "code": 200,
  "message": "SUCCESS_STATUS"
}

4. 配置

配置文件位于 iotdb-system.properties 中。

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

enable_rest_service=true

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

rest_service_port=18080

将 ‘enable_swagger’ 设置 ‘true’ 启用swagger来展示rest接口信息, 而设置为 ‘false’ 关闭该功能. 默认情况下，该值为 false。

enable_swagger=false

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

rest_query_default_row_size_limit=10000

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

cache_expire_in_seconds=28800

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

cache_max_num=100

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

cache_init_num=10

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

enable_https=false

keyStore 所在路径（非必填）

key_store_path=

keyStore 密码（非必填）

key_store_pwd=

trustStore 所在路径（非必填）

trust_store_path=""

trustStore 密码（非必填）

trust_store_pwd=""

SSL 超时时间，单位为秒

idle_timeout_in_seconds=5000