FineBI 是基於 B/S 架構的瀏覽器/伺服器模式，現在使用者開發的系統基本上趨向於 B/S 架構的瀏覽器/伺服器模式，因此有些頁面完全可以直接採用 Web 頁面嵌入式整合的簡易方式完成整合。
透過整合，使用者從自己的系統透過連結使用瀏覽器存取 FineBI 的伺服器，進而在自己系統內呼叫 FineBI 的 Web 頁面。
整合通常有兩種方式：
直接使用 URL 連結
透過 JS 呼叫 JSON 來獲得分析範本。
本章提供各部分的 URL 連結API以及 JSON 格式的 API 。
FineBI 在嵌入式整合時一般分為兩步：獲取 Token 和呼叫其他相關 API ，詳情請參見： Web頁面簡單整合例子 。
注1：由於平台安全限制，FineBI 在整合時需要將「管理系統>安全管理>安全防護」中的 Security Headers 關閉才可跨域。
注2：以下API均支援跨域，且跨域與不跨域的傳回值均一致。
作用：使用該API可以建立一個儀表板
URL：/v5/api/platform/dashboard/reports?dir=xxx
請求方式：GET
參數說明：
請求範例：localhost:37799/webroot/decision/v5/api/platform/dashboard/reports?dir={"name":"建立儀表板12","catalog":["建立文件夾"]}
傳回資料範例：
{ "success": true, "code": "200", "message": "success", "data": { "id": "72b579f34fef4982b53c723170de60cb", "name": "建立儀表板12", "folder": false, "initTime": 1593312632150, "lastUpdateTime": 1593312632150, "shared": false, "pId": "898b2dcdc6e145d38958aa304d11c362", "createBy": "b5f0c2ee-640f-4039-a4d4-918b55354898", "hangout": "NORMAL", "publicLink": { "shared": false, "uri": null, "reportId": "72b579f34fef4982b53c723170de60cb", "userId": null }, "mountedDirIds": [], "applyTime": 0 }, "errorCode": null, "detailErrorMsg": null, "errorMsg": null}
作用：透過呼叫該API，使用者可以刪除已經建立好的儀表板
URL：/v5/api/platform/dashboard/report?info=xx
請求範例：
localhost:37799/webroot/decision/v5/api/platform/dashboard/report?info={"folder":false,"reportId":"d5a78c3fc1f643059f02ff43fbdd44a9"}
成功傳回資料：
{ data:true}
失敗傳回資料：
{ errorCode:xxx 錯誤碼}
作用：透過呼叫該API，使用者可以修改已經建立好的儀表板的名稱。
URL：/v5/api/platform/dashboard/rename?info=xx
localhost:37799/webroot/decision/v5/api/platform/dashboard/rename?info= {"name":"建立儀表板","newName":"數據分析","reportId":"d5a78c3fc1f643059f02ff43fbdd44a9"}
作用：使用該API可以另存一個儀表板
URL：/v5/platform/dashboard/saveas
傳回成功資料範例：
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=155780
作用：我的（當前登入者）儀表板下對應目錄的詳細資料資訊（包括資料夾和儀表板）
URL：/v5/api/platform/dashboard/list?dir=xxx
dir={"catalog":["建立資料夾"],"reportId":"7e6382e9fe5448b38bb0bc3f50913b5d"}
注：reportId 為目錄 id ；如果是根目錄，reportId 為 urserId
注：因為 FineBI 中 URL 傳遞 JSON 對像，若有些伺服器不支援 JSON 的 URL ，就需要把 dir 值先進行編碼 encodeURIComponent() ，具體參考本文 4.1 節內容。
請求範例：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}
作用：使用該API可以獲取範本相關資訊。輸入：範本 ID 和建立者 ID ；傳回：範本資訊
URL：/v5/api/platform/dashboard/reports/info?info=xxx
請求範例：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}
1）json 格式
角色：所有有範本管理節點權限的使用者。
URL：/v5/api/dashboard/search?page=1&count=30
method：GET
{ "data": { "reportIndexList": [{ "userInfo": { "displayName": "3(3)", "postNames": ["研發"], "departmentNames": ["A"], "customRoleNames": null, "departmentPosts": [{ "jobTitle": "研發", "departments": "A" }] }, "reportIndex": { "name": "2312312", "folder": false, "initTime": 1537768891437, "lastUpdateTime": 1538032909917, "id": "5b5105c7f28547209cc50c5a23c3ebe6", "pId": "8a1462058954493ead2c7cb8e63bc7ec", "createBy": "80a56476-7ade-4b71-9c38-a365a9df591d", "hangout": "NORMAL", "publicLink": { "shared": false, "uri": null, "reportId": "5b5105c7f28547209cc50c5a23c3ebe6", "userId": null }, "mountedDirIds": [], "applyTime": 0 } }, { "userInfo": { "displayName": "1(1)", "postNames": null, "departmentNames": null, "customRoleNames": ["superusers"], "departmentPosts": null }, "reportIndex": { "name": "建立儀表板1", "folder": false, "initTime": 1537768667041, "lastUpdateTime": 1538032909810, "id": "af0835a860c1460da5d78f5a871ccc05", "pId": "53968b8b-14f4-4ec1-b9e0-347b1105af2d", "createBy": "53968b8b-14f4-4ec1-b9e0-347b1105af2d", "hangout": "NORMAL", "publicLink": { "shared": false, "uri": null, "reportId": "af0835a860c1460da5d78f5a871ccc05", "userId": null }, "mountedDirIds": [], "applyTime": 0 } }, { "userInfo": { "displayName": "1(1)", "postNames": null, "departmentNames": null, "customRoleNames": ["superusers"], "departmentPosts": null }, "reportIndex": { "name": "建立儀表板", "folder": false, "initTime": 1537768614423, "lastUpdateTime": 1538032909774, "id": "b63ae18862c0424d983865cbaa0dc7c4", "pId": "53968b8b-14f4-4ec1-b9e0-347b1105af2d", "createBy": "53968b8b-14f4-4ec1-b9e0-347b1105af2d", "hangout": "NORMAL", "publicLink": { "shared": false, "uri": null, "reportId": "b63ae18862c0424d983865cbaa0dc7c4", "userId": null }, "mountedDirIds": [], "applyTime": 0 } }], "applyingCount": 0, "totalCount": 3 }}
2）視覺化介面
URL：/dashboard/management
作用：使用該API可以獲取當前使用者的所有詳細資訊。目前包括departs、roles、users、reports。
URL：/v5/api/dashboard/user/info
{ "data": { "userInfo": { "displayName": "1(1)", "postNames": null, "departmentNames": null, "customRoleNames": ["superusers"], "departmentPosts": null }, "dashboards": [{ "name": "建立儀表板", "folder": false, "initTime": 1537768614423, "lastUpdateTime": 1538032909774, "id": "b63ae18862c0424d983865cbaa0dc7c4", "pId": "53968b8b-14f4-4ec1-b9e0-347b1105af2d", "createBy": "53968b8b-14f4-4ec1-b9e0-347b1105af2d", "hangout": "NORMAL", "publicLink": { "shared": false, "uri": null, "reportId": "b63ae18862c0424d983865cbaa0dc7c4", "userId": null }, "mountedDirIds": [], "applyTime": 0 }, { "name": "建立儀表板1", "folder": false, "initTime": 1537768667041, "lastUpdateTime": 1538032909810, "id": "af0835a860c1460da5d78f5a871ccc05", "pId": "53968b8b-14f4-4ec1-b9e0-347b1105af2d", "createBy": "53968b8b-14f4-4ec1-b9e0-347b1105af2d", "hangout": "NORMAL", "publicLink": { "shared": false, "uri": null, "reportId": "af0835a860c1460da5d78f5a871ccc05", "userId": null }, "mountedDirIds": [], "applyTime": 0 }] },}
作用：透過呼叫該API，使用者可以將某個使用者對的儀表板分享取消。
取消分享一個範本，一個使用者：
URL：/v5/api/dashboard/share/user/rejection/result?entityId=a,b,c&userId=1,2,3
取消分享多個範本，多個使用者：
API為：/v5/api/dashboard/share/user/rejection/result?entityId=&userId=
作用：使用該API可獲取分享給我（當前登入使用者）的所有範本資訊
URL：/v5/api/dashboard/share
請求範例：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}
作用：使用該API觸發全局更新，根據當前業務包的狀態選擇是全局更新/ Check 更新/配置更新
URL：/v5/api/conf/update/generate
請求範例：localhost:37799/webroot/decision/v5/api/conf/update/generate
傳回資料：
{ "success": true}
作用：根據業務包名對業務包中所有的表進行更新，或者根據錶轉義名進行單表更新。 無論是業務包還是單表的更新，都進行的是業務包表或單表的全量的更新。 在不加表的轉義名時候，進行的就是對這個業務包的更新，加了之後，進行的是對這個表的更新。
URL：/v5/api/conf/update/pack/table?info=xx
請求範例：localhost:37799/webroot/decision/v5/api/conf/update/pack/table?info={"packageName":"业务包"}
傳回資料（2020-01-15 及之前的版本）：
傳回資料（2020-08-04 版本）:
{ "msg":Package absent or has no auth!Update all too often!Success}
請求範例：localhost:37799/webroot/decision/v5/api/conf/update/pack/table?info={"packageName":"业务包","tableName":"产品销售表"}
注：fullload 參數為 false 表示增量更新，true 為全量更新，不填改參數預設為 true 。
傳回資料（2020-08-04 版本）：
{ "msg":Package absent or has no auth!Table is absent!Table is updating or waiting!Update all too often!Success}
作用：可查詢更新情況。
URL：/v5/api/conf/update/instance/任務實體id
注：該API適用於 2020-11-03 及之後的 JAR；任務實體 id 範例：「b58924f1-5141-44a8-9122-fb635b4cd599」。
2020-11-03 及之後的JAR，下表所示的更新API傳回任務實體 id ：
v5/api/conf/update/generate
{ "planId": "3845d501-b96b-46c7-b8c5-1d133dade15f", "taskName": "銀行_機構維度表單表更新", "startTime": 1602664101054, "endTime": 1602664101867, "state": 1, //更新狀態，1為已結束，2為正在運作中 "triggerType": 1, //觸發方式，1為手動，2為自動，3為內部 "resultType": 2, //運作結果，1為全部成功，2為部分成功 "roleName": "admin", "baseTableExpect": 1, "baseTableFinish": 1, "analysisTableExpect": 1, "analysisTableFinish": 0, "relationExpect": 1, "relationFinish": 0}
作用：獲取資料準備下所有業務包的分組
URL：/v5/api/conf/groups
請求範例：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}
作用：整合時，不能一個個手動輸入業務包名稱或者表的名稱來做相應的更新，需要有API來獲取到這些資訊
URL：v5/api/conf/packs/{packageId}
請求範例：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}
作用：獲取資料準備介面
URL：/v5/api/conf/page
請求範例：localhost:37799/webroot/decision/v5/api/conf/page
傳回範例：
作用：從 BI 的組件匯出或者全局匯出匯出excel時，在匯出操作之前，加入一些自訂操作，可以用這個API實現。比如匯出的檔案進行自訂加密；
接口：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(); }}
注：該API使用需要二次開發。
作用：使用該API可以登入 BI 系統。
URL：/login/cross/domain?fine_username=name&fine_password=password&validity=-1&callback=myfunction
很多使用者為了統一門戶，往往會把 FineBI 的後臺管理頁面整合到自己的系統中，本章提供 FineBI 支援的頁面整合API。
以將數據決策系統的「範本管理頁面」整合到使用者系統為例。
以管理者身分進入數據決策系統，存取連結：http://localhost:37799/webroot/decision/dashboard/management ，如下圖所示：
以管理者身分進入數據決策系統，其中每個API呼叫方法為存取：http://ip:埠/工程名/decision/API呼叫
支援單獨頁面整合的管理選單範圍如下表所示：
無全局設定
注：5.1.5 版本，2020-09-02 及之後的 JAR 支援呼叫該API
問題描述：
使用者以非管理者身分進入數據決策系統後，存取：http://IP:Port/webroot/decision/API呼叫 ，出現如下報錯：
解決方案：
需要獲得該頁面的權限，請參考 分級權限分配
業務包名稱和 ID 值儲存在 FineDB 資料庫的 fine_conf_entity 表中，欄位ID及欄位值介紹如下表所示：
查看業務包 ID 步驟如下所示：
1）新增 FineDB 資料連結，具體可參考：FineDB 資料庫簡介 的 2.4 節內容。
2）建立伺服器資料集，SQL語句為：SELECT *FROM fine_conf_entity where ID like 'DirectPackageConfStore.mapHolder%' and ID like '%name'
如下圖所示：
3）預覽建立的 SQL 資料集，可查看業務包 ID 。如下圖所示：
因為 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
在進行系統整合時，如果後臺有錯誤，會傳回錯誤碼（errorCode），具體異常碼定義可以參考 系統錯誤碼說明
問題描述
FineBI 透過 iframe 頁面嵌入到其他頁面中報錯：xxx拒絕了我們的連結請求，如下圖所示：
解決方案
管理者進入平台，點選「管理系統>安全管理」，關閉點選挾持攻擊防護按鈕。如下圖所示：