REST API

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

REST API - 图1note

与原生连接器的一个区别是，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 和端口号：

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

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

  1. {
  2.     "code": 0,
  3.     "column_meta": [
  4.         [
  5.             "name",
  6.             "VARCHAR",
  7.             64
  8.         ],
  9.         [
  10.             "ntables",
  11.             "BIGINT",
  12.             8
  13.         ],
  14.         [
  15.             "status",
  16.             "VARCHAR",
  17.             10
  18.         ]
  19.     ],
  20.     "data": [
  21.         [
  22.             "information_schema",
  23.             16,
  24.             "ready"
  25.         ],
  26.         [
  27.             "performance_schema",
  28.             9,
  29.             "ready"
  30.         ]
  31.     ],
  32.     "rows": 2
  33. }

HTTP 请求格式

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

参数说明：

  • fqdn: 集群中的任一台主机 FQDN 或 IP 地址。
  • port: 配置文件中 httpPort 配置项，缺省为 6041。
  • db_name: 可选参数，指定本次所执行的 SQL 语句的默认数据库库名。
  • tz: 可选参数，指定返回时间的时区，遵照 IANA Time Zone 规则，如 America/New_York。
  • req_id: 可选参数，指定请求 id，可以用于 tracing。

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

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

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

    1. Authorization: Taosd <TOKEN>

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

    1. Authorization: Basic <TOKEN>

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

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

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

或者，

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

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

HTTP 返回格式

HTTP 响应码

从 TDengine 3.0.3.0 开始 taosAdapter 提供配置参数 httpCodeServerError 用来设置当 C 接口返回错误时是否返回非 200 的http状态码

说明httpCodeServerError falsehttpCodeServerError true
taos_errno() 返回 0200200
taos_errno() 返回 非0200（除鉴权错误）500 （除鉴权错误和 400/502 错误）
参数错误400 (仅处理 HTTP 请求 URL 参数错误)400 （处理 HTTP 请求 URL 参数错误和 taosd 返回错误）
鉴权错误401401
接口不存在404404
集群不可用错误502502
系统资源不足503503

返回 400 的 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)

返回 401 的错误码为：

  • 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)

返回 403 的错误码为：

  • TSDB_CODE_RPC_SOMENODE_NOT_CONNECTED (0x0020)

HTTP body 结构

正确执行插入

样例：

  1. {
  2.   "code": 0,
  3.   "column_meta": [["affected_rows", "INT", 4]],
  4.   "data": [[0]],
  5.   "rows": 1
  6. }

说明：

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

正确执行查询

样例：

  1. {
  2.   "code": 0,
  3.   "column_meta": [
  4.     ["ts", "TIMESTAMP", 8],
  5.     ["count", "BIGINT", 8],
  6.     ["endpoint", "VARCHAR", 45],
  7.     ["status_code", "INT", 4],
  8.     ["client_ip", "VARCHAR", 40],
  9.     ["request_method", "VARCHAR", 15],
  10.     ["request_uri", "VARCHAR", 128]
  11.   ],
  12.   "data": [
  13.     [
  14.       "2022-06-29T05:50:55.401Z",
  15.       2,
  16.       "LAPTOP-NNKFTLTG:6041",
  17.       200,
  18.       "172.23.208.1",
  19.       "POST",
  20.       "/rest/sql"
  21.     ],
  22.     [
  23.       "2022-06-29T05:52:16.603Z",
  24.       1,
  25.       "LAPTOP-NNKFTLTG:6041",
  26.       200,
  27.       "172.23.208.1",
  28.       "POST",
  29.       "/rest/sql"
  30.     ],
  31.     [
  32.       "2022-06-29T06:28:14.118Z",
  33.       1,
  34.       "LAPTOP-NNKFTLTG:6041",
  35.       200,
  36.       "172.23.208.1",
  37.       "POST",
  38.       "/rest/sql"
  39.     ],
  40.     [
  41.       "2022-06-29T05:52:16.603Z",
  42.       2,
  43.       "LAPTOP-NNKFTLTG:6041",
  44.       401,
  45.       "172.23.208.1",
  46.       "POST",
  47.       "/rest/sql"
  48.     ]
  49.   ],
  50.   "rows": 4
  51. }

说明：

  • 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”

错误

样例：

  1. {
  2.   "code": 9728,
  3.   "desc": "syntax error near \"1\""
  4. }

说明：

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

自定义授权码

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

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

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

  • status：请求结果的标志位。
  • code：返回值代码。
  • desc：授权码。

获取授权码示例：

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

返回值：

  1. {
  2.   "code": 0,
  3.   "desc": "/KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04"
  4. }

使用示例

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

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

    返回值：

    1. {
    2.     "code": 0,
    3.     "column_meta": [
    4.         [
    5.             "ts",
    6.             "TIMESTAMP",
    7.             8
    8.         ],
    9.         [
    10.             "current",
    11.             "FLOAT",
    12.             4
    13.         ],
    14.         [
    15.             "voltage",
    16.             "INT",
    17.             4
    18.         ],
    19.         [
    20.             "phase",
    21.             "FLOAT",
    22.             4
    23.         ]
    24.     ],
    25.     "data": [
    26.         [
    27.             "2022-07-30T06:44:40.32Z",
    28.             10.3,
    29.             219,
    30.             0.31
    31.         ],
    32.         [
    33.             "2022-07-30T06:44:41.32Z",
    34.             12.6,
    35.             218,
    36.             0.33
    37.         ]
    38.     ],
    39.     "rows": 2
    40. }

  • 创建库 demo：

    1. curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "create database demo" 192.168.0.1:6041/rest/sql

    返回值：

    1. {
    2.     "code": 0,
    3.     "column_meta": [
    4.         [
    5.             "affected_rows",
    6.             "INT",
    7.             4
    8.         ]
    9.     ],
    10.     "data": [
    11.         [
    12.             0
    13.         ]
    14.     ],
    15.     "rows": 1
    16. }

参考

taosAdapter