IoTDB REST API V2 全量指南：开箱即用的HTTP接口，查询+写入+管理一站式搞定

如果你想用最简单的方式对接 IoTDB，不想引入各种SDK、不管什么语言、设备还是前端页面都能直接调用，那 REST API 绝对是最通用的方案。IoTDB REST V2 基于 OpenAPI 标准，支持数据查询、元数据查询、批量写入、库表管理，开箱即用、跨语言无敌。

这篇文章把开启服务、鉴权、所有接口、curl示例、返回格式、配置调优一次性讲全，复制就能用。

---

一、先开启 REST 服务

REST 服务默认关闭，先打开配置：

文件：conf/iotdb-system.properties

enable_rest_service=true
rest_service_port=18080

重启 IoTDB 即可。

---

二、统一鉴权（必看）

除了 /ping 以外，所有接口都需要 Basic 认证。

格式：

Authorization: Basic 【base64(username:password)】

默认账号：
root/root → base64 后是：

Authorization: Basic cm9vdDpyb290

认证失败会返回：

• 401 + code:600 密码错误
• 401 + code:603 没带认证头

---

三、接口总览

IoTDB REST V2 就 5 个核心接口，记牢就行：

1. /ping —— 服务检活
2. /rest/v2/query —— 查询（数据+元数据）
3. /rest/v2/nonQuery —— 执行DDL/DML（无结果）
4. /rest/v2/insertTablet —— 批量按列写入（高性能）
5. /rest/v2/insertRecords —— 批量按行写入

---

四、接口详解 + 直接可用 curl

4.1 /ping —— 检活

curl http://127.0.0.1:18080/ping

正常返回：

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

---

4.2 /rest/v2/query —— 万能查询

POST，支持所有 IoTDB SQL 查询：

• 普通查询
• 聚合查询
• 时序查询、设备查询
• show 指令
• count 统计

请求格式：

{
  "sql": "select s3,s4 from root.sg27 limit 2",
  "row_limit": 1000
}

curl 示例：

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

常用查询 SQL 我给你整理好了：

-- 数据查询
select * from root.sg27 limit 10

-- 元数据查询
show timeseries
show devices
show child paths root
show all ttl
show functions
count timeseries root.**
count nodes root.** level=2
list user

查询返回结构统一：

• expressions：查询表达式（数据查询）
• column_names：列名（元数据查询）
• timestamps：时间戳数组
• values：二维数组，每一列是一组值

---

4.3 /rest/v2/nonQuery —— 执行SQL（无结果集）

用来执行：

• CREATE DATABASE
• CREATE TIMESERIES
• DELETE TIMESERIES
• SET TTL
• INSERT 单条

curl 示例：

curl -H "Content-Type:application/json" \
-H "Authorization:Basic cm9vdDpyb290" \
-X POST \
-d '{"sql":"CREATE DATABASE root.test"}' \
http://127.0.0.1:18080/rest/v2/nonQuery

返回：

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

---

4.4 /rest/v2/insertTablet —— 高性能批量写入（推荐）

按列写入，IoTDB 最优写入方式，适合设备批量上报。

请求体：

{
  "timestamps": [1635232143960, 1635232153960],
  "measurements": ["s3","s4"],
  "data_types": ["INT32","BOOLEAN"],
  "values": [[11,null],[false,true]],
  "is_aligned": false,
  "device": "root.sg27"
}

curl 示例：

curl -H "Content-Type:application/json" \
-H "Authorization:Basic cm9vdDpyb290" \
-X POST \
-d '{
"timestamps":[1635232143960,1635232153960],
"measurements":["s3","s4"],
"data_types":["INT32","BOOLEAN"],
"values":[[11,null],[false,true]],
"is_aligned":false,
"device":"root.sg27"
}' \
http://127.0.0.1:18080/rest/v2/insertTablet

---

4.5 /rest/v2/insertRecords —— 批量多行写入

支持多设备、多测点、多行一起写。

请求体结构：

{
  "timestamps": [1635232113960, 1635232151960],
  "measurements_list": [["s33","s44"],["s55","s66"]],
  "data_types_list": [["INT32","INT64"],["FLOAT","DOUBLE"]],
  "values_list": [[1,11],[2.1,2]],
  "is_aligned": false,
  "devices": ["root.s1","root.s1"]
}

---

五、REST 完整配置（调优必备）

# 启用 REST
enable_rest_service=true

# 端口
rest_service_port=18080

# 启用 swagger 文档
enable_swagger=false

# 查询最大返回行数
rest_query_default_row_size_limit=10000

# 登录缓存过期时间（秒）
cache_expire=28800

# HTTPS
enable_https=false
key_store_path=
key_store_pwd=
trust_store_path=
trust_store_pwd=

---

六、不支持的 SQL（直接返回 407）

这些语法暂时不支持，避免踩坑：

• disable align
• align by device
• select into

---

七、最佳实践（超级实用）

1. 前端/低代码/网页对接 → 用 REST
2. 设备批量上报 → insertTablet
3. 管理操作 → nonQuery
4. 大屏/可视化 → query
5. 跨语言通用 → 首选 REST
6. 千万不要用 select * from root.xx.** 容易 OOM

---

八、总结

IoTDB REST API V2 是最简单、最通用、跨语言无敌的接入方式：

• 不用SDK
• 不用编译
• 不用关心语言
• 支持查询、写入、管理

一套接口满足：前端、小程序、Python、Go、PHP、Java、设备、网关、可视化平台。