Merge remote-tracking branch 'origin/master'

# Conflicts:
#	src/main/java/com/fanruan/hihidata/datasource/server/http/HttpKits.java

README.md

@@ -1,24 +1,75 @@
 # API数据源使用示例
 
+**注意：** 数据源表的数据更新的时候，会根据实际情况启动使用该数据源表的分析表的更新，最小更新间隔为1个小时。
+
+*举例：当10点更新了一张数据源表，当表数据写入完成后，会立即更新到九数云中，如果10点10分再次更新这张表，则需要在11点的时候，才会将最新的数据更新到九数云中，13点15的时候再次更新这张表的数据，则在数据写入完成后，会立即更新到九数云中。*
+
 ## 调用示例代码
 
+### 开启API数据源
+
 ```java
 Authentication authentication = new Authentication("#key", "#secret");
 DatasourceOperation operation = new DatasourceOperation(authentication);
 operation.open();
-// 创建一个分组，如果已经存在，则直接跳过
-operation.createGroup("TestGroup");
-// 在分组下创建一个表，返回创建的表的ID，如果表已经存在，则直接返回表ID
-String tableId = operation.createTable("HelloTable", "TestGroup");
-// 获取上传文件的url
+```
+
+在开启后，可以在企业数据的"数据导入"菜单看到如下图所示的API数据源入口
+![api_datasource](/screenshots/api_datasource.png)
+
+### 创建分组
+```java
+Authentication authentication = new Authentication("#key", "#secret");
+DatasourceOperation operation = new DatasourceOperation(authentication);
+// 创建表并返回分组Id
+String groupId = operation.createGroup("我的分组");
+```
+
+### 创建表
+
+```java
+Authentication authentication = new Authentication("#key", "#secret");
+DatasourceOperation operation = new DatasourceOperation(authentication);
+// 创建表并返回表id
+String tableId = operation.createTable("HelloTable", "#分组Id（可选）");
+```
+
+### 更新表数据
+
+```java
+Authentication authentication = new Authentication("#key", "#secret");
+DatasourceOperation operation = new DatasourceOperation(authentication);
+// 创建表并返回表id
+String tableId = "上一步获取到表id";
+// 获取给该表提供数据的文件的上传地址
 String fileUploadUrl = operation.requestUploadUrl(tableId);
 // 将数据文件上传
 HttpKits.upload(fileUploadUrl, new File(System.getProperty("user.dir") + "/data/地区数据分析.csv"));
 // 标记该表的数据已经上传完成
 operation.markAsFinish(tableId);
+```
+
+在调用了上述代码后，就可以在API数据源页面看到新增的表和其数据了，这时就可以和其他数据源表一样，添加到项目中使用了：
+
+![api_datasource_effect](/screenshots/api_datasource_effect.png)
+
+
+### 删除表
+```java
+Authentication authentication = new Authentication("#key", "#secret");
+DatasourceOperation operation = new DatasourceOperation(authentication);
+String tableId = "#待删除的表id";
+operation.deleteTable(tableId);
+```
 
+### 删除所有表
+```java
+Authentication authentication = new Authentication("#key", "#secret");
+DatasourceOperation operation = new DatasourceOperation(authentication);
+operation.reset();
 ```
 
+
 ## API文档
 
 ### 开启API数据源
@@ -57,21 +108,78 @@ operation.markAsFinish(tableId);
 
 请求类型：POST	
 
-请求参数：```{"name":"#分组名"}```
+请求参数：```{"groupName":"#分组名"}```
+
+返回值：
+```json 
+{
+"success":true,
+"code":"200",
+"data":"#groupId"
+}
+```
 
 #### 读取所有分组
 请求地址：```/api/v1/datasource/group/list```	
 
 请求类型：POST
 
+返回值：
+```json
+{
+  "success": true,
+  "code": "200",
+  "data": [{"id":"#groupId", "name": "#groupName"}]
+}
+```
+
+#### 读取分组下的所有表
+请求地址：```/api/v1/datasource/group/table/list```
+
+请求类型：POST
+
+请求参数：```{"groupId":"#分组Id"}```
+
+返回值：
+```json
+{
+  "success": true,
+  "code": "200",
+  "data": [{"id":"#tableId", "name": "#tableName"}]
+}
+```
+
+#### 修改分组名
+请求地址：```/api/v1/datasource/group/modify```
+
+请求类型：POST
+
+请求参数： ``` {"groupId":"#分组Id", "groupName":"#新的分组名"} ```
+
+返回值：
+```json
+{
+  "success": true,
+  "code": "200"
+}
+```
+
 ### 表管理
 #### 创建数据源表	
 请求地址：```/api/v1/datasource/table/create```
 
 请求类型：POST
 
