TDengine：远程连接taosd服务之-RESTful

TDengine：远程连接taosd服务之-RESTful

测试数据

RESTful Connector

RESTful Connector 是最简单的远程连接方式，跨平台、无需安装任何客户端，直接发起 HTTP 请求即可

TDengine 通过 HTTP POST 请求 BODY 中包含的 SQL 语句来操作数据库，仅需要一个 URL ，以下是在 Ubuntu 操作系统上使用 curl 发送 HTTP 请求来体验

RESTful Connector 默认使用6041（实际取值是 serverPort + 11，因此可以通过修改 serverPort 参数的设置来修改）端口通信，所以在服务器端需要开放6041的TCP端口

HTTP 请求格式

http://:/rest/sql/[db_name]

- fqnd: 集群中的任一台主机 FQDN 或 IP 地址
- port: 配置文件中 httpPort 配置项，缺省为 6041
- db_name: 可选参数，指定本次所执行的 SQL 语句的默认数据库库名。（从 2.2.0.0 版本开始支持）

TDengine 认证

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

不带认证信息

curl -d 'select * from temperature' 1.14.252.45:6041/rest/sql/test

{
    "code": 4357,
    "desc": "no auth info input",
    "status": "error"
}

Basic 认证

格式：

curl -H 'Authorization: Basic ' -d '' <ip>:<PORT>/rest/sql/[db_name]

或者：

curl -u username:password -d '' <ip>:<PORT>/rest/sql/[db_name]

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

curl -u root:root -d 'select * from temperature' 1.14.252.45:6041/rest/sql/test

curl -H 'Authorization: Basic cm9vdDb290' -d 'select * from temperature' 1.14.252.45:6041/rest/sql/test

查询结果：

{"status":"succ","head":["ts","temperature","location","tbindex"],"column_meta":[["ts",9,8],["temperature",6,4],["location",10,64],["tbindex",4,4]],"data":[["2020-11-10 08:00:22.222",1.10000,"北京",0],["2020-11-10 08:00:22.223",1.20000,"北京",0],["2020-11-10 16:00:00.000",34.16116,"北京",0],["2020-11-10 16:00:00.000",9.75780,"上海",1],["2020-11-10 16:00:00.000",36.83972,"广州",2],["2020-11-10 16:00:00.000",41.21980,"深圳",3],["2020-11-10 16:00:00.000",12.89832,"北京",4],["2020-11-10 16:00:00.000",10.07183,"北京",5],["2020-11-10 16:00:00.000",6.91456,"广州",6],["2020-11-10 16:00:00.000",45.11603,"广州",7],["2020-11-10 16:00:00.000",17.71194,"上海",8],["2020-11-10 16:00:00.000",26.36280,"北京",9]],"rows":12}

自定义授权码

HTTP 请求中需要带有授权码 ，用于身份识别。授权码通常由管理员提供，可简单的通过发送 HTTP GET 请求来

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

获取授权码示例：

curl http://1.14.252.45:6041/rest/login/root/root

返回值：

{
    "code": 0,
    "desc": "/KfeAzX/f9na8qdtNZmtONryp201KfeAzX/f9na8qdtNZmtONryp201ma04",
    "status": "succ"
}

使用示例：

curl -H 'Authorization: Taosd  /KfeAzX/f9na8qdtNZmtONryp201ma04/KfX/f9na8qdtNZmtONryp201ma04' -d 'select * from temperature' 1.14.252.45:6041/rest/sql/test

HTTP返回格式

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

参数说明：

• status: 告知操作结果是成功还是失败
• head: 表的定义，如果不返回结果集，则仅有一列 “affected_rows”。（从 2.0.17.0 版本开始，建议不要依赖 head 返回值来判断数据列类型，而推荐使用 column_meta。在未来版本中，有可能会从返回值中去掉 head 这一项。）
• column_meta: 从 2.0.17.0 版本开始，返回值中增加这一项来说明 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

使用示例

查询所有记录

curl -H 'Authorization: Taosd  /KfeAzX/f9na8qdtNZmtONryp201ma04/Kfe/f9na8qdtNZmtONryp201ma04' -d 'select * from temperature' 1.14.252.45:6041/rest/sql/test

或者：

