api-datasource-demo/README.md

# API数据源使用示例

**支持版本：** 仅企业版支持API数据源。

**更新间隔：** 数据源表的数据更新的时候，会根据实际情况启动使用该数据源表的分析表的更新，最小更新间隔为1个小时。*举例：当10点更新了一张数据源表，当表数据写入完成后，会立即更新到九数云中，如果10点10分再次更新这张表，则需要在11点的时候，才会将最新的数据更新到九数云中，13点15的时候再次更新这张表的数据，由于在这之前的1个小时没有任何的更新，因此在数据写入完成后，会立即更新到九数云中。*

## accessKeyId和accessKeySecret的获取
参考帮助文档：[获取accessKeyId和accessKeySecret](https://help.fanruan.com/jiushuyun/doc-view-140.html)

## 数据流转流程图

![api_data_flow](/screenshots/api_data_flow.png)

## 调用示例代码

```Authentication```表示的是传入accessKeyId和accessKeySecret参数，获取临时令牌的操作，可以自行调用其中的RestApi，不是必须使用该类。

```DatasourceOperation```表示的是可以对API数据源进行的若干操作的集合，可以自行调用其中的RestApi，不是必须使用该类。

### 开启API数据源

```java
Authentication authentication = new Authentication("#key", "#secret");
DatasourceOperation operation = new DatasourceOperation(authentication);
operation.open();
```

在开启后，可以在企业数据的"数据导入"菜单看到如下图所示的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（可选）");
```

### 更新表数据

数据的格式采用csv文件存储，格式如下：

假设文件名为data.csv，其内容为（其中第一行是表头，第一行之后是表数据）

表头行字段中可以将字段类型（目前支持字符串文本string、日期或时间date、数字类型number（不区分大小写））写在字段后，用#分隔，不带类型则默认为文本

主键字段在末尾添加#key（不区分大小写），可与字段类型连用。（主键唯一，多主键可以自行拼接成一个新的主键。）

```
"合同签约时间(Year Month Day)#date","城市","国家","客户名称#string#key","省份","回款金额","合同金额"
"18/1/2016","杭州市","中国","浙江臻善科技有限公司","浙江省","1200000","1200000"
"1/8/2016","郑州市","中国","杭州明佑电子有限公司","河南省","100800","100800"
"1/4/2016","西安市","中国","西北工业大学","陕西省","430000","430000"
```

**特别注意1：csv文件需要使用utf-8编码，其他编码均无法正确解析**

**特别注意2：为了避免数据中的逗号和csv的分隔符冲突，我们要求所有的数据均要使用双引号包含起来**

**踩坑记录：**

**1、数据中可能含有换行符的，转换数据时需要全局处理类似符号，否则可能导致格式错误**

**2、数据中可能含有英文引号的，注意不要和数据的引号冲突**

**注意：** 当前默认为全量覆盖表数据，如需切换到增量更新，参考接口/api/v1/datasource/table/modify。

```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文档
## 注：接口无特殊说明默认采用body传参

### 开启API数据源
#### 查看状态	
请求地址：```/api/v1/datasource/status```	

请求类型：POST

返回值： 
```json 
{
"success":true,
"code":"200",
"data":{"status":"0"}
}
```

#### 修改状态	
请求地址：```/api/v1/datasource/status/modify```

请求类型：POST	

请求参数： ``` {"status":"1"} ```

返回值：
```json
{
"success":true,
"code":"200"
}
```

### 分组管理
#### 创建分组
请求地址：```/api/v1/datasource/group/create```

请求类型：POST	

请求参数：```{"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/group/delete```

请求类型：POST

请求参数： ``` {"groupId":"#分组Id"} ```

返回值：
```json
{
  "success": true,
  "code": "200"
}
```

### 表管理
#### 创建数据源表	
请求地址：```/api/v1/datasource/table/create```

请求类型：POST

请求参数： ``` {"tableName":"#表名","groupId":"#分组Id（可选）","updateMode":1（可选1,2,3或不上传默认为1）} ```

说明：

updateMode: 更新方式

1:全量更新:用全新的数据替换旧的全部数据（数据可以做到新增、修改、删除，但是耗费资源较多，表数据量大时可能会比较慢，表数据量小时推荐使用，每次替换大规模数据时推荐使用）；

2:增量更新:新增新数据，旧数据不受影响（数据无法更新、删除，只能新增，记录历史数据无需修改和删除时推荐使用，效率最高）；

3:替换更新:（必须声明主键）按主键替换相同主键的数据，之前没有的数据直接新增。（主键处理见csv文件说明）（数据只能替换、新增，不能删除，每次更新会修改少量数据时推荐使用）

返回值：
```json
{
  "success": true,
  "code": "200",
  "data":"#tableId"
}
```

#### 获取表数据上传地址	
请求地址：```/api/v1/datasource/table/upload/url```

请求类型：POST

请求参数：``` {"tableId":"#表Id"} ```

返回值：
```json
{
  "success": true,
  "code": "200",
  "data":"#file_upload_url"
}
```
**注意：获取数据上传地址后，使用put请求调用，csv文件使用二进制上传**

#### 标记表数据已上传完成	

## 注意：创建表的动作是异步处理的，因此有可能存在调用标记数据上传完成接口时表未创建完成的情况，推荐在调用前等待3秒

请求地址：```/api/v1/datasource/table/upload/finish```

请求类型：POST	

请求参数：``` {"tableId":"#表Id"} ```

返回值：
```json
{
  "success": true,
  "code": "200"
}
```

#### 修改数据源表名、更新方式
请求地址：```/api/v1/datasource/table/modify```

请求类型：POST

请求参数： ``` {"tableId":"#表Id","tableName":"#新的表名","updateMode": 1（可选1,2,3或不上传默认为1，参考创建表）} ```

返回值：
```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"
}
```


#### 导出分析表数据
请求地址：```/api/v1/export```

请求类型：POST

请求参数： ``` {"tableId":"#表Id", "format": "excel"(说明：可不传，不传时默认为"csv"，导出csv文件，传"excel"则导出excel文件)} ```

返回值：
```json
{
  "code":"200",
  "data":"https://...（导出的文件下载地址）",
  "success":true
}
```

注：

1、导出只可以导出分析表（数据源表、仪表板、故事板不支持）；

2、导出不消耗导出次数；

3、此接口导出excel的功能，于2024.1.19.起正式使用；


#### 批量导出分析表数据
请求地址：```/api/v1/export/batch```

请求类型：POST

请求参数： ``` {"tableIds":["#表a Id", "#表b Id", ...], "format": "excel"(说明：可不传，不传时默认为"csv"，导出csv文件，传"excel"则导出excel文件)} ```

返回值：
```json
{
  "code":"200",
  "data":["https://...（表a下载地址）", "https://...（表b下载地址）", ...],
  "success":true
}
```
注： 同/export接口注意事项

#### 获取店铺信息
请求地址：```/api/v1/store/info```

请求类型：POST

请求参数： 无

返回值：
```json
{
    "success": true,
    "code": "200",
    "message": "success",
    "data": [
        {
            "id": "31ea502409f249cf95a361c17088a3ee",
            "name": "店铺",
            "type": 28
        }
    ]
}
```

#### 申请删除数据源数据（防止误删除，您必须先获取令牌，然后使用令牌删除您的数据）
请求地址：```/api/v1/store/data/delete/apply```

请求类型：POST

请求参数： 无

返回值：
```json
{
    "success": true,
    "code": "200",
    "message": "success",
    "data": "7d08cb01"
}
```

#### 删除数据源数据
请求地址：```/api/v1/store/data/delete```

请求类型：POST

请求参数： 
```
{
    "token": "7d08cb01",
    "storeId": "31ea502409f249cf95a361c17088a3ee"
}
```

返回值：
```json
{
    "success": true,
    "code": "200",
    "message": "success",
    "data": true
}
```


#### 获取store下所有的表
请求地址：```/api/v1/store/tables```

请求类型：POST

请求参数： 
```
{
    "storeId": "5fb0ad5df26b4598b073e979ddf4fb1a"(/store/info接口返回的id)
}
```

返回值：
```json
{
  "success": true,
  "code": "200",
  "message": "success",
  "data": [
    {
      "id": "239a9528b09942ee822ffaa41585dc356194dde1",
      "name": "合同事实表"
    },
    {
      "id": "239a9528b09942ee822ffaa41585dc356b6cce97",
      "name": "111"
    }
  ]
}
```

#### 数据源表单表同步
请求地址：```/api/v1/sync/table```

请求类型：POST

请求参数： 
```
{
    "tableId": "239a9528b09942ee822ffaa41585dc356194dde1"(/store/tables返回的表id),
    "type": 28(/store/info返回的type)
}
```

返回值：
```json
{
  "success": true,
  "code": "200",
  "message": "success",
  "data": true,
}

```

注：

1、目前只支持对钉钉、简道云、数据库以及云数据库的数据源表进行更新；

2、使用接口同步表时拥有企业下所有数据源表权限（不可获取数据仅可触发同步），请注意权限分配；

3、使用接口同步表仍需消耗同步次数，请注意用法用量；


#### 数据源表批量同步
请求地址：```/api/v1/sync/table```

请求类型：POST

请求参数： 
```
{
    "tables": [
        {
            "tableId": "69a5aab540a14dfea3138d67e377ffaf_64efefb47c70eb00063a3891_6368cf27de256c000a6cc773"(/store/tables返回的表id),
            "storeId": "69a5aab540a14dfea3138d67e377ffaf"(/store/info接口返回的id)
        },
        {
            "tableId": "69a5aab540a14dfea3138d67e377ffaf_64efefb47c70eb00063a3891_636b2c51c27bf3000a2eb438",
            "storeId": "69a5aab540a14dfea3138d67e377ffaf"
        }
    ],
    "type": 28(/store/info返回的type)
}
```

返回值：
```json
{
  "success": true,
  "code": "200",
  "message": "success",
  "data": {
    "failedNum": 0,
    "successNum": 2,
    "failedIds": [],
    "notAddProjectNum": 0
  },
}

```

注：

1、批量同步时，所有要同步的表必须是同一种数据源表；

2、返回值中failedNum和successNum分别为同步失败的表的个数和成功个数，失败的表id会显示在failedIds中，请注意保留日志等用于排查更新失败问题；

3、未添加到项目中的表目前无需同步，不会消耗次数，具体表数量请关注notAddProjectNum字段；