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

文章目录

  • TDengine:远程连接taosd服务之-RESTful
    • RESTful Connector
      • HTTP 请求格式
      • TDengine 认证
        • 不带认证信息
        • Basic 认证
        • 自定义授权码
      • HTTP返回格式
    • 使用示例
      • 查询所有记录
      • 创建库 demo
      • 创建超级表
      • 创建表
      • 自动建表
      • sql写入
      • 结果集采用 Unix 时间戳
      • 结果集采用 UTC 时间字符串
      • 删除超级表
      • 删除表
      • 删除库

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

测试数据

TDengine:远程连接taosd服务之-RESTful_第1张图片

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

你可能感兴趣的:(TDengine,tdengine)