REST API
为支持各种不同类型平台的开发,TDengine 提供符合 RESTful 设计标准的 API,即 REST API。为最大程度降低学习成本,不同于其他数据库 REST API 的设计方法,TDengine 直接通过 HTTP POST 请求 BODY 中包含的 SQL 语句来操作数据库,仅需要一个 URL。REST API 的使用参见 视频教程。
与原生连接器的一个区别是,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 时区)。
列类型使用如下字符串:
- "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 格式,各字段含义如下:
- status:请求结果的标志位。
- 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
URI | TDengine 2.x | TDengine 3.0 |
---|---|---|
/rest/sql | 支持 | 支持 (响应代码和消息体不同) |
/rest/sqlt | 支持 | 不再支持 |
/rest/sqlutc | 支持 | 不再支持 |
HTTP code
HTTP code | TDengine 2.x | TDengine 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
}