​Web頁面整合常見問題

1.1 版本

1.2 功能簡介

FineBI支援透過 GET 和 POST 兩種方式呼叫API資料，進行Web整合。

本文為你介紹 API API相關入門知識，便於後續使用FineBI進行Web整合。

APIAPI文檔一般分為API描述、API地址、請求方法、請求參數、回应內容、錯誤程式碼、實體幾個部分：

3.1 GET請求

GET通常用於獲取服務端資料：

• GET方式在url後面連接參數，只能以正文的形式傳遞參數；

• 傳遞的資料量小，4kb左右（不同瀏覽器會有差異）；

• 安全性低，會將資訊顯示在地址欄；

• 速度快，通常用於對安全性要求不高的請求；

• GET請求也可以有Headers參數

GET請求可以傳遞參數，一般的傳遞方式為 URL傳參。

在GET請求中，遇到參數 / Params / Querys 均是以 URL傳參的形式進行傳遞。

在POSTMAN中，可以直接用 URL傳參形式，也可以在Params處填寫KEY和VALUE，會自動進行連接（示範）。

3.2 POST請求

• post提交資料相對於get的安全性高一些。

• 傳遞資料量大，請求對資料長度沒有要求；

• 用於密碼等安全性要求高的場合，提交資料量較大的場合，如上傳檔案，發佈文章等。

POST請求一般由Url 、 Headers 、 Body組成，如果在POST請求的API文檔裏遇到 Params / Querys 則需以像GET請求一樣使用URL參數傳遞參數，而POST請求的API文檔裏面的參數一般指Body。

範例：

除了登入的API之外，FineBI所有的WEB APIAPI，都需要登入才能使用。

1）正式使用：建議配置單點登入，否則嵌入式整合後，需要反覆登入。詳情請參見：單點登入

2）測試階段：先登入FineBI，然後獲取token參數，並在除錯其他API時，帶上token參數。

本章將講解兩種獲取和使用token參數的方法，任選其一即可。

4.1 fine_auth_token

1）使用者登入FineBI系統。

2）F12，在「Network>Headers」下，獲取fine_auth_token的值。如下圖所示：

3）放在請求的queryString中，以?fine_auth_token=token的參數形式連接到url上、

4.2 Authorization

1）使用者登入FineBI系統。

2）F12，在「Network>Headers」下，獲取Authorization中token的值。如下圖所示：

3）放在請求的 header 中，以 key="Authorization"，value="Bearer " + token的形式存放。

注意Bearer後面的空格，建議直接複製上文黃色高亮區域。

有些API的參數值，需要透過其他API獲取。但是在除錯時，有時需要單個測試API，此時如何獲取這些ID值呢？

6.1 跨域登入API

作用：使用該API可以登入 BI 系統。

URL：/login/cross/domain?fine_username=name&fine_password=password&validity=-1&callback=myfunction

請求方式：GET

6.2 匯出之前自訂

作用：從 BI 的組件匯出或者全局匯出匯出excel時，在匯出操作之前，加入一些自訂操作，可以用這個API實現。比如匯出的檔案進行自訂加密；

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使用需要二次開發。

6.3 獲取完整目錄樹

作用：獲取平台主頁目錄面板

URL：/v10/view/entry/tree

請求方式：GET

注：該API需要攜帶 fine_auth_token 進行認證。

6.4 頁面整合API

很多使用者為了統一門戶，往往會把 FineBI 的後臺管理頁面整合到自己的系統中，本章提供 FineBI 支援的頁面整合API。

1）API

支援單獨頁面整合的管理選單範圍如下表所示：

每個API呼叫方法為存取：http://ip:埠/工程名/decision/API呼叫

2）範例

管理者登入數據決策系統，存取連結：http://localhost:37799/webroot/decision/directory，即可存取目錄管理，如下圖所示：

7.1 沒有頁面存取權限

問題描述：

使用者以非管理者身分進入數據決策系統後，存取：http://IP:Port/webroot/decision/API呼叫 ，出現如下報錯：

解決方案：

需要獲得該頁面的權限，請參考 分級權限分配

7.2 拒絕了我們的連結請求

問題描述

FineBI 透過 iframe 頁面嵌入到其他頁面中報錯：xxx拒絕了我們的連結請求，如下圖所示：

解決方案

管理者進入平台，點選「管理系統>安全管理」，關閉點選挾持攻擊防護按鈕。如下圖所示：

7.3 伺服器不支援 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

7.4 傳回錯誤碼

在進行系統整合時，如果後臺有錯誤，會傳回錯誤碼（errorCode），具體異常碼定義可以參考 系統錯誤碼說明