目录:
1. 概述编辑
1.1 版本
| FineBI 版本 | JAR 包 | 新增功能 |
|---|---|---|
| 5.1 | - | - |
| 2020-08-04 | 单表更新和业务包更新支持设置全量&增量更新 |
1.2 应用场景
FineBI 是基于 B/S 架构的浏览器/服务器模式，现在用户开发的系统基本上趋向于 B/S 架构的浏览器/服务器模式，因此有些页面完全可以直接采用 Web 页面嵌入式集成的简易方式完成集成。
通过集成，用户从自己的系统通过链接使用浏览器访问 FineBI 的服务器，从而在自己系统内调用 FineBI 的 Web 页面。
1.3 功能介绍
集成通常有两种方式：
直接使用 URL 链接
通过 JS 调用 JSON 来获得分析模板。
本章提供各部分的 URL 链接接口以及 JSON 格式的 API 。
FineBI 在嵌入式集成时一般分为两步：获取 Token 和调用其他相关 API ，详情请参见： Web页面简单集成例子 。
注1：由于平台安全限制，FineBI在集成时需要将管理系统>安全管理>安全防护中的 Security Headers 关闭才可跨域。
注2：以下接口均支持跨域，且跨域与不跨域的返回值均一致。
2. 创建仪表板 API编辑
作用：使用该接口可以新建一个仪表板
URL：/v5/api/platform/dashboard/reports?dir=xxx
请求方式：GET
参数说明：
| 参数 | 说明 | 示例 |
|---|---|---|
| dir | 创建到的目录结构 | dir={"name":"新建仪表板12","catalog":["新建文件夹"]} |
请求示例:localhost:37799/webroot/decision/v5/api/platform/dashboard/reports?dir={"name":"新建仪表板12","catalog":["新建文件夹"]}
返回数据示例：
13. 当前目录下仪表板及文件夹列表（JSON）编辑
作用：我的（当前登录者）仪表板下对应目录的详细数据信息（包括文件夹和仪表板）
URL：/v5/api/platform/dashboard/list?dir=xxx
请求方式：GET
参数说明：
| 参数 | 说明 | 示例 |
|---|---|---|
| dir | 创建到的目录结构 | dir={"catalog":["新建文件夹"],"reportId":"7e6382e9fe5448b38bb0bc3f50913b5d"} |
请求示例：localhost:37799/webroot/decision/v5/api/platform/dashboard/list?dir={"catalog":["新建文件夹"],"reportId":"7e6382e9fe5448b38bb0bc3f50913b5d"}
返回数据示例：
{ "code": "200", "data": [ { "applyTime": 0, "createBy": "b5f0c2ee-640f-4039-a4d4-918b55354898", "folder": false, "hangout": "NORMAL", "id": "0ba9d9496aee4bba95fcf60d78473115", "initTime": 1539157863240, "lastUpdateTime": 1539157863241, "mountedDirIds": [], "name": "新建仪表板12", "pId": "d5a78c3fc1f643059f02ff43fbdd44a9", "publicLink": { "reportId": "0ba9d9496aee4bba95fcf60d78473115", "shared": false, "uri": null, "userId": null } }, { "applyTime": 0, "createBy": "b5f0c2ee-640f-4039-a4d4-918b55354898", "folder": false, "hangout": "NORMAL", "id": "7e6382e9fe5448b38bb0bc3f50913b5d", "initTime": 1539157797060, "lastUpdateTime": 1539157797061, "mountedDirIds": [], "name": "新建仪表板", "pId": "d5a78c3fc1f643059f02ff43fbdd44a9", "publicLink": { "reportId": "7e6382e9fe5448b38bb0bc3f50913b5d", "shared": false, "uri": null, "userId": null } } ], "detailErrorMsg": null, "errorCode": null, "errorMsg": null, "message": "success", "success": true}4. 获取仪表板相关信息 API编辑
作用：使用该接口可以获取模板相关信息。输入：模板 ID 和创建者 ID ；返回：模板信息
URL：/v5/api/platform/dashboard/reports/info?info=xxx
请求方式：GET
参数说明：
| 参数 | 说明 | 示例 |
|---|---|---|
| info | 需要查看的仪表板目录 | info={"index":[ { "id":"7e6382e9fe5448b38bb0bc3f50913b5d" }] } |
请求示例：localhost:37799/webroot/decision/v5/api/platform/dashboard/reports/info?info={"index":[ { "id":"7e6382e9fe5448b38bb0bc3f50913b5d" }] }
返回数据示例：
{ "code": "200", "data": { "index": [ { "createBy": "1", "folder": false, "id": null, "initTime": 1539157797060, "lastUpdateTime": 1539157797061, "name": "新建仪表板", "pId": "d5a78c3fc1f643059f02ff43fbdd44a9" } ] }, "detailErrorMsg": null, "errorCode": null, "errorMsg": null, "message": "success", "success": true}5. 分享给我的仪表板信息 API编辑
作用：使用该接口可获取分享给我（当前登录用户）的所有模板信息
URL：/v5/api/dashboard/share
请求方式：GET
请求示例：localhost:37799/webroot/decision/v5/api/dashboard/share
返回数据示例：
{ "code": "200", "data": [ { "folder": true, "createBy": "b5f0c2ee-640f-4039-a4d4-918b55354898", "description": null, "id": "e5bc1ae63f944050b43d031c21d01847", "reportId": "e5bc1ae63f944050b43d031c21d01847", "originType": "isShared", "pId": "-2", "text": "用指标解析银行数据" } ], "detailErrorMsg": null, "errorCode": null, "errorMsg": null, "message": "success", "success": true}6. 触发全局更新 API编辑
作用：使用该接口触发全局更新，根据当前业务包的状态选择是全局更新/ Check 更新/配置更新
URL：/v5/api/conf/update/generate
请求示例：localhost:37799/webroot/decision/v5/api/conf/update/generate
请求方式：GET
返回数据：
{ "success": true}7. 触发单表/业务包更新 API编辑
作用：根据业务包名对业务包中所有的表进行更新，或者根据表转义名进行单表更新。 无论是业务包还是单表的更新，都进行的是业务包表或单表的全量的更新。 在不加表的转义名时候，进行的就是对这个业务包的更新，加了之后，进行的是对这个表的更新。
7.1 业务包更新
URL：/v5/api/conf/update/pack/table?info=xx
请求方式：GET
请求示例：localhost:37799/webroot/decision/v5/api/conf/update/pack/table?info={"packageName":"业务包"}
参数说明：
| 参数 | 版本 | 说明 | 示例 |
|---|---|---|---|
| info | 2020-01-15 及之前的版本 | 需要更新的业务包信息 | {"packageName":"业务包"} |
| 2020-08-04 版本 |
返回数据（2020-01-15 及之前的版本）：
{ "success": true}返回数据（2020-08-04 版本）:
{ "msg":Package absent or has no auth!Update all too often!Success}7.2 单表更新
URL：/v5/api/conf/update/pack/table?info=xx
请求方式：GET
请求示例：localhost:37799/webroot/decision/v5/api/conf/update/pack/table?info={"packageName":"业务包","tableName":"产品销售表"}
参数说明：
| 参数 | 版本 | 说明 | 示例 |
|---|---|---|---|
| info | 2020-01-15 及之前的版本 | 需要更新的表信息 | {"packageName":"业务包","tableName":"表转义名"} |
| 2020-08-04 版本 | {"packageName":"业务包","tableName":"转义名","fullLoad":"false"} |
注：fullload 参数为 false 表示增量更新，true 为全量更新，不填改参数默认为 true 。
返回数据（2020-01-15 及之前的版本）：
{ "success": true}返回数据（2020-08-04 版本）：
{ "msg":Package absent or has no auth!Table is absent!Table is updating or waiting!Update all too often!Success}8. 获取所有业务包分组信息编辑
作用：获取数据准备下所有业务包的分组
URL：/v5/api/conf/groups
请求方式：GET
请求示例：localhost:37799/webroot/decision/v5/api/conf/groups
返回数据示例：
{ "code": "200", "data": [ { "editable": true, "id": "__no_group__", "initTime": 1531100612398, "myAnalysisTables": [], "name": "__no_group__", "packs": [ { "createBy": "1", "editable": true, "id": "a5e4bcbd09fd4de497d91839a0da82d6", "name": "业务包", "tableCount": 2, "timeStamp": 1536819164195, "type": 2, "usedSpace": 0.0 } ] }, { "editable": true, "id": "de20c13fdcdd436987289588b232c38c", "initTime": 1531138781428, "myAnalysisTables": [], "name": "功能数据", "packs": [ { "createBy": "1", "editable": true, "id": "18d26ef06d1f4e91adaa12c80feb2daa", "name": "销售DEMO", "tableCount": 9, "timeStamp": 1531101074181, "type": 2, "usedSpace": 4.123135566711426 }, ] }, ], "detailErrorMsg": null, "errorCode": null, "errorMsg": null, "message": "success", "success": true}9. 获取所有业务包信息 API编辑
作用：集成时，不能一个个手动输入业务包名字或者表的名字来做相应的更新，需要有接口来获取到这些信息
URL：v5/api/conf/packs/{packageId}
请求方式：GET
请求示例：localhost:37799/webroot/decision/v5/api/conf/packs/{packageId}
返回数据示例：
{ "code": "200", "data": { "editable": true, "errorTable": [], "missTable": [], "name": "销售DEMO", "tables": [ { "connectionName": "BI Demo", "createBy": "1", "editable": true, "fields": [ { "enable": true, "engineType": "Direct", "fieldGroupType": 0, "id": "DEMO[5f]PRODUCT_[4ea7][54c1]ID", "name": "产品ID", "primaryKey": false, "size": 32, "transferName": "产品ID", "type": 32, "usable": true }, { "enable": true, "engineType": "Direct", "fieldGroupType": 0, "id": "DEMO[5f]PRODUCT_[4ea7][54c1][540d][79f0]", "name": "产品名称", "primaryKey": false, "size": 32, "transferName": "产品名称", "type": 16, "usable": true } ], "initTime": 1539161534282, "memorize": true, "name": "DEMO_PRODUCT", "operators": null, "pack": "18d26ef06d1f4e91adaa12c80feb2daa", "realTimeData": false, "selected": 0, "tableName": "DEMO_PRODUCT", "transferName": "产品名称维度", "type": 1, "usedSpace": 0.0007028579711914062 }, ] }, "detailErrorMsg": null, "errorCode": null, "errorMsg": null, "message": "success", "success": true}10. 数据准备界面 API编辑
作用：获取数据准备界面
URL：/v5/api/conf/page
请求方式：GET
请求示例：localhost:37799/webroot/decision/v5/api/conf/page
返回示例：
11. 删除仪表板编辑
作用：通过调用该接口，用户可以删除已经创建好的仪表板
URL：/v5/api/platform/dashboard/report?info=xx
参数说明：
| 参数 | 说明 | 实例 |
|---|---|---|
| info | 需要删除的仪表板 | {"folder":是否是文件夹,"reportId":"模板id"} |
请求方式：GET
请求示例：localhost:37799/webroot/decision/v5/api/platform/dashboard/report?info={"folder":false,"reportId":"d5a78c3fc1f643059f02ff43fbdd44a9"}
成功返回数据：
{ data:true}失败返回数据：
{ errorCode:xxx 错误码}12. 修该仪表板名称编辑
作用：通过调用该接口，用户可以修改已经创建好的仪表板的名称。
URL：/v5/api/platform/dashboard/rename?info=xx
请求方式：GET
参数说明：
| 参数 | 说明 | 实例 |
|---|---|---|
| info | 需要重命名的仪表板 | {"name":"模板名字","newName":"重命名的名字","reportId":"模板id"} |
请求示例：localhost:37799/webroot/decision/v5/api/platform/dashboard/rename?info= {"name":"新建仪表板","newName":"数据分析","reportId":"d5a78c3fc1f643059f02ff43fbdd44a9"}
成功返回数据：
{ data:true}失败返回数据：
{ errorCode:xxx 错误码}13. 导出之前自定义加工编辑
作用：从 BI 的组件导出或者全局导出导出excel时，在导出操作之前，加入一些自定义操作，可以用这个接口实现。比如导出的文件进行自定义加密；
接口：ExportHandleProvider
package com.finebi.stable.fun; import com.fr.stable.fun.mark.Mutable; import java.io.OutputStream; /** * Created by Hiram on 2018/11/14. */public interface ExportHandleProvider extends Mutable { String XML_TAG = "ExportHandleProvider"; int CURRENT_LEVEL = 1; /** * * @param originalOutputStream 原始导出流 * @param type 导出类型 * @return 处理后的流 */ OutputStream handleStream(OutputStream originalOutputStream, ExportType type);}示例源码：
下面的示例源码简单的统计一下导出文件的大小，输出在日志里面。写一个拦截处理的CountExportHandle，返回一个CountOutputStream，在write时计数，最后在close的时候输出大小。
CountExportHandle：
import com.finebi.stable.fun.ExportType;import com.finebi.stable.fun.impl.AbstractExportHandleProvider;import java.io.OutputStream;public class CountExportHandle extends AbstractExportHandleProvider { @Override public OutputStream handleStream(OutputStream originalOutputStream, ExportType type) { return new CountOutputStream(originalOutputStream); } }CountOutputStream：
import com.fr.log.FineLoggerFactory;import java.io.IOException;import java.io.OutputStream; public class CountOutputStream extends OutputStream { private OutputStream out; private int count; public CountOutputStream(OutputStream out) { this.out = out; } @Override public void write(int b) throws IOException { count++; out.write(b); } @Override public void write(byte[] b) throws IOException { count += b.length; out.write(b); } @Override public void write(byte[] b, int off, int len) throws IOException { count += len; out.write(b, off, len); } @Override public void flush() throws IOException { out.flush(); } @Override public void close() throws IOException { FineLoggerFactory.getLogger().info("===== export length: {} ======", count); out.close(); }}注：该接口使用需要二次开发。
14. 另存仪表板编辑
作用：使用该接口可以另存一个仪表板
URL：/v5/platform/dashboard/saveas
请求方式：GET
参数说明：
| 参数 | 说明 | 示例 |
|---|---|---|
| from | 需要另存的仪表板 | "from":[{"reportId":"3ef0fe316b604c75bc4ec0ab644ce0f9"}] |
| to | 另存到的路径 | "to":{"name":"新建仪表板61","catalog":[]} |
返回成功数据示例：
code: "200"data: {id: "d07aeebaa6244d7c984cac0cd1f7c32a", name: "新建仪表板61", folder: false, initTime: 1557801373662,…}applyTime: 0createBy: "b5f0c2ee-640f-4039-a4d4-918b55354898"folder: falsehangout: "NORMAL"id: "d07aeebaa6244d7c984cac0cd1f7c32a"initTime: 1557801373662lastUpdateTime: 1557801371510mountedDirIds: []name: "新建仪表板61"pId: "b5f0c2ee-640f-4039-a4d4-918b55354898"publicLink: {shared: false, uri: null, reportId: "d07aeebaa6244d7c984cac0cd1f7c32a", userId: null}shared: falsedetailErrorMsg: nullerrorCode: nullerrorMsg: nullmessage: "success"success: true注：返回的 data.id 是模板 id，根据模板 id 获取模板信息。
返回失败数据示例：（根据errorCode判断是否模板名是否重复）
code: "200",message: "success",data: [ ],success: false,errorCode: "61310032",detailErrorMsg: null,errorMsg: "ReportIndex{name='20190117111140448_10813', folder=false, initTime=1557802945315, lastUpdateTime=15578015. 取消分享编辑
作用：通过调用该接口，用户可以将某个用户对的仪表板分享取消。
URL：/v5/api/dashboard/share/user/rejection/result?entityId=a,b,c&userId=1,2,3
16. 注意事项编辑
16.1 服务器不支持 JSON 下的 URL
因为 FineBI 中 URL 传递 JSON 对像，若有些服务器不支持 JSON 的 URL ，就需要把 JSON 类型的 URL 参数值先进行编码encodeURIComponent()。
例如：
dir={"name":"新建仪表板12","catalog":[]} 需要改为：encodeURIComponent(JSON.stringify({"name":"新建仪表板12","catalog":[]}))编码显示为：
dir=%7B%22name%22%3A%22%E6%96%B0%E5%BB%BA%E4%BB%AA%E8%A1%A8%E6%9D%BF12%22%2C%22catalog%22%3A%5B%5D%7D
16.2 返回错误码
在进行系统集成时，如果后台有错误，会返回错误码（errorCode），具体异常码定义可以参考 系统错误码说明 。