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 <[email protected]> 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'], ] }, {
