API表接口 - FineBI Cloud

API表接口

1. 概述

通过上传数据表接口，可以将 CSV 文件上传至 FineBI Cloud 的 API 数据源，并管理分组、数据源表及数据更新方式。

1.1 登录认证

本文所有接口均需要临时令牌。请先使用 accessKeyId 和 accessKeySecret 获取临时令牌，详情请参见：登录认证。访问接口时，在请求头中设置 Authorization，值为获取到的临时令牌。

1.2 CSV 文件说明

项目	说明
文件结构	第 1 行为表头，后续行为表数据
字段类型	在表头字段名后用 # 添加类型，支持文本 string、日期或时间 date、数字 number，不区分大小写；不声明时默认为文本
主键	在表头末尾添加 #key，不区分大小写，可与类型连用；主键值需唯一。需要联合主键时，可先将多个字段拼接为一个新的主键字段
文件编码	使用 UTF-8，其他编码无法正确解析
分隔符	所有表头和数据值均使用英文双引号包裹，避免数据中的逗号与 CSV 分隔符冲突
换行与引号	转换数据时统一处理数据中的换行符，并避免数据内的英文引号与包裹数据的双引号冲突
默认更新方式	全量覆盖表数据；需要改为增量更新或替换更新时，调用第 4.4 节接口

以 data.csv 为例：

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

2. 开启API数据源

接口信息	说明
接口作用	开启 API 数据源
接口路径	/api/v1/datasource/status/modify
请求方式	POST
请求参数	{ "status":"1" }

响应实例：

请求示例	https://bi.finecloud.com/decision/api/v1/datasource/status/modify
请求Body	{ "status":"1" }
响应成功	{ "success": true, "code": "200", "message": "success", "data": {}, "errorCode": null, "detailErrorMsg": null, "errorMsg": null }
截图示例

开启后，可在「数据连接市场」看到 API 数据源入口。

3. 分组管理

以下示例中的分组名、分组 ID 和表 ID，请替换为自己环境的实际值。

3.1 创建分组

接口信息	说明
接口作用	创建分组
接口路径	/api/v1/datasource/group/create
请求方式	POST
请求参数	{ "groupName":"${your_group_name}" } 其中${your_group_name}为分组名

响应实例：

请求示例	https://bi.finecloud.com/decision/api/v1/datasource/group/create
响应成功	{ "success": true, "code": "200", "message": "success", "data": "agqufuteyn23nmotycas6qkec4", "errorCode": null, "detailErrorMsg": null, "errorMsg": null }
截图示例

成功响应中，data 为分组 ID。

创建成功后，可在「数据连接>API」中看到该分组。

3.2 读取所有分组

接口信息	说明
接口作用	读取所有分组
接口路径	/api/v1/datasource/group/list
请求方式	POST

响应实例：

请求示例	https://bi.finecloud.com/decision/api/v1/datasource/group/list
响应成功	{ "success": true, "code": "200", "message": "success", "data": [ { "id": "agqufuteyn23nmotycas6qkec4", "name": "API数据表" }, { "id": "agqugsfij57zjagibs5ebrugaa", "name": "API测试" } ], "errorCode": null, "detailErrorMsg": null, "errorMsg": null }
截图示例

3.3 读取分组下的所有表

接口信息	说明
接口作用	读取指定分组下的所有表
接口路径	/api/v1/datasource/group/table/list
请求方式	POST
请求参数	{ "groupId": "${your_group_id}" } ${your_group_id}为目标分组ID，可通过 3.2 节获取

响应实例：

请求示例	https://bi.finecloud.com/decision/api/v1/datasource/group/table/list
请求Body	{ "groupId": "agqufuteyn23nmotycas6qkec4" }
响应成功	{ "success": true, "code": "200", "message": "success", "data": [ { "id": "agqugyxnhz6ihgwnfa4xawdihi", "name": "门店销售数据表" } ], "errorCode": null, "detailErrorMsg": null, "errorMsg": null }
截图示例

3.4 重命名分组

接口信息	说明
接口作用	修改分组名
接口路径	/api/v1/datasource/group/modify
请求方式	POST
请求参数	{ "groupId":"${your_group_id}", "groupName":"${your_group_newname}" } ${your_group_id} 为待重命名分组的 ID，可通过 3.2 节获取 ${your_group_newname}为新的分组名

响应实例：

请求示例	https://bi.finecloud.com/decision/api/v1/datasource/group/modify
请求Body	{ "groupId":"agqugsfij57zjagibs5ebrugaa", "groupName":"API测试环境" }
响应成功	{ "success": true, "code": "200", "message": "success", "data": {}, "errorCode": null, "detailErrorMsg": null, "errorMsg": null }
截图示例

修改成功后，可在「数据连接>API」中看到该分组命名变化。

3.5 删除分组

分组下存在表时无法删除。

接口信息	说明
接口作用	删除分组
接口路径	/api/v1/datasource/group/delete
请求方式	POST
请求参数	{ "groupId":"${your_group_id}" } ${your_group_id}为待删除分组的 ID，可通过 3.2 节获取

响应实例：

请求示例	https://bi.finecloud.com/decision/api/v1/datasource/group/delete
请求Body	{ "groupId":"agqugsfij57zjagibs5ebrugaa" }
响应成功	{ "success": true, "code": "200", "message": "success", "data": {}, "errorCode": null, "detailErrorMsg": null, "errorMsg": null }
截图示例

