当前位置： 首页 > news >正文

TDengine Restful 接口API

news 2025/4/26 21:32:23

简介

为支持各种不同类型平台的开发，TDengine 提供符合 RESTful 设计标准的 API，即 REST API。为最大程度降低学习成本，不同于其他数据库 REST API 的设计方法，TDengine 直接通过 HTTP POST 请求 BODY 中包含的 SQL 语句来操作数据库，仅需要一个 URL。REST API 的使用参见 视频教程。

:::note
与原生连接器的一个区别是，RESTful 接口是无状态的，因此 USE db_name 指令没有效果，所有对表名、超级表名的引用都需要指定数据库名前缀。支持在 RESTful URL 中指定 db_name，这时如果 SQL 语句中没有指定数据库名前缀的话，会使用 URL 中指定的这个 db_name。
:::

安装

RESTful 接口不依赖于任何 TDengine 的库，因此客户端不需要安装任何 TDengine 的库，只要客户端的开发语言支持 HTTP 协议即可。TDengine 的 RESTful API 由 taosAdapter 提供，在使用 RESTful API 之前需要确保 taosAdapter 正常运行。

验证

在已经安装 TDengine 服务器端的情况下，可以按照如下方式进行验证。

下面以 Ubuntu 环境中使用 curl 工具（请确认已经安装）来验证 RESTful 接口是否工作正常，验证前请确认 taosAdapter 服务已开启，在 Linux 系统上此服务默认由 systemd 管理，使用命令 systemctl start taosadapter 启动。

下面示例是列出所有的数据库，请把 h1.taosdata.com 和 6041（缺省值）替换为实际运行的 TDengine 服务 FQDN 和端口号：

curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" \-d "select name, ntables, status from information_schema.ins_databases;" \h1.taosdata.com:6041/rest/sql

返回值结果如下表示验证通过：

{"code": 0,"column_meta": [["name","VARCHAR",64],["ntables","BIGINT",8],["status","VARCHAR",10]],"data": [["information_schema",16,"ready"],["performance_schema",9,"ready"]],"rows": 2
}

HTTP 请求格式

http://<fqdn>:<port>/rest/sql/[db_name][?tz=timezone[&req_id=req_id][&row_with_meta=true]]

参数说明：

  • fqdn：集群中的任一台主机 FQDN 或 IP 地址。
  • port：配置文件中 httpPort 配置项，缺省为 6041。
  • db_name：可选参数，指定本次所执行的 SQL 语句的默认数据库库名。
  • tz：可选参数，指定返回时间的时区，遵照 IANA Time Zone 规则，如 America/New_York。
  • req_id：可选参数，指定请求 id，可以用于 tracing。
  • row_with_meta：可选参数，指定是否每行数据都携带列名，缺省为 false。（3.3.2.0 版本开始支持）

例如：http://h1.taos.com:6041/rest/sql/test 是指向地址为 h1.taos.com:6041 的 URL，并将默认使用的数据库库名设置为 test。

HTTP 请求的 Header 里需带有身份认证信息，TDengine 支持 Basic 认证与自定义认证两种机制，后续版本将提供标准安全的数字签名机制来做身份验证。

  • 自定义身份认证信息如下所示：

    Authorization: Taosd <TOKEN>

  • Basic 身份认证信息如下所示：

    Authorization: Basic <TOKEN>

HTTP 请求的 BODY 里就是一个完整的 SQL 语句，SQL 语句中的数据表应提供数据库前缀，例如 db_name.tb_name。如果表名不带数据库前缀，又没有在 URL 中指定数据库名的话，系统会返回错误。因为 HTTP 模块只是一个简单的转发，没有当前 DB 的概念。

使用 curl 通过自定义身份认证方式来发起一个 HTTP Request，语法如下：

curl -L -H "Authorization: Basic <TOKEN>" -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name][?tz=timezone[&req_id=req_id][&row_with_meta=true]]

或者，

curl -L -u username:password -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name][?tz=timezone[&req_id=req_id][&row_with_meta=true]]

