02-rest-api.mdx

---
title: REST API
---

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

:::note
与原生连接器的一个区别是，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` 启动。

下面示例是列出所有的数据库，请把 h1.taosdata.com 和 6041（缺省值）替换为实际运行的 TDengine 服务 FQDN 和端口号：

```html
curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "show databases;" h1.taosdata.com:6041/rest/sql
```

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

```json
{
    "code": 0,
    "column_meta": [
        [
            "name",
            "VARCHAR",
            64
        ],
        [
            "create_time",
            "TIMESTAMP",
            8
        ],
        [
            "vgroups",
            "SMALLINT",
            2
        ],
        [
            "ntables",
            "BIGINT",
            8
        ],
        [
            "replica",
            "TINYINT",
            1
        ],
        [
            "strict",
            "VARCHAR",
            4
        ],
        [
            "duration",
            "VARCHAR",
            10
        ],
        [
            "keep",
            "VARCHAR",
            32
        ],
        [
            "buffer",
            "INT",
            4
        ],
        [
            "pagesize",
            "INT",
            4
        ],
        [
            "pages",
            "INT",
            4
        ],
        [
            "minrows",
            "INT",
            4
        ],
        [
            "maxrows",
            "INT",
            4
        ],
        [
            "comp",
            "TINYINT",
            1
        ],
        [
            "precision",
            "VARCHAR",
            2
        ],
        [
            "status",
            "VARCHAR",
            10
        ],
        [
            "retention",
            "VARCHAR",
            60
        ],
        [
            "single_stable",
            "BOOL",
            1
        ],
        [
            "cachemodel",
            "VARCHAR",
            11
        ],
        [
            "cachesize",
            "INT",
            4
        ],
        [
            "wal_level",
            "TINYINT",
            1
        ],
        [
            "wal_fsync_period",
            "INT",
            4
        ],
        [
            "wal_retention_period",
            "INT",
            4
        ],
        [
            "wal_retention_size",
            "BIGINT",
            8
        ],
        [
            "wal_roll_period",
            "INT",
            4
        ],
        [
            "wal_seg_size",
            "BIGINT",
            8
        ]
    ],
    "data": [
        [
            "information_schema",
            null,
            null,
            14,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            "ready",
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null
        ],
        [
            "performance_schema",
            null,
            null,
            3,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            "ready",
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null
        ]
    ],
    "rows": 2
}
```

## HTTP 请求格式

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

参数说明：

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

例如：`http://h1.taos.com:6041/rest/sql/test` 是指向地址为 `h1.taos.com:6041` 的 URL，并将默认使用的数据库库名设置为 `test`。

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

- [自定义身份认证信息](#自定义授权码)如下所示

  ```text
  Authorization: Taosd <TOKEN>
  ```

- Basic 身份认证信息如下所示

  ```text
  Authorization: Basic <TOKEN>
  ```

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

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

```bash
curl -L -H "Authorization: Basic <TOKEN>" -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]
```

或者

```bash
curl -L -u username:password -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]
```

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

## HTTP 返回格式

### HTTP 响应码

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

### HTTP body 结构

<table>
<tr>
  <th>执行结果</th>
  <th>说明</th>
  <th>样例</th>
</tr>
<tr>
  <td>正确执行</td>
  <td>
  code：（int）0 代表成功
  <br/>
  <br/>
  column_meta：（[][3]any）列信息，每个列会用三个值来说明，分别为：列名(string)、列类型(string)、类型长度(int)
  <br/>
  <br/>
  rows：（int）数据返回行数
  <br/>
  <br/>
  data：（[][]any）具体数据内容
  </td>
  <td>

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

  </td>
</tr>
<tr>
    <td>正确查询</td>
    <td>
    code：（int）0 代表成功
    <br/>
    <br/>
    column_meta：（[][3]any） 列信息，每个列会用三个值来说明，分别为：列名（string）、列类型（string）、类型长度（int）
    <br/>
    <br/>
    rows：（int）数据返回行数
    <br/>
    <br/>
    data：（[][]any）具体数据内容
  </td>
  <td>

```json
{
  "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
}
```

  </td>
</tr>
<tr>
  <td>错误</td>
  <td>
  code：（int）错误码
  <br/>
  <br/>
  desc：（string）错误描述
  </td>
  <td>

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

  </td>
</tr>
</table>

### 说明

- 时间格式仅支持 RFC3339，结果集为 0 时区
- 列类型使用如下字符串:
    > "NULL"
    > "BOOL"
    > "TINYINT"
    > "SMALLINT"
    > "INT"
    > "BIGINT"
    > "FLOAT"
    > "DOUBLE"
    > "VARCHAR"
    > "TIMESTAMP"
    > "NCHAR"
    > "TINYINT UNSIGNED"
    > "SMALLINT UNSIGNED"
    > "INT UNSIGNED"
    > "BIGINT UNSIGNED"
    > "JSON"

## 自定义授权码

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

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

其中，`fqdn` 是 TDengine 数据库的 FQDN 或 IP 地址，`port` 是 TDengine 服务的端口号，`username` 为数据库用户名，`password` 为数据库密码，返回值为 JSON 格式，各字段含义如下：

- status：请求结果的标志位

- code：返回值代码

- desc：授权码

获取授权码示例：

```bash
curl http://192.168.0.1:6041/rest/login/root/taosdata
```

返回值：

```json
{
  "status": "succ",
  "code": 0,
  "desc": "/KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04"
}
```

## 使用示例

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

  ```bash
  curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "select * from demo.d1001" 192.168.0.1:6041/rest/sql
  ```

  返回值：

  ```json
  {
      "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
  }
  ```

- 创建库 demo：

  ```bash
  curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "create database demo" 192.168.0.1:6041/rest/sql
  ```

  返回值：

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

## 参考

[taosAdapter](/reference/taosadapter/)