curl -H 'Authorization: Taosd  /KfeAzX/f9na8qdtNZmtONryp201ma04eAzX/f9na8qdtNZmtONryp201ma04' -d 'select * from test.temperature' 1.14.252.45:6041/rest/sql

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

创建库 demo

curl -H 'Authorization: Basic cm9vdyb290' -d 'create database demo' 1.14.252.45:6041/rest/sql

返回值：

{"status":"succ","head":["affected_rows"],"column_meta":[["affected_rows",4,4]],"data":[[0]],"rows":1}

创建超级表

curl -H 'Authorization: Basic cm9vyb290' -d 'CREATE STABLE meters (ts timestamp, current float, voltage int, phase float) TAGS (location binary(64), groupId int)' 1.14.252.45:6041/rest/sql/demo

创建表时，需要提供表名（示例中为 meters），表结构 Schema，即数据列的定义。第一列必须为时间戳（示例中为 ts)，其他列为采集的物理量（示例中为 current, voltage, phase)，数据类型可以为整型、浮点型、字符串等。除此之外，还需要提供标签的 schema (示例中为 location, groupId)，标签的数据类型可以为整型、浮点型、字符串等

一张超级表最多容许 1024 列，如果一个采集点采集的物理量个数超过 1024，需要建多张超级表来处理。一个系统可以有多个 DB，一个 DB 里可以有一到多个超级表。（从 2.1.7.0 版本开始，列数限制由 1024 列放宽到了 4096 列。）

创建表

curl -H 'Authorization: Basic cm9vpyb290' -d 'CREATE TABLE d1001 USING meters TAGS ("Beijing.Chaoyang", 2)' 1.14.252.45:6041/rest/sql/demo

自动建表

curl -H 'Authorization: Basic cm9pyb290' -d 'INSERT INTO d1002 USING meters TAGS ("Beijng.Chaoyang", 2) VALUES (now, 10.2, 219, 0.32)' 1.14.252.45:6041/rest/sql/demo

sql写入

# 写入一条数据
curl -H 'Authorization: Basic cm9Dpyb290' -d 'INSERT INTO d1001 VALUES (1538548685000, 10.3, 219, 0.31)' 1.14.252.45:6041/rest/sql/demo

# 一次性写入多条数据
curl -H 'Authorization: Basic cmDpyb290' -d 'INSERT INTO d1001 VALUES (1538548684000, 10.2, 220, 0.23) (1538548696650, 10.3, 218, 0.25)' 1.14.252.45:6041/rest/sql/demo

# 向多个表写入数据
curl -H 'Authorization: Basic cmDpyb290' -d 'INSERT INTO d1001 VALUES (1538548685000, 10.3, 219, 0.31) (1538548695000, 12.6, 218, 0.33) d1002 VALUES (1538548696800, 12.3, 221, 0.31)' 1.14.252.45:6041/rest/sql/demo

结果集采用 Unix 时间戳

curl -H 'Authorization: Basic cmDpyb290' -d 'select * from demo.d1001' 1.14.252.45:6041/rest/sqlt

查询结果：

{
    "status": "succ",
    "head": ["ts","current","voltage","phase"],
    "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
    "data": [
        [1538548684000,10.20000,220,0.23000],
        [1538548685000,10.30000,219,0.31000]
    ],
    "rows": 2
}

结果集采用 UTC 时间字符串

curl -H 'Authorization: Basic cm9vdDp290' -d 'select * from demo.d1001' 1.14.252.45:6041/rest/sqlutc

查询结果：

{
    "status": "succ",
    "head": ["ts","current","voltage","phase"],
    "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
    "data": [
        ["2018-10-03T06:38:04.000+0000",10.20000,220,0.23000],
        ["2018-10-03T06:38:05.000+0000",10.30000,219,0.31000]
    ],
    "rows": 2
}

删除超级表

curl -H 'Authorization: Basic cm9vdDpy90' -d 'drop table if exists temperature' 1.14.252.45:6041/rest/sql/test

删除表

curl -H 'Authorization: Basic cm9vdDpy90' -d 'drop table if exists d1001' 1.14.252.45:6041/rest/sql/demo

删除库

curl -H 'Authorization: Basic cm9vdDb290' -d 'drop database test' 1.14.252.45:6041/rest/sql