其中，TOKEN 为 {username}:{password} 经过 Base64 编码之后的字符串，例如 root:taosdata 编码后为 cm9vdDp0YW9zZGF0YQ==。

HTTP 返回格式

HTTP 响应码

默认情况下，taosAdapter 对大多数 C 接口调用出错时也会返回 200 响应码，但是 HTTP body 中包含错误信息。从 TDengine 3.0.3.0 开始 taosAdapter 提供配置参数 httpCodeServerError 用来设置当 C 接口返回错误时是否返回非 200 的 HTTP 响应码。无论是否设置此参数，响应 body 里都有详细的错误码和错误信息，具体请参考 错误 。

当 httpCodeServerError 为 false 时：

分类说明HTTP 响应码
C 接口调用成功200
C 接口调用出错，且不是鉴权错误200
HTTP 请求 URL 参数错误400
C 接口调用鉴权错误401
接口不存在404
系统资源不足503

当 httpCodeServerError 为 true 时：

分类说明HTTP 响应码
C 接口调用成功200
HTTP 请求 URL 参数错误和 C 接口调用参数解析错误400
C 接口调用鉴权错误401
接口不存在404
C 接口调用网络不可用错误502
系统资源不足503
其他 C 接口调用错误500

C 接口参数解析相关错误码：

  • TSDB_CODE_TSC_SQL_SYNTAX_ERROR (0x0216)
  • TSDB_CODE_TSC_LINE_SYNTAX_ERROR (0x021B)
  • TSDB_CODE_PAR_SYNTAX_ERROR (0x2600)
  • TSDB_CODE_TDB_TIMESTAMP_OUT_OF_RANGE (0x060B)
  • TSDB_CODE_TSC_VALUE_OUT_OF_RANGE (0x0224)
  • TSDB_CODE_PAR_INVALID_FILL_TIME_RANGE (0x263B)

C 接口鉴权相关错误码：

  • TSDB_CODE_MND_USER_ALREADY_EXIST (0x0350)
  • TSDB_CODE_MND_USER_NOT_EXIST (0x0351)
  • TSDB_CODE_MND_INVALID_USER_FORMAT (0x0352)
  • TSDB_CODE_MND_INVALID_PASS_FORMAT (0x0353)
  • TSDB_CODE_MND_NO_USER_FROM_CONN (0x0354)
  • TSDB_CODE_MND_TOO_MANY_USERS (0x0355)
  • TSDB_CODE_MND_INVALID_ALTER_OPER (0x0356)
  • TSDB_CODE_MND_AUTH_FAILURE (0x0357)

C 接口网络不可用相关错误码：

  • TSDB_CODE_RPC_NETWORK_UNAVAIL (0x000B)

错误码和错误描述请参考 错误码

HTTP body 结构

正确执行插入

样例：

{"code": 0,"column_meta": [["affected_rows", "INT", 4]],"data": [[0]],"rows": 1
}

说明：

  • code：（int）0 代表成功。
  • column_meta：（[1][3]any）只返回 [["affected_rows", "INT", 4]]。
  • rows：（int）只返回 1。
  • data：（[][]any）返回受影响行数。
正确执行查询

样例：

{"code": 0,"column_meta": [["ts", "TIMESTAMP", 8],["count", "BIGINT", 8],["endpoint", "VARCHAR", 45],["status_code", "INT", 4],["client_ip", "VARCHAR", 40],["request_method", "VARCHAR", 15],["request_uri", "VARCHAR", 128]],"data": [["2022-06-29T05:50:55.401Z",2,"LAPTOP-NNKFTLTG:6041",200,"172.23.208.1","POST","/rest/sql"],["2022-06-29T05:52:16.603Z",1,"LAPTOP-NNKFTLTG:6041",200,"172.23.208.1","POST","/rest/sql"],["2022-06-29T06:28:14.118Z",1,"LAPTOP-NNKFTLTG:6041",200,"172.23.208.1","POST","/rest/sql"],["2022-06-29T05:52:16.603Z",2,"LAPTOP-NNKFTLTG:6041",401,"172.23.208.1","POST","/rest/sql"]],"rows": 4
}