删除成功后，可在「数据连接>API」中看到该分组消失。

4. 表管理

4.1 创建数据源表

接口信息	说明
接口作用	创建数据源表
接口路径	/api/v1/datasource/table/create
请求方式	POST
请求参数	{ "tableName": "${your_table_name}", "groupId": "${your_group_id}", "updateMode": 1 } ${your_table_name}：待创建的表名称 ${your_group_id}：表存储的分组ID，可通过 3.2 节获取 updateMode：表更新方式，可选 1、2、3，不传时默认为 1

三种更新方式的区别如下。

值	更新方式	数据处理规则	适用场景
1	全量更新	用新数据替换全部旧数据，可实现新增、修改和删除；资源消耗较多	表数据量较小，或每次需要替换整表数据
2	增量更新	只新增数据，不修改或删除旧数据	追加历史记录，无需修改或删除
3	替换更新	必须声明主键；相同主键的数据被替换，新主键的数据被新增，不删除旧记录	每次只修改少量记录

注意：使用全量更新时，旧数据会被本次上传的数据整体替换。上传前确认文件包含需要保留的全部数据。

响应实例：

请求示例	https://bi.finecloud.com/decision/api/v1/datasource/table/create
请求Body	{ "tableName": "门店销售数据表", "groupId": "agqufuteyn23nmotycas6qkec4", "updateMode": 1 }
响应成功	{ "success": true, "code": "200", "message": "success", "data": "agqugyxnhz6ihgwnfa4xawdihi", "errorCode": null, "detailErrorMsg": null, "errorMsg": null }
截图示例

成功响应中，data 为表 ID。

创建成功后，可在「数据连接>API」中看到该表。

4.2 获取表数据上传地址

接口信息	说明
接口作用	获取表数据上传地址获取上传地址后，使用 PUT 请求，将 CSV 文件以二进制方式上传至该地址。本接口提供的上传地址、下载地址等链接有效期均为 24 小时。
接口路径	/api/v1/datasource/table/upload/url
请求方式	POST
请求参数	{ "tableId":"${your_table_id}" } ${your_table_id}为目标表ID，可通过 3.3 节获取

响应实例：

请求示例	https://bi.finecloud.com/decision/api/v1/datasource/table/upload/url
请求Body	{ "tableId":"agqugyxnhz6ihgwnfa4xawdihi" }
响应成功	{ "success": true, "code": "200", "message": "success", "data": "https://xxxxxxxxxxxxxxxxxx", "errorCode": null, "detailErrorMsg": null, "errorMsg": null }
截图示例

成功响应中，data 为上传地址。

4.3 标记表数据已上传完成

接口信息	说明
接口作用	标记表数据已上传完成
接口路径	/api/v1/datasource/table/upload/finish
请求方式	POST
请求参数	{ "tableId":"${your_table_id}" } ${your_table_id}为目标表ID，可通过 3.3 节获取

注意：创建表为异步处理，调用本接口时表可能尚未创建完成。建议调用前等待 3 秒。

响应实例：

请求示例	https://bi.finecloud.com/decision/api/v1/datasource/table/upload/finish
请求Body	{ "tableId":"agqugyxnhz6ihgwnfa4xawdihi" }
响应成功	{ "success": true, "code": "200", "message": "success", "data": "agqugyxnhz6ihgwnfa4xawdihi", "errorCode": null, "detailErrorMsg": null, "errorMsg": null }
截图示例

4.4 修改数据源表名、更新方式

接口信息	说明
接口作用	修改数据源表名、更新方式
接口路径	/api/v1/datasource/table/modify
请求方式	POST
请求参数	{ "tableId": "${your_table_id}", "tableName": "${your_table_name}", "updateMode": 1 } ${your_table_id}：目标表ID，可通过 3.3 节获取 ${your_table_name}：新的表名 updateMode：表更新方式，可选 1、2、3，不传时默认为 1。具体说明见第 4.1 节。

响应实例：

请求示例	https://bi.finecloud.com/decision/api/v1/datasource/table/modify
请求Body	{ "tableId": "agqugyxnhz6ihgwnfa4xawdihi", "tableName": "门店销售数据统计", "updateMode": 1 }
响应成功	{ "success": true, "code": "200", "message": "success", "data": {}, "errorCode": null, "detailErrorMsg": null, "errorMsg": null }
截图示例

4.5 删除数据源表

接口信息	说明
接口作用	删除数据源表
接口路径	/api/v1/datasource/table/delete
请求方式	POST
请求参数	{ "tableId":"${your_table_id}" } ${your_table_id}为目标表ID，可通过 3.3 节获取

响应实例：

请求示例	https://bi.finecloud.com/decision/api/v1/datasource/table/delete
请求Body	{ "tableId":"agqugyxnhz6ihgwnfa4xawdihi" }
响应成功	{ "success": true, "code": "200", "message": "success", "data": {}, "errorCode": null, "detailErrorMsg": null, "errorMsg": null }
截图示例

4.6 重置整个数据源

接口信息	说明
接口作用	重置整个数据源
接口路径	/api/v1/datasource/reset
请求方式	POST