Merge pull request #475 from hxy7yx/v2.8-1

[v2.8]add api: read/paginate
emqx · Jun 12, 2024 · 099122d · 099122d
2 parents ab61e58 + 9bdae75
commit 099122d
Show file tree

Hide file tree

Showing 2 changed files with 128 additions and 2 deletions.
diff --git a/en_US/api/rw.md b/en_US/api/rw.md
@@ -21,7 +21,7 @@
     //node name (required)
     "node": "modbus-tcp-1",
     //group name (required)
-    "group": "config_modbus_tcp_sample_2"
+    "group": "config_modbus_tcp_sample_2",
     //synchronous read (optional, default false)
     "sync": false,
     //filter (optional)
@@ -61,6 +61,69 @@
 The value is displayed only when the value is read correctly, when the value is read incorrectly, the error code is displayed, not the value.
 :::
 
+## Read Tag(pagination)
+
+*POST*  /api/v2/read/paginate
+
+### Request Headers
+
+**Content--Type**  application/json
+
+**Authorization** Bearer \<token\>
+
+### Response Status
+
+* 200
+
+### Body
+
+```json
+{
+    //node name (required)
+    "node": "modbus-tcp-1",
+    //group name (required)
+    "group": "config_modbus_tcp_sample_2",
+    //synchronous read (optional, default false)
+    "sync": false,
+    //filter (optional)
+    "query": {
+        //tag name substring match (optional)
+        "name": "data",
+        //tag description substring match (optional)
+        "description": "switch",
+        //current page (optional)
+        "currentPage": 1,
+        //number of tags per page (optional)
+        "pageSize": 10,
+        //response error tags only (optional)
+        "isError": true
+    }
+}
+```
+
+### Response
+
+```json
+{
+   "meta": {"currentPage": 1, "pageSize": 10, "total": 1},
+   "items": [ {
+            "name": "tag1",
+            "type": 4,
+            "address": "1!400001",
+            "attribute": 8,
+            "description": "",
+            "precison": 0,
+            "decimal": 0,
+            "bias": 0,
+            "error": 3002 // "value": 123
+        } ]
+}
+```
+
+::: tip
+The **value** is displayed only when the value is read correctly, when the value is read incorrectly, the error code is displayed with **error**.
+:::
+
 ## Write Tag
 
 ### Write One Tag

diff --git a/zh_CN/api/rw.md b/zh_CN/api/rw.md
@@ -21,7 +21,7 @@
     //node name (required)
     "node": "modbus-tcp-1",
     //group name (required)
-    "group": "config_modbus_tcp_sample_2"
+    "group": "config_modbus_tcp_sample_2",
     //synchronous read (optional, default false)
     "sync": false,
     //filter (optional)
@@ -61,6 +61,69 @@
 当某个点位读数值出错时，将显示 **error** 字段，不再显示 **value** 字段。
 :::
 
+## 读 Tag(分页)
+
+*POST*  /api/v2/read/paginate
+
+### 请求头部
+
+**Content--Type**  application/json
+
+**Authorization** Bearer \<token\>
+
+### 响应状态
+
+* 200
+
+### 请求体
+
+```json
+{
+    //node name (required)
+    "node": "modbus-tcp-1",
+    //group name (required)
+    "group": "config_modbus_tcp_sample_2",
+    //synchronous read (optional, default false)
+    "sync": false,
+    //filter (optional)
+    "query": {
+        //tag name substring match (optional)
+        "name": "data",
+        //tag description substring match (optional)
+        "description": "switch",
+        //current page (optional)
+        "currentPage": 1,
+        //number of tags per page (optional)
+        "pageSize": 10,
+        //response error tags only (optional)
+        "isError": true
+    }
+}
+```
+
+### 响应
+
+```json
+{
+   "meta": {"currentPage": 1, "pageSize": 10, "total": 1},
+   "items": [ {
+            "name": "tag1",
+            "type": 4,
+            "address": "1!400001",
+            "attribute": 8,
+            "description": "",
+            "precison": 0,
+            "decimal": 0,
+            "bias": 0,
+            "error": 3002 // "value": 123
+        } ]
+}
+```
+
+::: tip 注意
+当某个点位读数值出错时，显示 **error** 字段；读取正常时显示 **value** 字段。
+:::
+
 ## 写 Tag
 
 ### 写一个 Tag