diff --git a/README.md b/README.md index fe059e3..67e3006 100644 --- a/README.md +++ b/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数据源 @@ -52,26 +103,83 @@ operation.markAsFinish(tableId); ``` ### 分组管理 -#### 创建分组 +#### 创建分组 请求地址:```/api/v1/datasource/group/create``` 请求类型: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" +} +``` + diff --git a/screenshots/api_datasource.png b/screenshots/api_datasource.png new file mode 100644 index 0000000..998c696 Binary files /dev/null and b/screenshots/api_datasource.png differ diff --git a/screenshots/api_datasource_effect.png b/screenshots/api_datasource_effect.png new file mode 100644 index 0000000..07a5220 Binary files /dev/null and b/screenshots/api_datasource_effect.png differ diff --git a/src/main/java/com/fanruan/hihidata/datasource/server/DatasourceOperation.java b/src/main/java/com/fanruan/hihidata/datasource/server/DatasourceOperation.java index 699a6ff..d600c93 100644 --- a/src/main/java/com/fanruan/hihidata/datasource/server/DatasourceOperation.java +++ b/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 params = new HashMap<>(); + 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"); + } + + /** + * 在API数据源下创建一个分组 + * @param groupName 分组名 + * @return 该分组的Id + * @throws Exception 操作失败则抛出此异常 + */ + public String createGroup(String groupName) throws Exception { + JSONObject body = new JSONObject(); + body.put("groupName", groupName); + HttpEntity entity = new StringEntity(body.toString(), StandardCharsets.UTF_8); + 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 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/group/list", ProjectConstants.BASE_URI), headers(), params); + JSONObject data = new JSONObject(res); + return data.getJSONArray("data"); } - public void createGroup(String groupName) throws Exception { + /** + * 列出指定分组下所有的数据源表 + * @param groupId 分组Id + * @return 分组下的所有数据源表组成的一个JSON数组 + * @throws Exception 操作失败则抛出此异常 + */ + public JSONArray listTablesOfGroup(String groupId) throws Exception { JSONObject body = new JSONObject(); - body.put("name", groupName); + body.put("groupId", groupId); 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/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 params = new HashMap<>(); + HttpKits.post(String.format("%s/api/v1/datasource/reset", ProjectConstants.BASE_URI), headers(), params); + } + private Map headers() throws Exception { Map headers = new HashMap<>(); headers.put("Authorization", auth.getToken()); diff --git a/src/main/java/com/fanruan/hihidata/datasource/server/ServerApplication.java b/src/main/java/com/fanruan/hihidata/datasource/server/ServerApplication.java index 3e60a04..02f48a8 100644 --- a/src/main/java/com/fanruan/hihidata/datasource/server/ServerApplication.java +++ b/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")); diff --git a/src/main/java/com/fanruan/hihidata/datasource/server/http/HttpKits.java b/src/main/java/com/fanruan/hihidata/datasource/server/http/HttpKits.java index b0f12b1..ec8acd3 100644 --- a/src/main/java/com/fanruan/hihidata/datasource/server/http/HttpKits.java +++ b/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); } /**