Skip to content

T
TDengine

taosdata / TDengine
1 年多 前同步成功

通知 1185
Star 22016
Fork 4786
T
TDengine
提交 a7334797 编写于 作者: T t_max
浏览文件
操作

docs(REST): improve REST API document

上级 d6362604
隐藏空白更改
内联 并排
Showing with 63 addition and 251 deletion
docs/zh/14-reference/02-rest-api/02-rest-api.mdx
浏览文件 @ a7334797
...@@ -20,8 +20,10 @@ RESTful 接口不依赖于任何 TDengine 的库，因此客户端不需要安 ...@@ -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 ...@@ -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] ...@@ -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 语句中的数据 ...@@ -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] ...@@ -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] ...@@ -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] ...@@ -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] ...@@ -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> ...@@ -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：授权码
获取授权码示例： 获取授权码示例：
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或