-请求参数： ``` {"group":"#分组名", "name":"#表名"} ```，分组名可以不传，默认值为“默认”
+请求参数： ``` {"tableName":"#表名", "groupId":"#分组Id（可选）"} ```
 
+返回值：
+```json
+{
+  "success": true,
+  "code": "200",
+  "data":"#tableId"
+}
+```
 
 #### 获取表数据上传地址	
 请求地址：```/api/v1/datasource/table/upload/url```
@@ -80,9 +188,70 @@ operation.markAsFinish(tableId);
 
 请求参数：``` {"tableId":"#表Id"} ```
 
+返回值：
+```json
+{
+  "success": true,
+  "code": "200",
+  "data":"#file_upload_url"
+}
+```
+
 #### 标记表数据已上传完成	
 请求地址：```/api/v1/datasource/table/upload/finish```
 
 请求类型：POST	
 
 请求参数：``` {"tableId":"#表Id"} ```
+
+返回值：
+```json
+{
+  "success": true,
+  "code": "200"
+}
+```
+
+#### 修改数据源表名（暂未启用）
+请求地址：```/api/v1/datasource/table/modify```
+
+请求类型：POST
+
+请求参数： ``` {"tableId":"#表Id", "tableName":"#新的表名"} ```
+
+返回值：
+```json
+{
+  "success": true,
+  "code": "200"
+}
+```
+
+#### 删除数据源表
+请求地址：```/api/v1/datasource/table/delete```
+
+请求类型：POST
+
+请求参数： ``` {"tableId":"#表Id"} ```
+
+返回值：
+```json
+{
+  "success": true,
+  "code": "200"
+}
+```
+
+#### 重置整个数据源
+请求地址：```/api/v1/datasource/reset```
+
+请求类型：POST
+
+返回值：
+```json
+{
+  "success": true,
+  "code": "200"
+}
+```
+

src/main/java/com/fanruan/hihidata/datasource/server/DatasourceOperation.java

@@ -3,6 +3,7 @@ package com.fanruan.hihidata.datasource.server;
 import com.fanruan.hihidata.datasource.server.http.HttpKits;
 import org.apache.http.HttpEntity;
 import org.apache.http.entity.StringEntity;
+import org.json.JSONArray;
 import org.json.JSONObject;
 
 import java.nio.charset.StandardCharsets;
@@ -10,6 +11,7 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
+ * API数据源所有操作的示例集合，只需要传入授权参数即可
  * @author richie
  * Created by richie on 2022/9/16
  */
@@ -21,23 +23,91 @@ public class DatasourceOperation {
         this.auth = auth;
     }
 
+    /**
+     * 开启或者关闭API数据源入口
+     * @throws Exception 操作失败则抛出此异常
+     */
     public void open() throws Exception {
         JSONObject body = new JSONObject();
         body.put("status", "1");
         HttpEntity entity = new StringEntity(body.toString(), StandardCharsets.UTF_8);
+        HttpKits.post(String.format("%s/api/v1/datasource/status/modify", ProjectConstants.BASE_URI), headers(), entity);
+    }
+
+    /**
+     * 查看当前API数据源的开关状态
+     * @return API数据源处于开启状态，则返回"1"，否则返回"0"
+     * @throws Exception 操作失败则抛出此异常
+     */
+    public String status() throws Exception {
         Map<String, String> params = new HashMap<>();
-        params.put("status", "1");
-        String r = HttpKits.post(String.format("%s/api/v1/datasource/status/modify", ProjectConstants.BASE_URI), headers(), params);
-        System.out.println("result=" + r);
+        String res = HttpKits.post(String.format("%s/api/v1/datasource/status", ProjectConstants.BASE_URI), headers(), params);
+        JSONObject data = new JSONObject(res);
+        return data.getString("data");
     }
 
