1 Docker 安装

命令如下：

docker run -d -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine

一个奇怪的地方：使用 --name 参数为容器指定名称会启动失败，使用 docker ps -a 命令查看，会发现自动生成了一个随机的 name：

启动容器后，进入容器内部：

docker exec -it <container-id> bash

2 命令行工具

然后进入 TDEngine 命令行：

taos

可以使用 SQL 语句操作数据库：

# 创建数据库
create database demo;

# 使用数据库
use demo;

# 创建表
create table t (ts timestamp, speed int);

# 插入数据
insert into t values ('2024-01-01 10:10:10', 10);
insert into t values ('2024-01-01 10:10:20', 20);

# 查询数据
select * from t;

退出命令行工具：

exit;

3 REST API

3.1 测试接口连通性

使用列出所有数据库的命令测试 RESTful 接口能否访问：

 curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "show databases;" 192.168.204.133:6041/rest/sql

其中，192.168.204.133:6041 需要替换为自己的地址，认证中的 token cm9vdDp0YW9zZGF0YQ==为root:taosdata 的 Base64 编码。

返回结果如下，说明接口可以访问：

{
  "code":0,
  "column_meta":[
    [
      "name",
      "VARCHAR",
      64
    ]
  ],
  "data":[
    ["information_schema"],
    ["performance_schema"],
    ["demo"],
    ["log"]
  ],
  "rows":4
}

3.2 HTTP 请求格式

POST 请求格式如下：

http://<fqdn>:<port>/rest/sql/[db_name]

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

HTTP 请求的 Header 里需要携带身份认证信息，TDengine 支持 Basic 认证与自定义认证两种机制：

# Basic 认证
Authorization: Basic <TOKEN>

# 自定义认证
Authorization: Taosd <TOKEN>

HTTP 请求的 BODY 里就是一个完整的 SQL 语句，SQL 语句中的数据表应提供数据库前缀（因为 REST 接口是无状态的，不能像 CLI 一样使用 use <db_name> 语句）。

3.1 的示例中展示了 curl 中使用 Basic 认证的方法，而下面则展示了自定义认证的用法：

# 用法1
curl -L -H "Authorization: Basic <TOKEN>" -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]

# 用法2
curl -L -u username:password -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]

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

3.3 HTTP 响应格式

使用查询 demo.t 表全部数据进行举例：

# 使用 curl 发送请求
curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "select * from demo.t;" 192.168.204.133:6041/rest/sql

下面是 json 格式的响应：

{
  "code":0,
  "column_meta":[
    ["ts","TIMESTAMP",8],
    ["speed","INT",4]
  ],
  "data":[
    ["2024-01-01T10:10:10.000Z",10],
    ["2024-01-01T10:10:20.000Z",20]
  ],
  "rows":2
}

其中：

• code : 状态码，告知操作成功还是失败；
• column_meta: 说明 data 里每一列的数据类型，具体每个列会用三个值来说明，分别为：列名、列类型、类型长度。
• data: 具体返回的数据，一行一行的呈现，如果不返回结果集，那么就仅有 [[affected_rows]]; data 中每一行的数据列顺序，与 column_meta 中描述数据列的顺序完全一致;
• rows: 表明总共多少行数据。

3.4 获取自定义授权码

可以通过请求来获取授权码：

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

默认的 username 是 root，password 是 taosdata。

例如：

# 获取授权码
curl http://192.168.204.133:6041/rest/login/root/taosdata

# 响应如下：
{
  "code":0,
  "desc":"/KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04"
}

• 其中，desc 为授权码。