说明：

  • code：（int）0 代表成功。
  • column_meta：（[][3]any）列信息，每个列会用三个值来说明，分别为：列名（string）、列类型（string）、类型长度（int）。
  • rows：（int）数据返回行数。
  • data：（[][]any）具体数据内容（时间格式仅支持 RFC3339，结果集为 0 时区，指定 tz 时返回对应时区）。

列类型使用如下字符串：

  • “NULL”
  • “BOOL”
  • “TINYINT”
  • “SMALLINT”
  • “INT”
  • “BIGINT”
  • “FLOAT”
  • “DOUBLE”
  • “VARCHAR”
  • “TIMESTAMP”
  • “NCHAR”
  • “TINYINT UNSIGNED”
  • “SMALLINT UNSIGNED”
  • “INT UNSIGNED”
  • “BIGINT UNSIGNED”
  • “JSON”
  • “VARBINARY”
  • “GEOMETRY”

VARBINARY 和 GEOMETRY 类型返回数据为 Hex 字符串，样例：

准备数据

create database demo
use demo
create table t(ts timestamp,c1 varbinary(20),c2 geometry(100))
insert into t values(now,'\x7f8290','point(100 100)')

执行查询

curl --location 'http://<fqdn>:<port>/rest/sql' \
--header 'Content-Type: text/plain' \
--header 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' \
--data 'select * from demo.t'

返回结果

{"code": 0,"column_meta": [["ts","TIMESTAMP",8],["c1","VARBINARY",20],["c2","GEOMETRY",100]],"data": [["2023-11-01T06:28:15.210Z","7f8290","010100000000000000000059400000000000005940"]],"rows": 1
}
  • 010100000000000000000059400000000000005940 为 point(100 100) 的 Well-Known Binary (WKB) 格式
错误

样例：

{"code": 9728,"desc": "syntax error near \"1\""
}

说明：

  • code：（int）错误码。
  • desc：（string）错误描述。

错误码和错误描述请参考 错误码

返回 key-value 形式数据

当指定 url 参数 row_with_meta=true 时，返回的 data 中的数据会从数组的形式变成对象的形式，对象的 key 为列名，value 为数据，如下所示：

插入数据返回示例

{"code": 0,"column_meta": [["affected_rows","INT",4]],"data": [{"affected_rows": 1}],"rows": 1
}

查询数据返回示例

{"code": 0,"column_meta": [["ts","TIMESTAMP",8],["current","FLOAT",4],["voltage","INT",4],["phase","FLOAT",4],["groupid","INT",4],["location","VARCHAR",24]],"data": [{"ts": "2017-07-14T02:40:00.000Z","current": -2.498076,"voltage": 0,"phase": -0.846025,"groupid": 8,"location": "California.Sunnyvale"}],"rows": 1
}

自定义授权码

HTTP 请求中需要带有授权码 <TOKEN>，用于身份识别。授权码通常由管理员提供，可简单的通过发送 HTTP GET 请求来获取授权码，操作如下：

curl http://<fqnd>:<port>/rest/login/<username>/<password>

其中，fqdn 是 TDengine 数据库的 FQDN 或 IP 地址，port 是 TDengine 服务的端口号，username 为数据库用户名，password 为数据库密码，返回值为 JSON 格式，各字段含义如下：

  • code：返回值代码。
  • desc：授权码。

获取授权码示例：

curl http://192.168.0.1:6041/rest/login/root/taosdata

返回值：

{"code": 0,"desc": "/KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04"
}

使用示例

  • 在 demo 库里查询表 d1001 的所有记录：

    curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "select * from demo.d1001" 192.168.0.1:6041/rest/sql
curl -L -H "Authorization: Taosd /KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04" -d "select * from demo.d1001" 192.168.0.1:6041/rest/sql

    返回值：

    {"code": 0,"column_meta": [["ts","TIMESTAMP",8],["current","FLOAT",4],["voltage","INT",4],["phase","FLOAT",4]],"data": [["2022-07-30T06:44:40.32Z",10.3,219,0.31],["2022-07-30T06:44:41.32Z",12.6,218,0.33]],"rows": 2
}

  • 创建库 demo：

    curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "create database demo" 192.168.0.1:6041/rest/sql