-    public void createGroup(String groupName) throws Exception {
+    /**
+     * 在API数据源下创建一个分组
+     * @param groupName 分组名
+     * @return 该分组的Id
+     * @throws Exception 操作失败则抛出此异常
+     */
+    public String createGroup(String groupName) throws Exception {
         JSONObject body = new JSONObject();
-        body.put("name", groupName);
+        body.put("groupName", groupName);
         HttpEntity entity = new StringEntity(body.toString(), StandardCharsets.UTF_8);
-        HttpKits.post(String.format("%s/api/v1/datasource/group/create", ProjectConstants.BASE_URI), headers(), entity);
+        String res = HttpKits.post(String.format("%s/api/v1/datasource/group/create", ProjectConstants.BASE_URI), headers(), entity);
+        JSONObject data = new JSONObject(res);
+        return data.getString("data");
+    }
+
+    /**
+     * 修改分组的名字
+     * @param groupId 分组Id
+     * @param newGroupName 新的分组名字
+     * @throws Exception 操作失败则抛出此异常
+     */
+    public void modifyGroup(String groupId, String newGroupName) throws Exception {
+        JSONObject body = new JSONObject();
+        body.put("groupId", groupId);
+        body.put("groupName", newGroupName);
+        HttpEntity entity = new StringEntity(body.toString(), StandardCharsets.UTF_8);
+        HttpKits.post(String.format("%s/api/v1/datasource/group/modify", ProjectConstants.BASE_URI), headers(), entity);
+    }
+
+    /**
+     * 列出所有的分组
+     * @return 以JSON数组的形式输出所有分组的信息的集合
+     * @throws Exception 操作失败则抛出此异常
+     */
+    public JSONArray listAllGroup() throws Exception {
+        Map<String, String> params = new HashMap<>();
+        String res = HttpKits.post(String.format("%s/api/v1/datasource/group/list", ProjectConstants.BASE_URI), headers(), params);
+        JSONObject data = new JSONObject(res);
+        return data.getJSONArray("data");
+    }
+
+    /**
+     * 列出指定分组下所有的数据源表
+     * @param groupId 分组Id
+     * @return 分组下的所有数据源表组成的一个JSON数组
+     * @throws Exception 操作失败则抛出此异常
+     */
+    public JSONArray listTablesOfGroup(String groupId) throws Exception {
+        JSONObject body = new JSONObject();
+        body.put("groupId", groupId);
+        HttpEntity entity = new StringEntity(body.toString(), StandardCharsets.UTF_8);
+        String res = HttpKits.post(String.format("%s/api/v1/datasource/group/table/list", ProjectConstants.BASE_URI), headers(), entity);
+        JSONObject data = new JSONObject(res);
+        return data.getJSONArray("data");
     }
 
+    /**
+     * 在默认分组下创建一个数据源表
+     * @param tableName 数据源表名
+     * @return 数据源表Id
+     * @throws Exception 操作失败则抛出此异常
+     */
     public String createTable(String tableName) throws Exception {
         JSONObject body = new JSONObject();
         body.put("tableName", tableName);
@@ -47,14 +117,43 @@ public class DatasourceOperation {
         return data.getString("data");
     }
 
-    public String createTable(String tableName, String groupName) throws Exception {
+    /**
+     * 在指定的分组下创建 一个数据源表
+     * @param tableName 数据源表名
+     * @param groupId 分组Id
+     * @return 数据源表Id
+     * @throws Exception 操作失败则抛出此异常
+     */
+    public String createTable(String tableName, String groupId) throws Exception {
+        JSONObject body = new JSONObject();
+        body.put("tableName", tableName);
+        body.put("groupId", groupId);
+        HttpEntity entity = new StringEntity(body.toString(), StandardCharsets.UTF_8);
+        String res = HttpKits.post(String.format("%s/api/v1/datasource/table/create", ProjectConstants.BASE_URI), headers(), entity);
+        JSONObject data = new JSONObject(res);
+        return data.getString("data");
+    }
+
+    /**
+     * 修改已有的数据源表的名字
+     * @param tableId 数据源表Id
+     * @param newTableName 新的数据源表名字
+     * @throws Exception 操作失败则抛出此异常
+     */
+    public void modifyTable(String tableId, String newTableName) throws Exception {
         JSONObject body = new JSONObject();
-        body.put("name", tableName);
-        body.put("group", groupName);
+        body.put("tableId", tableId);
+        body.put("tableName", newTableName);
         HttpEntity entity = new StringEntity(body.toString(), StandardCharsets.UTF_8);
-        return HttpKits.post(String.format("%s/api/v1/datasource/table/create", ProjectConstants.BASE_URI), headers(), entity);
+        HttpKits.post(String.format("%s/api/v1/datasource/table/modify", ProjectConstants.BASE_URI), headers(), entity);
     }
 
+    /**
+     * 生成指定的数据源表数据上传的地址
+     * @param tableId 数据源表Id
+     * @return 上传数据的地址
+     * @throws Exception 操作失败则抛出此异常
+     */
     public String requestUploadUrl(String tableId) throws Exception {
         JSONObject body = new JSONObject();
         body.put("tableId", tableId);
@@ -64,6 +163,11 @@ public class DatasourceOperation {
         return data.getString("data");
     }
 
+    /**
+     * 标记数据源表的数据上传已完成
+     * @param tableId 数据源表Id
+     * @throws Exception 操作失败则抛出此异常
+     */
     public void markAsFinish(String tableId) throws Exception {
         JSONObject body = new JSONObject();
         body.put("tableId", tableId);
@@ -71,6 +175,27 @@ public class DatasourceOperation {
         HttpKits.post(String.format("%s/api/v1/datasource/table/upload/finish", ProjectConstants.BASE_URI), headers(), entity);
     }
 
+    /**
+     * 删除数据源表
+     * @param tableId 数据源表Id
+     * @throws Exception 操作失败则抛出此异常
+     */
+    public void deleteTable(String tableId) throws Exception {
+        JSONObject body = new JSONObject();
+        body.put("tableId", tableId);
+        HttpEntity entity = new StringEntity(body.toString(), StandardCharsets.UTF_8);
+        HttpKits.post(String.format("%s/api/v1/datasource/table/delete", ProjectConstants.BASE_URI), headers(), entity);
+    }
+
+    /**
+     * 删除API数据源下的所有分组和表
+     * @throws Exception 操作失败则抛出此异常
+     */
+    public void reset() throws Exception {
+        Map<String, String> params = new HashMap<>();
+        HttpKits.post(String.format("%s/api/v1/datasource/reset", ProjectConstants.BASE_URI), headers(), params);
+    }
+
     private Map<String, String> headers() throws Exception {
         Map<String, String> headers = new HashMap<>();
         headers.put("Authorization", auth.getToken());

src/main/java/com/fanruan/hihidata/datasource/server/ServerApplication.java

@@ -11,14 +11,19 @@ import java.io.File;
 public class ServerApplication {
 
     public static void main(String... args) throws Exception {
-        Authentication authentication = new Authentication("ZDdjOWJhZGI5OTBjNDI3ZWE2MzAzYWYwY2UyMTI1Zjg=", "103d4522039be2d17588882b7ae5ba12");
+        Authentication authentication;
+        if (args.length > 1) {
+            authentication = new Authentication(args[0], args[1]);
+        } else {
+            authentication = new Authentication("#key", "#secret");
+        }
         DatasourceOperation operation = new DatasourceOperation(authentication);
-        //operation.open();
-        // 创建一个分组，如果已经存在，则直接跳过
-        //operation.createGroup("TestGroup");
-        // 在分组下创建一个表，返回创建的表的ID，如果表已经存在，则直接返回表ID
-        String tableId = operation.createTable("HelloTable");
-        // 获取上传文件的url
+
+        String groupId = operation.createGroup("我的分组");
+
+        String tableId = operation.createTable("地区数据", groupId);
+
+        // 获取给该表提供数据的文件的上传地址
         String fileUploadUrl = operation.requestUploadUrl(tableId);
         // 将数据文件上传
         HttpKits.upload(fileUploadUrl, new File(System.getProperty("user.dir") + "/data/地区数据分析.csv"));

src/main/java/com/fanruan/hihidata/datasource/server/http/HttpKits.java

@@ -230,7 +230,18 @@ public class HttpKits {
      * @throws IOException 上传中出现错误则抛出此异常
      */
     public static void upload(String url, File file) throws IOException {
-        upload(url, file, StandardCharsets.UTF_8);
+        upload(url, file, StandardCharsets.UTF_8, HttpRequestType.PUT);
+    }
+
+    /**
+     * 上传文件到指定的服务器
+     *
+     * @param url  接收文件的服务器地址
+     * @param file 要上传的文件，默认的文件编码为utf-8
+     * @throws IOException 上传中出现错误则抛出此异常
+     */
+    public static void upload(String url, File file, HttpRequestType requestType) throws IOException {
+        upload(url, file, StandardCharsets.UTF_8, requestType);
     }
 
     /**
@@ -241,8 +252,8 @@ public class HttpKits {
      * @param charset 文件的编码
      * @throws IOException 上传中出现错误则抛出此异常
      */
-    public static void upload(String url, File file, Charset charset) throws IOException {
-        upload(url, new FileEntity(file), charset);
+    public static void upload(String url, File file, Charset charset, HttpRequestType requestType) throws IOException {
+        upload(url, new FileEntity(file), charset, requestType);
     }
 
     /**
@@ -253,8 +264,8 @@ public class HttpKits {
      * @param charset    文件的编码
      * @throws IOException 上传中出现错误则抛出此异常
      */
-    public static void upload(String url, FileEntity fileEntity, Charset charset) throws IOException {
-        upload(url, fileEntity, charset, Collections.emptyMap(), HttpRequestType.PUT);
+    public static void upload(String url, FileEntity fileEntity, Charset charset, HttpRequestType requestType) throws IOException {
+        upload(url, fileEntity, charset, Collections.emptyMap(), requestType);
     }
 
     /**