Merge pull request #816 from taosdata/feature/slguan

Instructions for using the RESTful interface

documentation/webdocs/markdowndocs/connector-ch.md

@@ -306,21 +306,34 @@ import taos
 
 ### HTTP请求格式 
 
-​	`http://<ip>:<PORT>/rest/sql`
+```
+http://<ip>:<PORT>/rest/sql
+```
+
+​参数说明：
 
-​    参数说明：
+- IP: 集群中的任一台主机
+- PORT: 配置文件中httpPort配置项，缺省为6020
 
-​    IP: 集群中的任一台主机
+例如：http://192.168.0.1:6020/rest/sql 是指向IP地址为192.168.0.1的URL. 
 
-​    PORT: 配置文件中httpPort配置项，缺省为6020 
+HTTP请求的Header里需带有身份认证信息，TDengine支持Basic认证与自定义认证两种机制，后续版本将提供标准安全的数字签名机制来做身份验证。
 
-如：http://192.168.0.1:6020/rest/sql 是指向IP地址为192.168.0.1的URL. 
+- 自定义身份认证信息如下所示（<token>稍后介绍）
 
-HTTP请求的Header里需带有身份认证信息，TDengine单机版仅支持Basic认证机制。
+```
+Authorization: Taosd <TOKEN>
+```
+
+- Basic身份认证信息如下所示
+
+```
+Authorization: Basic <TOKEN>
+```
 
 HTTP请求的BODY里就是一个完整的SQL语句，SQL语句中的数据表应提供数据库前缀，例如\<db-name>.\<tb-name>。如果表名不带数据库前缀，系统会返回错误。因为HTTP模块只是一个简单的转发，没有当前DB的概念。 
 
-使用curl来发起一个HTTP Request, 语法如下：
+使用curl通过自定义身份认证方式来发起一个HTTP Request, 语法如下：
 
 ```
 curl -H 'Authorization: Basic <TOKEN>' -d '<SQL>' <ip>:<PORT>/rest/sql
@@ -332,11 +345,12 @@ curl -H 'Authorization: Basic <TOKEN>' -d '<SQL>' <ip>:<PORT>/rest/sql
 curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql
 ```
 
-其中，`TOKEN`为`{username}:{password}`经过Base64编码之后的字符串，例如`root:taosdata`编码后为`cm9vdDp0YW9zZGF0YQ==`
+其中，`TOKEN`为`{username}:{password}`经过Base64编码之后的字符串, 例如`root:taosdata`编码后为`cm9vdDp0YW9zZGF0YQ==`
 
 ### HTTP返回格式
 
-返回值为JSON格式，如下：
+返回值为JSON格式，如下:
+
 ```
 {
     "status": "succ",
@@ -351,26 +365,60 @@ curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql
 
 说明：
 
-- 第一行”status”告知操作结果是成功还是失败;
-- 第二行”head”是表的定义，如果不返回结果集，仅有一列“affected_rows”;
-- 第三行是具体返回的数据，一排一排的呈现。如果不返回结果集，仅[[affected_rows]]
-- 第四行”rows”表明总共多少行数据
+- status: 告知操作结果是成功还是失败
+- head: 表的定义，如果不返回结果集，仅有一列“affected_rows”
+- data: 具体返回的数据，一排一排的呈现,如果不返回结果集，仅[[affected_rows]]
+- rows: 表明总共多少行数据
 
-### 使用示例
+### 自定义授权码
+
+HTTP请求中需要带有授权码`<TOKEN>`, 用于身份识别。授权码通常由管理员提供, 可简单的通过发送`HTTP GET`请求来获取授权码, 操作如下：
 
-- 在demo库里查询表t1的所有记录, curl如下： 
+```
+curl http://<ip>:6020/rest/login/<username>/<password>
+```
 
-  `curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6020/rest/sql`
+其中, `ip`是TDengine数据库的IP地址, `username`为数据库用户名, `password`为数据库密码, 返回值为`JSON`格式, 各字段含义如下：
 
-  返回值：
+- status：请求结果的标志位
+
+- code：返回值代码
+
+- desc: 授权码
+
+获取授权码示例：
+
+```
+curl http://192.168.0.1:6020/rest/login/root/taosdata
+```
+
+返回值：
+
+```
+{
+  "status": "succ",
+  "code": 0,
+  "desc": 
+"/KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04"
+}
+```
+
+### 使用示例
+
+- 在demo库里查询表t1的所有记录： 
+
+```
+curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6020/rest/sql`
+```
+返回值：
 
 ```
 {
     "status": "succ",
     "head": ["column1","column2","column3"],
     "data": [
-        ["2017-12-12 23:44:25.730", 1, 2.3],
-        ["2017-12-12 22:44:25.728", 4, 5.6]
+        ["2017-12-12 22:44:25.728",4,5.60000],
+        ["2017-12-12 23:44:25.730",1,2.30000]
     ],
     "rows": 2
 }
@@ -378,9 +426,11 @@ curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql
 
 - 创建库demo：
 
-  `curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 192.168.0.1:6020/rest/sql`
+```
+curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 192.168.0.1:6020/rest/sql`
+```
 
-  返回值：
+返回值：
 ```
 {
     "status": "succ",
@@ -390,6 +440,64 @@ curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql
 }
 ```
 
+### 其他用法
+
+#### 结果集采用Unix时间戳
+
+HTTP请求URL采用`sqlt`时，返回结果集的时间戳将采用Unix时间戳格式表示，例如
+
+```
+curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6020/rest/sqlt
+```
+
+返回值：
+
+```
+{
+    "status": "succ",
+    "head": ["column1","column2","column3"],
+    "data": [
+        [1513089865728,4,5.60000],
+        [1513093465730,1,2.30000]
+    ],
+    "rows": 2
+}
+```
+
+#### 结果集采用UTC时间字符串
+
+HTTP请求URL采用`sqlutc`时，返回结果集的时间戳将采用UTC时间字符串表示，例如
+```
+  curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6020/rest/sqlutc
+```
+
+返回值：
+
+```
+{
+    "status": "succ",
+    "head": ["column1","column2","column3"],
+    "data": [
+        ["2017-12-12T22:44:25.728+0800",4,5.60000],
+        ["2017-12-12T23:44:25.730+0800",1,2.30000]
+    ],
+    "rows": 2
+}
+```
+
+### 重要配置项
+
+下面仅列出一些与RESTFul接口有关的配置参数，其他系统参数请看配置文件里的说明。注意：配置修改后，需要重启taosd服务才能生效
+
+- httpIp: 对外提供RESTFul服务的IP地址，默认绑定到0.0.0.0
+- httpPort: 对外提供RESTFul服务的端口号，默认绑定到6020
+- httpMaxThreads: 启动的线程数量，默认为2
+- httpCacheSessions: 缓存连接的数量，并发请求数目需小于此数值的10倍，默认值为100
+- restfulRowLimit: 返回结果集（JSON格式）的最大条数，默认值为10240
+- httpEnableCompress: 是否支持压缩，默认不支持，目前TDengine仅支持gzip压缩格式
+- httpDebugFlag: 日志开关，131：仅错误和报警信息，135：所有，默认131
+
+
 ## Go Connector
 
 #### 安装TDengine