curl -L -H "Authorization: Taosd /KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04" -d "create database demo" 192.168.0.1:6041/rest/sql

    返回值：

    {"code": 0,"column_meta": [["affected_rows","INT",4]],"data": [[0]],"rows": 1
}

TDengine 2.x 和 3.0 之间 REST API 的差异

URI

URITDengine 2.xTDengine 3.0
/rest/sql支持支持（响应代码和消息体不同）
/rest/sqlt支持不再支持
/rest/sqlutc支持不再支持

HTTP code

HTTP codeTDengine 2.xTDengine 3.0备注
200支持支持正确返回和 taosc 接口错误返回
400不支持支持参数错误返回
401不支持支持鉴权失败
404支持支持接口不存在
500不支持支持内部错误
503支持支持系统资源不足

响应代码和消息体

TDengine 2.x 响应代码和消息体
{"status": "succ","head": ["name","created_time","ntables","vgroups","replica","quorum","days","keep1,keep2,keep(D)","cache(MB)","blocks","minrows","maxrows","wallevel","fsync","comp","precision","status"],"data": [["log","2020-09-02 17:23:00.039",4,1,1,1,10,"30,30,30",1,3,100,4096,1,3000,2,"us","ready"]],"rows": 1
}

  "data": [["information_schema",16,"ready"],["performance_schema",9,"ready"]],
TDengine 3.0 响应代码和消息体
{"code": 0,"column_meta": [["name","VARCHAR",64],["ntables","BIGINT",8],["status","VARCHAR",10]],"data": [["information_schema",16,"ready"],["performance_schema",9,"ready"]],"rows": 2
}

访问官网

更多内容欢迎访问 TDengine 官网

http://www.xdnf.cn/news/13249.html

相关文章：

  • excel解析图片pdf附件不怕
  • ESP8266简单介绍
  • 2025年山东燃气瓶装送气工考试真题练习
  • MCP协议量子加密实践：基于QKD的下一代安全通信（2025深度解析版）
  • 从数字化到智能化，百度 SRE 数智免疫系统的演进和实践
  • MCP（Model Context Protocol 模型上下文协议）科普
  • vue 中formatter
  • 2025-04-18 李沐深度学习3 —— 线性代数
  • yarn的三大组件及各自作用
  • easyexcel使用模板填充excel坑点总结
  • Kotlin协程Semaphore withPermit约束并发任务数量
  • chili3d调试笔记3 加入c++ 大模型对话方法 cmakelists精读
  • PY32F003+TIM+外部中断实现对1527解码
  • 【Test Test】灰度化和二值化处理图像
  • 6TOPS算力NPU加持！RK3588如何重塑8K显示的边缘计算新边界
  • 嵌入式音视频开发指南：从MPP框架到QT实战全解析
  • 3D 视觉赋能仓储精准高效：ID Logistics 与 Stereolabs 的创新合作之旅
  • Java开发中的常用注解
  • 字符串系列一＞最长回文子串
  • 给予FLUX更好的控制：FLUX.1-dev-ControlNet-Union-Pro-2.0
  • Redis——网络模型之IO讲解
  • 大模型微服务架构模块实现方案，基于LLaMA Factory和Nebius Cloud实现模型精调的标准流程及代码
  • Android——动画
  • IPTV电视信息发布直播点播系统:营造数字化个性化融合化多媒体IPTV电视信息发布平台
  • 预训练与微调：大模型如何“学习知识”？
  • Python 网络爬虫基础理论与实战指南
  • 【每日八股】复习计算机网络 Day1：TCP 的头部结构 + TCP 确保可靠传输 + TCP 的三次握手
  • 【漫话机器学习系列】209.均值的标准误差（Standard Error of the Mean）
  • 完整的 .NET 6 分布式定时任务实现（Hangfire + Redis 分布式锁）
  • 故障诊断常用算法