REST API

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

IMPORTANT

与原生连接器的一个区别是，RESTful 接口是无状态的，因此 USE db_name 指令没有效果，所有对表名、超级表名的引用都需要指定数据库名前缀。支持在 RESTful URL 中指定 db_name，这时如果 SQL 语句中没有指定数据库名前缀的话，会使用 URL 中指定的这个 db_name。

安装

RESTful 接口不依赖于任何 TDengine 的库，因此客户端不需要安装任何 TDengine 的库，只要客户端的开发语言支持 HTTP 协议即可。

验证

在已经安装 TDengine 服务器端的情况下，可以按照如下方式进行验证。

下面以 Ubuntu 环境中使用 curl 工具（请确认已经安装）来验证 RESTful 接口是否工作正常，验证前请确认 taosAdapter 服务已开启，在 Linux 系统上此服务默认由 systemd 管理，使用命令 systemctl start taosadapter 启动。

下面示例是列出所有的数据库都在 TDengine Cloud URL 主机上面。如果您正在访问 TDengine Cloud，您必须使用云服务的令牌。

curl -L \
  -d "select name, ntables, status from information_schema.ins_databases;" \
  <TDengine Cloud URL>/rest/sql\?token=<TDengine Cloud Token>

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

{
    "code": 0,
    "column_meta": [
        [
            "name",
            "VARCHAR",
            64
        ],
        [
            "ntables",
            "BIGINT",
            8
        ],
        [
            "status",
            "VARCHAR",
            10
        ]
    ],
    "data": [
        [
            "information_schema",
            16,
            "ready"
        ],
        [
            "performance_schema",
            9,
            "ready"
        ]
    ],
    "rows": 2
}

HTTP 请求格式

https://<TDENGINE_CLOUD_URL>/rest/sql/[db_name]?token=<TDENGINE_CLOUD_TOKEN>

参数说明：

TDENGINE_CLOUD_URL: TDengine Cloud 的地址。
db_name: 可选参数，指定本次所执行的 SQL 语句的默认数据库库名。
TDENGINE_CLOUD_TOKEN: 用来访问 TDengine Cloud。

例如：https://gw.cloud.taosdata.com/rest/sql/test?token=xxxxxxxxx 是指向地址为 gw.cloud.taosdata.com 的 URL，并将默认使用的数据库库名设置为 test。

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

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

curl -L -d "<SQL>" <TDENGINE_CLOUD_URL>/rest/sql/[db_name]?token=<TDENGINE_CLOUD_TOKEN>

HTTP 返回格式

HTTP 响应码

response code	说明
200	正确返回和 C 接口错误返回
400	参数错误返回
401	鉴权失败
404	接口不存在
500	内部错误
503	系统资源不足

HTTP body 结构

正确执行插入

样例：

{
  "code": 0,
  "column_meta": [["affected_rows", "INT", 4]],
  "data": [[0]],
  "rows": 1
}

说明：

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

正确执行查询

样例：

{
  "code": 0,
  "column_meta": [
    ["ts", "TIMESTAMP", 8],
    ["count", "BIGINT", 8],
    ["endpoint", "VARCHAR", 45],
    ["status_code", "INT", 4],
    ["client_ip", "VARCHAR", 40],
    ["request_method", "VARCHAR", 15],
    ["request_uri", "VARCHAR", 128]
  ],
  "data": [
    [
      "2022-06-29T05:50:55.401Z",
      2,
      "LAPTOP-NNKFTLTG:6041",
      200,
      "172.23.208.1",
      "POST",
      "/rest/sql"
    ],
    [
      "2022-06-29T05:52:16.603Z",
      1,
      "LAPTOP-NNKFTLTG:6041",
      200,
      "172.23.208.1",
      "POST",
      "/rest/sql"
    ],
    [
      "2022-06-29T06:28:14.118Z",
      1,
      "LAPTOP-NNKFTLTG:6041",
      200,
      "172.23.208.1",
      "POST",
      "/rest/sql"
    ],
    [
      "2022-06-29T05:52:16.603Z",
      2,
      "LAPTOP-NNKFTLTG:6041",
      401,
      "172.23.208.1",
      "POST",
      "/rest/sql"
    ]
  ],
  "rows": 4
}

说明：

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"

错误

样例：

{
  "code": 9728,
  "desc": "syntax error near \"1\""
}

说明：

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

使用示例

下面以智能电表为例，展示如何使用 REST 连接在名为 power 的数据库中，创建一个名为 meters 的超级表（STABLE），插入并查询数据。meters 表结构包含时间戳、电流、电压、相位等列，以及分组 ID 和位置作为标签。

IMPORTANT

在执行下面样例代码的之前，您必须先在 TDengine Cloud - 数据浏览器页面创建一个名为 power 的数据库

配置 URL 和 Token

export TDENGINE_CLOUD_URL="<url>"
export TDENGINE_CLOUD_TOKEN="<token>"

创建 meters 超级表

curl -L -d \
"CREATE STABLE IF NOT EXISTS power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)" \
$TDENGINE_CLOUD_URL/rest/sql\?token=$TDENGINE_CLOUD_TOKEN

返回值

{
  "code": 0,
  "column_meta": [
    [
      "affected_rows",
      "INT",
      4
    ]
  ],
  "data": [
    [
      0
    ]
  ],
  "rows": 1
}

向 meters 中插入数据

curl -L -d \
"INSERT INTO power.d1001 USING power.meters TAGS('California.SanFrancisco', 2) VALUES ('2018-10-03 14:38:05.000', 10.30000, 219, 0.31000) ('2018-10-03 14:38:15.000', 12.60000, 218, 0.33000)" \
$TDENGINE_CLOUD_URL/rest/sql\?token=$TDENGINE_CLOUD_TOKEN

返回值

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

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

curl -L -d "select * from power.d1001" $TDENGINE_CLOUD_URL/rest/sql\?token=$TDENGINE_CLOUD_TOKEN

返回值：

{
    "code": 0,
    "column_meta": [
        [
            "ts",
            "TIMESTAMP",
            8
        ],
        [
            "current",
            "FLOAT",
            4
        ],
        [
            "voltage",
            "INT",
            4
        ],
        [
            "phase",
            "FLOAT",
            4
        ]
    ],
    "data": [
        [
            "2022-07-30T06:44:40.32Z",
            10.3,
            219,
            0.31
        ],
        [
            "2022-07-30T06:44:41.32Z",
            12.6,
            218,
            0.33
        ]
    ],
    "rows": 2
}