Merge pull request #16107 from taosdata/docs/xftan/TD-18386
docs(REST): improve REST API document
This commit is contained in:
Shuaiqiang Chang
GitHub
commit
dcac4ba0fc
|
|
@ -20,8 +20,10 @@ RESTful 接口不依赖于任何 TDengine 的库，因此客户端不需要安
|
||||||
|
|
||||||
下面示例是列出所有的数据库，请把 h1.taosdata.com 和 6041（缺省值）替换为实际运行的 TDengine 服务 FQDN 和端口号：
|
下面示例是列出所有的数据库，请把 h1.taosdata.com 和 6041（缺省值）替换为实际运行的 TDengine 服务 FQDN 和端口号：
|
||||||
|
|
||||||
```html
|
```bash
|
||||||
curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "show databases;" h1.taosdata.com:6041/rest/sql
|
curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" \
|
||||||
|
-d "select name, ntables, status from information_schema.ins_databases;" \
|
||||||
|
h1.taosdata.com:6041/rest/sql
|
||||||
```
|
```
|
||||||
|
|
||||||
返回值结果如下表示验证通过：
|
返回值结果如下表示验证通过：
|
||||||
|
|
@ -35,188 +37,27 @@ curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "show databases;" h1.t
|
||||||
"VARCHAR",
|
"VARCHAR",
|
||||||
64
|
64
|
||||||
],
|
],
|
||||||
[
|
|
||||||
"create_time",
|
|
||||||
"TIMESTAMP",
|
|
||||||
8
|
|
||||||
],
|
|
||||||
[
|
|
||||||
"vgroups",
|
|
||||||
"SMALLINT",
|
|
||||||
2
|
|
||||||
],
|
|
||||||
[
|
[
|
||||||
"ntables",
|
"ntables",
|
||||||
"BIGINT",
|
"BIGINT",
|
||||||
8
|
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",
|
"status",
|
||||||
"VARCHAR",
|
"VARCHAR",
|
||||||
10
|
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": [
|
"data": [
|
||||||
[
|
[
|
||||||
"information_schema",
|
"information_schema",
|
||||||
null,
|
16,
|
||||||
null,
|
"ready"
|
||||||
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",
|
"performance_schema",
|
||||||
null,
|
9,
|
||||||
null,
|
"ready"
|
||||||
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
|
"rows": 2
|
||||||
|
|
@ -231,21 +72,21 @@ http://<fqdn>:<port>/rest/sql/[db_name]
|
||||||
|
|
||||||
参数说明：
|
参数说明：
|
||||||
|
|
||||||
- fqnd: 集群中的任一台主机 FQDN 或 IP 地址
|
- fqnd: 集群中的任一台主机 FQDN 或 IP 地址。
|
||||||
- port: 配置文件中 httpPort 配置项，缺省为 6041
|
- port: 配置文件中 httpPort 配置项，缺省为 6041。
|
||||||
- db_name: 可选参数，指定本次所执行的 SQL 语句的默认数据库库名。
|
- db_name: 可选参数，指定本次所执行的 SQL 语句的默认数据库库名。
|
||||||
|
|
||||||
例如：`http://h1.taos.com:6041/rest/sql/test` 是指向地址为 `h1.taos.com:6041` 的 URL，并将默认使用的数据库库名设置为 `test`。
|
例如：`http://h1.taos.com:6041/rest/sql/test` 是指向地址为 `h1.taos.com:6041` 的 URL，并将默认使用的数据库库名设置为 `test`。
|
||||||
|
|
||||||
HTTP 请求的 Header 里需带有身份认证信息，TDengine 支持 Basic 认证与自定义认证两种机制，后续版本将提供标准安全的数字签名机制来做身份验证。
|
HTTP 请求的 Header 里需带有身份认证信息，TDengine 支持 Basic 认证与自定义认证两种机制，后续版本将提供标准安全的数字签名机制来做身份验证。
|
||||||
|
|
||||||
- [自定义身份认证信息](#自定义授权码)如下所示
|
- [自定义身份认证信息](#自定义授权码)如下所示：
|
||||||
|
|
||||||
```text
|
```text
|
||||||
Authorization: Taosd <TOKEN>
|
Authorization: Taosd <TOKEN>
|
||||||
```
|
```
|
||||||
|
|
||||||
- Basic 身份认证信息如下所示
|
- Basic 身份认证信息如下所示：
|
||||||
|
|
||||||
```text
|
```text
|
||||||
Authorization: Basic <TOKEN>
|
Authorization: Basic <TOKEN>
|
||||||
|
|
@ -259,13 +100,13 @@ HTTP 请求的 BODY 里就是一个完整的 SQL 语句，SQL 语句中的数据
|
||||||
curl -L -H "Authorization: Basic <TOKEN>" -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]
|
curl -L -H "Authorization: Basic <TOKEN>" -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]
|
||||||
```
|
```
|
||||||
|
|
||||||
或者
|
或者，
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -L -u username:password -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]
|
curl -L -u username:password -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]
|
||||||
```
|
```
|
||||||
|
|
||||||
其中，`TOKEN` 为 `{username}:{password}` 经过 Base64 编码之后的字符串，例如 `root:taosdata` 编码后为 `cm9vdDp0YW9zZGF0YQ==`
|
其中，`TOKEN` 为 `{username}:{password}` 经过 Base64 编码之后的字符串，例如 `root:taosdata` 编码后为 `cm9vdDp0YW9zZGF0YQ==`。
|
||||||
|
|
||||||
## HTTP 返回格式
|
## HTTP 返回格式
|
||||||
|
|
||||||
|
|
@ -282,27 +123,9 @@ curl -L -u username:password -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]
|
||||||
|
|
||||||
### HTTP body 结构
|
### 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
|
```json
|
||||||
{
|
{
|
||||||
|
|
@ -313,23 +136,16 @@ curl -L -u username:password -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
</td>
|
说明：
|
||||||
</tr>
|
|
||||||
<tr>
|
- code：（`int`）0 代表成功。
|
||||||
<td>正确查询</td>
|
- column_meta：（`[1][3]any`）只返回 `[["affected_rows", "INT", 4]]`。
|
||||||
<td>
|
- rows：（`int`）只返回 `1`。
|
||||||
code：（int）0 代表成功
|
- data：（`[][]any`）返回受影响行数。
|
||||||
<br/>
|
|
||||||
<br/>
|
#### 正确查询
|
||||||
column_meta：（[][3]any） 列信息，每个列会用三个值来说明，分别为：列名（string）、列类型（string）、类型长度（int）
|
|
||||||
<br/>
|
样例：
|
||||||
<br/>
|
|
||||||
rows：（int）数据返回行数
|
|
||||||
<br/>
|
|
||||||
<br/>
|
|
||||||
data：（[][]any）具体数据内容
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
|
@ -385,17 +201,35 @@ curl -L -u username:password -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
</td>
|
说明：
|
||||||
</tr>
|
|
||||||
<tr>
|
- code：（`int`）0 代表成功。
|
||||||
<td>错误</td>
|
- column_meta：（`[][3]any`） 列信息，每个列会用三个值来说明，分别为：列名（string）、列类型（string）、类型长度（int）。
|
||||||
<td>
|
- rows：（`int`）数据返回行数。
|
||||||
code：（int）错误码
|
- data：（`[][]any`）具体数据内容（时间格式仅支持 RFC3339，结果集为 0 时区）。
|
||||||
<br/>
|
|
||||||
<br/>
|
列类型使用如下字符串:
|
||||||
desc：（string）错误描述
|
|
||||||
</td>
|
- "NULL"
|
||||||
<td>
|
- "BOOL"
|
||||||
|
- "TINYINT"
|
||||||
|
- "SMALLINT"
|
||||||
|
- "INT"
|
||||||
|
- "BIGINT"
|
||||||
|
- "FLOAT"
|
||||||
|
- "DOUBLE"
|
||||||
|
- "VARCHAR"
|
||||||
|
- "TIMESTAMP"
|
||||||
|
- "NCHAR"
|
||||||
|
- "TINYINT UNSIGNED"
|
||||||
|
- "SMALLINT UNSIGNED"
|
||||||
|
- "INT UNSIGNED"
|
||||||
|
- "BIGINT UNSIGNED"
|
||||||
|
- "JSON"
|
||||||
|
|
||||||
|
#### 错误
|
||||||
|
|
||||||
|
样例：
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
|
@ -404,30 +238,10 @@ curl -L -u username:password -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
</td>
|
说明：
|
||||||
</tr>
|
|
||||||
</table>
|
|
||||||
|
|
||||||
### 说明
|
- code：（`int`）错误码。
|
||||||
|
- desc：（`string`）错误描述。
|
||||||
- 时间格式仅支持 RFC3339，结果集为 0 时区
|
|
||||||
- 列类型使用如下字符串:
|
|
||||||
> "NULL"
|
|
||||||
> "BOOL"
|
|
||||||
> "TINYINT"
|
|
||||||
> "SMALLINT"
|
|
||||||
> "INT"
|
|
||||||
> "BIGINT"
|
|
||||||
> "FLOAT"
|
|
||||||
> "DOUBLE"
|
|
||||||
> "VARCHAR"
|
|
||||||
> "TIMESTAMP"
|
|
||||||
> "NCHAR"
|
|
||||||
> "TINYINT UNSIGNED"
|
|
||||||
> "SMALLINT UNSIGNED"
|
|
||||||
> "INT UNSIGNED"
|
|
||||||
> "BIGINT UNSIGNED"
|
|
||||||
> "JSON"
|
|
||||||
|
|
||||||
## 自定义授权码
|
## 自定义授权码
|
||||||
|
|
||||||
|
|
@ -439,11 +253,9 @@ curl http://<fqnd>:<port>/rest/login/<username>/<password>
|
||||||
|
|
||||||
其中，`fqdn` 是 TDengine 数据库的 FQDN 或 IP 地址，`port` 是 TDengine 服务的端口号，`username` 为数据库用户名，`password` 为数据库密码，返回值为 JSON 格式，各字段含义如下：
|
其中，`fqdn` 是 TDengine 数据库的 FQDN 或 IP 地址，`port` 是 TDengine 服务的端口号，`username` 为数据库用户名，`password` 为数据库密码，返回值为 JSON 格式，各字段含义如下：
|
||||||
|
|
||||||
- status：请求结果的标志位
|
- status：请求结果的标志位。
|
||||||
|
- code：返回值代码。
|
||||||
- code：返回值代码
|
- desc：授权码。
|
||||||
|
|
||||||
- desc：授权码
|
|
||||||
|
|
||||||
获取授权码示例：
|
获取授权码示例：
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue