Update docs for v3.4

kyubotics · Jan 25, 2018 · 249c840 · 249c840
1 parent c552c2f
commit 249c840
Show file tree

Hide file tree

Showing 4 changed files with 33 additions and 4 deletions.
diff --git a/docs/3.4/CommunicationMethods.md b/docs/3.4/CommunicationMethods.md
@@ -71,3 +71,31 @@ API 的调用方式和插件作为 WebSocket 服务端的 `/api/` 接口使用
 插件启动时会启动一个**保持连接**的客户端用于连接事件上报接口，即 `ws_reverse_event_url` 指定的接口，在后续接收到酷 Q 的事件时，会通过这个连接发送事件数据。发送事件数据格式和 HTTP POST 方式上报的完全一致，见 [上报数据格式](/Post#上报数据格式)，事件列表见 [事件列表](/Post#事件列表)。
 
 与 HTTP 上报不同的是，这里上报不会对数据进行签名（即 HTTP 上报中的 `X-Signature` 请求头在这里没有等价的东西），并且也不会处理响应数据。
+
+## WebSocket 的 API 调用响应顺序问题
+
+由于 WebSocket 的通信不像 HTTP 那样是固定的一来一回，而是一直保持连接，大多 WebSocket 框架都采用事件驱动的方式来提供接口。这就导致，在通过 WebSocket 进行**连续** API 调用时，很多情况下无法确切地知道插件返回的响应是对应哪次调用。因此插件现加入了 echo 机制，允许用户在调用 API 时在调用数据（JSON 对象）中加入一个 `echo` 字段（数据类型任意），以标记此次调用，插件会在该调用的响应数据中将其原样返回。
+
+### 调用示例
+
+```json
+{
+    "action": "send_private_msg",
+    "params": {
+        "user_id": 123456,
+        "message": "你好"
+    },
+    "echo": 1648451782
+}
+```
+
+### 响应示例
+
+```json
+{
+    "status": "ok",
+    "retcode": 0,
+    "data": null,
+    "echo": 1648451782
+}
+```
diff --git a/docs/3.4/Configuration.md b/docs/3.4/Configuration.md
@@ -44,6 +44,7 @@ secret=kP9yK2lrGxoymmpo
 | `ws_reverse_api_url` | 空 | 反向 WebSocket API 地址 |
 | `ws_reverse_event_url` | 空 | 反向 WebSocket 事件上报地址 |
 | `ws_reverse_reconnect_interval` | `3000` | 反向 WebSocket 客户端断线重连间隔，单位毫秒 |
+| `ws_reverse_reconnect_on_code_1000` | `no` | 是否在关闭状态码为 1000 的时候重连 |
 | `use_ws_reverse` | `no` | 是否使用反向 WebSocket 服务，即插件作为 WebSocket 客户端主动连接指定的 API 和事件上报地址，见 [通信方式的第三种](/CommunicationMethods#插件作为-websocket-客户端（反向-websocket）) |
 | `post_url` | 空 | 消息和事件的上报地址，通过 POST 方式请求，数据以 JSON 格式发送 |
 | `access_token` | 空 | API 访问 token，如果不为空，则会在接收到请求时验证 `Authorization` 请求头是否为 `Token xxxxxxxx`，`xxxxxxxx` 为 access token |

diff --git a/docs/3.4/WebSocketAPI.md b/docs/3.4/WebSocketAPI.md
@@ -24,7 +24,7 @@ Authorization: Token kSLuTF2GC2Q4q4ugm3
 
 或者在 URI 中指定，如 `/api/?access_token=kSLuTF2GC2Q4q4ugm3`。
 
-## `/api/`
+## `/api/` 接口
 
 连接此接口后，向插件发送如下结构的 JSON 对象，即可调用相应的 API：
 
@@ -45,7 +45,7 @@ Authorization: Token kSLuTF2GC2Q4q4ugm3
 ```json
 {
     "status": "failed",
-    "retcode": 1404
+    "retcode": 1404,
     "data": null
 }
 ```
@@ -63,7 +63,7 @@ Authorization: Token kSLuTF2GC2Q4q4ugm3
 
 对于 `/api/` 接口，你可以保持连接，也可以每次请求是重新建立连接，区别不是很大。
 
-## `/event/`
+## `/event/` 接口
 
 连接此接口后，插件会在收到事件后推送至客户端，推送的格式和 HTTP POST 方式上报的完全一致，见 [上报数据格式](/Post#上报数据格式)，事件列表见 [事件列表](/Post#事件列表)。
 

diff --git a/docs/index.html b/docs/index.html
@@ -8,7 +8,7 @@
 </head>
 <body>
   <script>
-      window.location.replace('3.3/' + window.location.hash);
+      window.location.replace('3.4/' + window.location.hash);
   </script>
 </body>
 </html>