You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iotdb.apache.org by ro...@apache.org on 2021/11/11 10:17:50 UTC
[iotdb] branch pr/4280 created (now 13d1f05)
This is an automated email from the ASF dual-hosted git repository.
rong pushed a change to branch pr/4280
in repository https://gitbox.apache.org/repos/asf/iotdb.git.
at 13d1f05 modify zh docs and remove en docs
This branch includes the following new commits:
new 13d1f05 modify zh docs and remove en docs
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[iotdb] 01/01: modify zh docs and remove en docs
Posted by ro...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
rong pushed a commit to branch pr/4280
in repository https://gitbox.apache.org/repos/asf/iotdb.git
commit 13d1f0581f4b67310c75d5408fa3c73f0f5fa487
Author: Steve Yurong Su <ro...@apache.org>
AuthorDate: Thu Nov 11 18:17:08 2021 +0800
modify zh docs and remove en docs
---
.../Communication-Service-Protocol/RestService.md | 242 -------------------
.../Communication-Service-Protocol/RestService.md | 256 ++++++++++++---------
site/src/main/.vuepress/config.js | 1 -
3 files changed, 145 insertions(+), 354 deletions(-)
diff --git a/docs/UserGuide/Communication-Service-Protocol/RestService.md b/docs/UserGuide/Communication-Service-Protocol/RestService.md
deleted file mode 100644
index 5141ab7..0000000
--- a/docs/UserGuide/Communication-Service-Protocol/RestService.md
+++ /dev/null
@@ -1,242 +0,0 @@
-<!--
-
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
--->
-
-## REST Service
-
-IoTDB's REST services can be used to query, write, and manage operations. It uses OpenAPI standard to define the interfaces and generate framework source codes.
-
-Now, REST Service interface uses basic authentication. Every URL request needs to carry 'authorization':'basic '+ Base64. Encode (user name +': '+ password) in the header. for example:
-
-
-### Configuration
-
-The configuration is located in `iotdb-rest.properties`, set `enable_rest_service` to `true` to enable the module while `false` to disable it.
-By default, the value is `false`.
-
-```
-enable_rest_service=true
-```
-
-Only take effects when `enable_rest_service=true`. Set `rest_service_port` as a number (1025~65535) to customize your rest service socket port.
-
-By default, the value is `18080`.
-```
-rest_service_port=18080
-```
-
-REST Service enables SSL configuration and sets "enable_https" to "true" to enable the module and "false" to disable the module.
-By default, the value is "false".
-
-```
-enable_https=false
-```
-
-Keystore path
-
-```
-key_store_path=
-```
-Password for keystore
-
-```
-key_store_pwd=
-```
-trustStore path（Not required）
-
-```
-trust_store_path=
-```
-
-Password for trustStore
-```
-trust_store_pwd=
-```
-
-SSL timeout in seconds
-
-```
-idle_timeout=5000
-```
-
-cache expiration time of REST Service (in seconds)
-
-```
-cache_expire=28800
-```
-maximum number of users stored in cache(Default 100)
-
-```
-cache_max_num=100
-```
-
-init number of users stored in cache(Default 10)
-
-```
-cache_init_num=10
-```
-
-In the following doc, we suppose your IoTDB binds 127.0.0.1 and 18080 port.
-
-### Health check
-
-Check if the iotdb service is working.
-
-Request method：get
-
-url：http://ip:port/ping
-
-The user name used in the example is: root and the password is: root
-
-Request examples
-```shell
-$ curl -H "Authorization:Basic cm9vdDpyb2901" http://127.0.0.1:18080/ping
-```
-
-Response parameters:
-
-|Parameter name |Parameter Type |description|
-| ------------ | ------------ | ------------ |
-| code | number | status code |
-| message | string | message|
-
-Response examples
-```json
-{
- "code": 200,
- "message": "SUCCESS_STATUS"
-}
-```
-
-Example of user name password authentication failure
-```json
-{
- "code": 600,
- "message": "WRONG_LOGIN_PASSWORD_ERROR"
-}
-```
-
-### SQL query interface
-
-Request method：post
-content-type：application/json
-url：http://ip:port/rest/v1/query
-
-Parameter description:
-
-|Parameter name |Parameter type |required|description|
-| ------------ | ------------ | ------------ |------------ |
-| sql | string | true | |
-
-Request examples:
-```shell
-$ curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select * from root.sg25 limit 1"}' http://127.0.0.1:18080/rest/v1/query
-```
-
-Response parameters:
-
-|Parameter name |Parameter Type |description|
-| ------------ | ------------ | ------------|
-| dataValues | array | value |
-| measurements | string | measurement |
-The first in the datavalues array is the value of the measuring point, and the second is the time
-
-Response examples:
-```json
-[
- {
- "measurements": "root.sg25.s3",
- "dataValues": [
- [
- 22.1,
- 1635232143960
- ]
- ]
- }
-]
-```
-
-### SQL non query interface
-
-Request method：post
-content-type：application/json
-url：http://ip:port/rest/v1/nonQuery
-
-Parameter description:
-
-|Parameter name |Parameter type |required|description|
-| ------------ | ------------ | ------------ |------------ |
-| sql | string | true | |
-
-Request examples:
-```shell
-$ curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"set storage group to root.ln"}' http://127.0.0.1:18080/rest/v1/nonQuery
-```
-
-Response parameters:
-
-|Parameter name |Parameter Type |description|
-| ------------ | ------------ | ------------|
-| code | integer | status code |
-| message | string | message |
-
-Response examples:
-```json
-{
-"code": 200,
-"message": "SUCCESS_STATUS"
-}
-```
-
-### write interfaces
-Request method：post
-content-type：application/json
-url：http://ip:port/rest/v1/insertTablet
-
-Parameter description
-| ------------ | ------------ | ------------ |------------ |
-| timestamps | array | true | timestamps |
-| measurements | array | true | measurement |
-| dataType | array | true | data type |
-| values | array | true | value |
-| isAligned | boolean | true | Align |
-| deviceId | boolean | true | device |
-| rowSize | integer | 是 | row size |
-
-Request examples:
-```shell
-$ curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"timestamps":[1635232143960,1635232153960],"measurements":["s3","s4"],"dataType":["INT32","BOOLEAN"],"values":[[11,22],[false,true]],"isAligned":false,"deviceId":"root.sg27","rowSize":2}' http://127.0.0.1:18080/rest/v1/insertTablet
-```
-
-Response parameters:
-
-|Parameter name |Parameter Type |description|
-| ------------ | ------------ | ------------|
-| code | integer | status code |
-| message | string | message |
-
-Response examples:
-```json
-{
-"code": 200,
-"message": "SUCCESS_STATUS"
-}
-```
-
diff --git a/docs/zh/UserGuide/Communication-Service-Protocol/RestService.md b/docs/zh/UserGuide/Communication-Service-Protocol/RestService.md
index 58fb37b..37dbdd7 100644
--- a/docs/zh/UserGuide/Communication-Service-Protocol/RestService.md
+++ b/docs/zh/UserGuide/Communication-Service-Protocol/RestService.md
@@ -19,101 +19,46 @@
-->
-## OpenAPI 协议（RESTful 服务）
+## RESTful 服务
IoTDB 的 RESTful 服务可用于查询、写入和管理操作，它使用 OpenAPI 标准来定义接口并生成框架。
-### 鉴权
-RESTful 服务使用了基础（basic）鉴权，每次 url 请求都需要在 header 中携带 'Authorization': 'Basic ' + base64.encode(username + ':' + password)
-
-例如:
-
-
-### Configuration
-配置位于“iotdb-rest.properties”中，将“enable_rest_service”设置为“true”以启用该模块，而将“false”设置为禁用该模块。
-默认情况下，该值为“false”。
-```
-enable_rest_service=true
-```
-
-仅在“enable_rest_service=true”时生效。将“rest_service_port”设置为数字（1025~65535），以自定义REST服务套接字端口。
-默认情况下，值为“18080”。
-```
-rest_service_port=18080
-```
-
-REST Service 开启ssl配置，将“enable_https”设置为“true”以启用该模块，而将“false”设置为禁用该模块。
-默认情况下，该值为“false”。
-```
-enable_https=false
-```
+### 鉴权
+RESTful 服务使用了基础（basic）鉴权，每次 URL 请求都需要在 header 中携带 `'Authorization': 'Basic ' + base64.encode(username + ':' + password)`。
-keyStore所在路径
-```
-key_store_path=
-```
-keyStore密码
-```
-key_store_pwd=
-```
-trustStore所在路径（非必填）
+### 接口
-```
-trust_store_path=
-```
+#### ping
-trustStore密码
-```
-trust_store_pwd=
-```
-ssl 超时时间单位为秒
+请求方式：`GET`
-```
-idle_timeout=5000
-```
-缓存过期时间(单位s，默认是8个小时)
+请求路径：http://ip:port/ping
-```
-cache_expire=28800
-```
-缓存中存储的最大用户数量(默认是100)
-
-```
-cache_max_num=100
-```
-
-缓存中初始化用户数量(默认是10)
+示例中使用的用户名为：root，密码为：root
-```
-cache_init_num=10
-```
+请求示例：
-## 检查iotdb服务是否在运行
-请求方式：get
-请求url：http://ip:port/ping
-示例中使用的用户名为：root，密码为：root
-请求示例
```shell
$ curl -H "Authorization:Basic cm9vdDpyb2901" http://127.0.0.1:18080/ping
```
-响应参数:
+响应参数：
|参数名称 |参数类型 |参数描述|
| ------------ | ------------ | ------------|
| code | integer | 状态码 |
| message | string | 信息提示 |
-响应示例
+响应示例：
```json
{
"code": 200,
"message": "SUCCESS_STATUS"
}
```
-用户名密码认证失败示例
+用户名密码认证失败示例：
```json
{
"code": 600,
@@ -121,11 +66,15 @@ $ curl -H "Authorization:Basic cm9vdDpyb2901" http://127.0.0.1:18080/ping
}
```
-### SQL 查询接口
-请求方式：post
-请求头：application/json
-请求url：http://ip:port/rest/v1/query
+
+#### query
+
+请求方式：`POST`
+
+请求头：`application/json`
+
+请求路径：http://ip:port/rest/v1/query
参数说明:
@@ -135,38 +84,40 @@ $ curl -H "Authorization:Basic cm9vdDpyb2901" http://127.0.0.1:18080/ping
请求示例:
```shell
-$ curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select * from root.sg25 limit 1"}' http://127.0.0.1:18080/rest/v1/query
+curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select s3, s4, s3 + 1 from root.sg27 limit 2"}' http://127.0.0.1:18080/rest/v1/query
```
响应参数:
|参数名称 |参数类型 |参数描述|
| ------------ | ------------ | ------------|
-| dataValues | array | 值 |
-| measurements | string | 测点 |
-其中dataValues数组中第一个为测点的值,第二个为时间
+| expressions | array | 结果集列名的数组 |
+| timestamps | array | 时间戳列 |
+|values|array|值列数组，列数与结果集列名数组的长度相同|
响应示例:
```json
-[
- {
- "expressions": [
- "root.sg27.s3",
- "root.sg27.s4",
- "root.sg27.s3 + 1"
- ],
- "timestamps": [t1,t2],
- "values": [[11,12],[false,true],[12.0,23.0]]
- }
-]
+{
+ "expressions": [
+ "root.sg27.s3",
+ "root.sg27.s4",
+ "root.sg27.s3 + 1"
+ ],
+ "timestamps": [1,2],
+ "values": [[11,12],[false,true],[12.0,23.0]]
+}
```
-### SQL 非查询接口
-请求方式：post
-请求头：application/json
-请求url：http://ip:port/rest/v1/nonQuery
+
+#### nonQuery
+
+请求方式：`POST`
+
+请求头：`application/json`
+
+请求路径：http://ip:port/rest/v1/nonQuery
参数说明:
@@ -176,7 +127,7 @@ $ curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290"
请求示例:
```shell
-$ curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"set storage group to root.ln"}' http://127.0.0.1:18080/rest/v1/nonQuery
+curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"set storage group to root.ln"}' http://127.0.0.1:18080/rest/v1/nonQuery
```
响应参数:
@@ -189,46 +140,129 @@ $ curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290"
响应示例：
```json
{
-"code": 200,
-"message": "SUCCESS_STATUS"
+ "code": 200,
+ "message": "SUCCESS_STATUS"
}
```
-### 写入接口
-请求方式：post
-请求头：application/json
-请求url：http://ip:port/rest/v1/insertTablet
+
+
+#### insertTablet
+
+请求方式：`POST`
+
+请求头：`application/json`
+
+请求路径：http://ip:port/rest/v1/insertTablet
参数说明:
|参数名称 |参数类型 |是否必填|参数描述|
| ------------ | ------------ | ------------ |------------ |
-| timestamps | array | 是 | 时间 |
-| measurements | array | 是 | 测点 |
-| dataType | array | 是 | 数据类型 |
-| values | array | 是 | 值 |
-| isAligned | boolean | 是 | 是否对齐 |
-| deviceId | boolean | 是 | 设备 |
-| rowSize | integer | 是 | 行数 |
-
-请求示例:
+| timestamps | array | 是 | 时间列 |
+| measurements | array | 是 | 测点名称 |
+| dataTypes | array | 是 | 数据类型 |
+| values | array | 是 | 值列，每一列中的值可以为 `null` |
+| isAligned | boolean | 是 | 是否是对齐时间序列 |
+| deviceId | boolean | 是 | 设备名称 |
+
+请求示例：
```shell
-$ curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"timestamps":[1635232143960,1635232153960],"measurements":["s3","s4"],"dataType":["INT32","BOOLEAN"],"values":[[11,22],[false,true]],"isAligned":false,"deviceId":"root.sg27","rowSize":2}' http://127.0.0.1:18080/rest/v1/insertTablet
+curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"timestamps":[1635232143960,1635232153960],"measurements":["s3","s4"],"dataTypes":["INT32","BOOLEAN"],"values":[[11,null],[false,true]],"isAligned":false,"deviceId":"root.sg27"}' http://127.0.0.1:18080/rest/v1/insertTablet
```
-响应参数:
+响应参数：
|参数名称 |参数类型 |参数描述|
| ------------ | ------------ | ------------|
| code | integer | 状态码 |
| message | string | 信息提示 |
-响应示例:
+响应示例：
```json
{
-"code": 200,
-"message": "SUCCESS_STATUS"
+ "code": 200,
+ "message": "SUCCESS_STATUS"
}
```
+
+### 配置
+
+配置位于 `iotdb-rest.properties` 中。
+
+
+
+* 将 `enable_rest_service` 设置为 `true` 以启用该模块，而将 `false` 设置为禁用该模块。默认情况下，该值为 `false`。
+
+```properties
+enable_rest_service=true
+```
+
+* 仅在 `enable_rest_service=true` 时生效。将 `rest_service_port `设置为数字（1025~65535），以自定义REST服务套接字端口。默认情况下，值为 `18080`。
+
+```properties
+rest_service_port=18080
+```
+
+* REST Service 是否开启 SSL 配置，将 `enable_https` 设置为 `true` 以启用该模块，而将 `false` 设置为禁用该模块。默认情况下，该值为 `false`。
+
+```properties
+enable_https=false
+```
+
+* keyStore 所在路径（非必填）
+
+```properties
+key_store_path=
+```
+
+
+* keyStore 密码（非必填）
+
+```properties
+key_store_pwd=
+```
+
+
+* trustStore 所在路径（非必填）
+
+```properties
+trust_store_path=
+```
+
+* trustStore 密码（非必填）
+
+```properties
+trust_store_pwd=
+```
+
+
+* SSL 超时时间，单位为秒
+
+```properties
+idle_timeout=5000
+```
+
+
+* 缓存客户登录信息的过期时间（用于加速用户鉴权的速度，单位为秒，默认是8个小时）
+
+```properties
+cache_expire=28800
+```
+
+
+* 缓存中存储的最大用户数量（默认是100）
+
+```properties
+cache_max_num=100
+```
+
+* 缓存初始容量（默认是10）
+
+```properties
+cache_init_num=10
+```
+
+
diff --git a/site/src/main/.vuepress/config.js b/site/src/main/.vuepress/config.js
index a9eae09..78160ab 100644
--- a/site/src/main/.vuepress/config.js
+++ b/site/src/main/.vuepress/config.js
@@ -725,7 +725,6 @@ var config = {
children: [
['Communication-Service-Protocol/Programming-Thrift','Thrift'],
['Communication-Service-Protocol/Programming-MQTT','MQTT'],
- ['Communication-Service-Protocol/RestService','REST'],
]
},
{