RESTful Connector

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

HTTP请求格式

  1. http://<ip>:<PORT>/rest/sql

参数说明：

  • IP: 集群中的任一台主机
  • PORT: 配置文件中httpPort配置项，缺省为6041

例如：http://192.168.0.1:6041/rest/sql 是指向IP地址为192.168.0.1的URL.

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

  • 自定义身份认证信息如下所示（稍后介绍）
  1. Authorization: Taosd <TOKEN>
  • Basic身份认证信息如下所示
  1. Authorization: Basic <TOKEN>

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

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

  1. curl -H 'Authorization: Basic <TOKEN>' -d '<SQL>' <ip>:<PORT>/rest/sql

或者

  1. curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql

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

HTTP返回格式

返回值为JSON格式，如下:

  1. {
  2.     "status": "succ",
  3.     "head": ["ts","current", …],
  4.     "column_meta": [["ts",9,8],["current",6,4], …],
  5.     "data": [
  6.         ["2018-10-03 14:38:05.000", 10.3, …],
  7.         ["2018-10-03 14:38:15.000", 12.6, …]
  8.     ],
  9.     "rows": 2
  10. }

说明：

  • status: 告知操作结果是成功还是失败。
  • head: 表的定义，如果不返回结果集，则仅有一列“affected_rows”。（从 2.0.17 版本开始，建议不要依赖 head 返回值来判断数据列类型，而推荐使用 column_meta。在未来版本中，有可能会从返回值中去掉 head 这一项。）
  • column_meta: 从 2.0.17 版本开始，返回值中增加这一项来说明 data 里每一列的数据类型。具体每个列会用三个值来说明，分别为：列名、列类型、类型长度。例如["current",6,4]表示列名为“current”；列类型为 6，也即 float 类型；类型长度为 4，也即对应 4 个字节表示的 float。如果列类型为 binary 或 nchar，则类型长度表示该列最多可以保存的内容长度，而不是本次返回值中的具体数据长度。当列类型是 nchar 的时候，其类型长度表示可以保存的 unicode 字符数量，而不是 bytes。
  • data: 具体返回的数据，一行一行的呈现，如果不返回结果集，那么就仅有[[affected_rows]]。data 中每一行的数据列顺序，与 column_meta 中描述数据列的顺序完全一致。
  • rows: 表明总共多少行数据。

column_meta 中的列类型说明：

  • 1：BOOL
  • 2：TINYINT
  • 3：SMALLINT
  • 4：INT
  • 5：BIGINT
  • 6：FLOAT
  • 7：DOUBLE
  • 8：BINARY
  • 9：TIMESTAMP
  • 10：NCHAR

自定义授权码

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

  1. curl http://<ip>:6041/rest/login/<username>/<password>

其中，ip是TDengine数据库的IP地址，username为数据库用户名，password为数据库密码，返回值为JSON格式，各字段含义如下：

  • status：请求结果的标志位

  • code：返回值代码

  • desc: 授权码

获取授权码示例：

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

返回值：

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

使用示例

  • 在demo库里查询表d1001的所有记录：
  1. curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sql

返回值：

  1. {
  2.     "status": "succ",
  3.     "head": ["ts","current","voltage","phase"],
  4.     "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
  5.     "data": [
  6.         ["2018-10-03 14:38:05.000",10.3,219,0.31],
  7.         ["2018-10-03 14:38:15.000",12.6,218,0.33]
  8.     ],
  9.     "rows": 2
  10. }
  • 创建库demo：
  1. curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 192.168.0.1:6041/rest/sql

返回值：

  1. {
  2.     "status": "succ",
  3.     "head": ["affected_rows"],
  4.     "column_meta": [["affected_rows",4,4]],
  5.     "data": [[1]],
  6.     "rows": 1
  7. }

其他用法

结果集采用Unix时间戳

HTTP请求URL采用sqlt时，返回结果集的时间戳将采用Unix时间戳格式表示，例如

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

返回值：

  1. {
  2.     "status": "succ",
  3.     "head": ["ts","current","voltage","phase"],
  4.     "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
  5.     "data": [
  6.         [1538548685000,10.3,219,0.31],
  7.         [1538548695000,12.6,218,0.33]
  8.     ],
  9.     "rows": 2
  10. }

结果集采用UTC时间字符串

HTTP请求URL采用sqlutc时，返回结果集的时间戳将采用UTC时间字符串表示，例如

  1.   curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6041/rest/sqlutc

返回值：

  1. {
  2.     "status": "succ",
  3.     "head": ["ts","current","voltage","phase"],
  4.     "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
  5.     "data": [
  6.         ["2018-10-03T14:38:05.000+0800",10.3,219,0.31],
  7.         ["2018-10-03T14:38:15.000+0800",12.6,218,0.33]
  8.     ],
  9.     "rows": 2
  10. }

重要配置项

下面仅列出一些与RESTful接口有关的配置参数，其他系统参数请看配置文件里的说明。注意：配置修改后，需要重启taosd服务才能生效

  • httpPort: 对外提供RESTful服务的端口号，默认绑定到6041
  • httpMaxThreads: 启动的线程数量，默认为2（2.0.17版本开始，默认值改为CPU核数的一半向下取整）
  • restfulRowLimit: 返回结果集（JSON格式）的最大条数，默认值为10240
  • httpEnableCompress: 是否支持压缩，默认不支持，目前TDengine仅支持gzip压缩格式
  • httpDebugFlag: 日志开关，131：仅错误和报警信息，135：调试信息，143：非常详细的调试信息，默认131