1. 概述
1.1 版本
| FineBI 版本 | FineBI JAR 包 |
|---|---|
| 5.1.10 | 2021-02-05 |
| 6.X | 2022-09-23 |
1.2 應用場景
客戶希望在自身的第三方業務系統中，透過存取應用，呼叫API的方式，實現帆軟決策系統的管理效果，以及自訂的資料服務功能
1）IT部門，基於開放平台，實現企業內各系統的互聯互通。
2）軟體公司，透過整合方式，實現其行業產品的帆軟相關功能。
3）終端企業，基於API服務，實現客製化需求。
1.3 功能簡介
帆軟提供「開放平台」插件：
1）提供安全、靈活、規範、有效的 web 服務，方便開發人員快速構建應用，實現在自身的業務系統中，對帆軟系統、報表進行相應的管理、開展資料服務。
2）提供統一的平台配置，實現用戶端API的權限管理、安全認證管理。
3）提供日誌管理功能，實現對於 API、應用的請求、存取狀態查看。
1.4 業務流程
1.5 公共API
1）官方API
對於開放平台中內建API，帆軟提供相關 API 文檔，方便使用者進行理解和使用。
該 API 文檔，僅作為官方範例，提供給具備自主產品整合能力的使用者使用。技術支援不負責API範例的維護和使用問題解答。
注：平台API文檔為開放平台文檔。
FineBIAPI文檔為同系列其他API插件文檔，需下載安裝相應子插件後，方可正常使用。
| 分類 | 對應插件 | API文檔 |
|---|---|---|
| 平台 | 開放平台插件 | 平台API文檔 |
| FineBI | FineBIAPI文檔 |
2. 插件簡介
2.1 插件安裝
點選下載插件：開放平台插件
設計器插件安裝方法參照：設計器插件管理
伺服器安裝插件方法參照：伺服器插件管理
注：在安裝&升級插件時，如果同時安裝了同系列插件，需要在安裝&升級開放平台插件後重啟伺服器！
同系列插件列表：開放平台、開放平台-FineBIAPI、開放平台-FineReport報表API、開放平台-平台登入認證API。
2.2 介面簡介
插件安裝成功後，管理者登入數據決策系統，點選「管理系統>開放平台」，即可進入功能介面，如下圖所示：
3. 功能簡介
各模組功能簡介如下表：
| 模組 | 功能簡介 |
|---|---|
| API管理 | API查看：API功能、呼叫方式等 API管理：支援API的增刪改查和複製使用 |
| 應用管理 | 建立應用，系統自動生成應用ID和金鑰，作為API呼叫的證件 |
| 認證方式 | API認證方式管理，預設提供三種備選認證方式，可新增自訂認證方式 |
| 權限管理 | 為應用管理中的建立應用，開放API的呼叫權限 |
| 日誌管理 | 展示API呼叫情況 |
3.1 API管理
在「API管理」中，包含第三方系統與 Finereport 進行資料互動服務的所有配置。
1）分組管理
「API管理」介面左側為分組。平台已內建多個分組，使用者可根據需需求，自行增刪分組。
對於內建分組，使用者不可刪除和編輯。
對於非內建分組，使用者可進行編輯、刪除等操作。被刪除的分組內的 API，會自動行動到預設分組中。
2）API管理
每個分組中可儲存多個 API。平台已內建部分常用的 API，使用者也可自行新增 API。
對於內建 API，使用者僅可進行編輯、複製、更換分組操作，不可刪除和禁用。
對於非內建 API，使用者可進行編輯、複製、更換分組、刪除和禁用等操作。
3.2 應用管理
1）新增應用
在「應用管理」中，使用者可以透過新增事件的方式，建立應用。
使用者點選「應用管理」，點選「增加」，設定相關內容，點選「確定」，即可新增應用。
自動生成的「應用ID」和「金鑰」，可用於 API 的鑑權，作為第三方系統的存取證件。
| 設定項 | 說明 |
|---|---|
| 應用名稱 | 應用的名稱，必填 |
| 應用描述 | 應用的描述，選填 |
| 備選認證 | 認證方式中預先設定好的幾種方式，選填 |
2）應用管理
對於新增的應用，支援新增、編輯、複製、禁用、單個刪除、批量刪除等操作。編輯時可重置金鑰。
3.3 認證方式
3.3.1 通用認證方式
是所有的應用API天然支援的認證方式。不論是否選擇備選認證，該認證方式均可用。
獲取 token 的請求連結為：$HOST/sp/client/api/token
API 方法為：POST
clientToken。根據對應 API 的配置，修改 API 方法與地址，即可呼叫相應的 API API。
整體效果如下圖所示：
3.3.2 內建備選認證方式
開放平台內建了三種備選認證方式，僅允許使用者編輯、複製，不支援刪除和禁用，如下圖所示：
| 認證方式 | 說明 |
|---|---|
| 國密SM2簽章認證 | 利用國密SM2橢圓算法進行加解密，對應用ID、金鑰以即時間戳進行簽章後，透過簽章和應用ID進行認證。 其中配置項 priKey=金鑰、timeout=逾時時間（秒） 簽章_sign_=SM2(應用ID+金鑰+時間戳)+時間戳 在 Headers 中新增 _sign_={計算值}，client_id={應用ID}，即可直接存取應用 |
| 摘要簽章認證 | 在不能使用 token 認證的情況下，可使用摘要演算法（比如 SM3/MD5/ SHA256），對應用ID、金鑰以即時間戳進行簽章後，透過簽章和應用ID進行認證。 其中配置項 method=摘要算法、timeout=逾時時間（秒） 簽章_sign_= 摘要算法(應用ID+金鑰+時間戳)+時間戳 在 Headers 中新增 _sign_={計算值}，client_id={應用ID}，即可直接存取應用 推薦使用這種認證方式，安全性更高 範例：
此時，簽章_sign_ = MD5(client_id+secret+timestamp)+timestamp = EE6E14BCEC5724C3BC6FC08AFC5C2B111600166180321 |
| AkSk直接認證 | 使用應用ID和金鑰直接作為認證依據，直接呼叫服務。 無配置項，認證方式的編輯介面的配置資訊，不可自行編輯。 在 Headers 中新增 client_id={應用ID}、secret={金鑰} 即可直接存取應用 出於安全考慮，不推薦使用這種認證方式 |
3.3.3 自訂備選認證方式
編輯、禁用、單個刪除、批量刪除等操作。
在「認證方式」頁面，點選「增加」按鈕，設定相關配置項，點選「確定」，即可新增認證方式。如下圖所示：
| 配置項 | 說明 |
|---|---|
| 基礎 | 支援自訂「認證名稱」、「認證描述」和「API類」，方便使用者區分設定的認證方式 1）「認證名稱」必填，不可為空 2）「認證描述」選填 3）「API類」是需要實現的認證API的例項物件。同一個類，可以透過配置的改變，實現多種認證方式。 |
| 配置 | 在認證方式的編輯介面的配置資訊中，需進行一些固定配置，例如摘要簽章認證需要定義「摘要算法」和「有效期」； 配置可以設定為加密項，這樣加密後的資訊在儲存後，也無法從前端讀取 |
| 預設參數 | 自訂參數設定 |
注：在部分使用了nginx的環境中，client_id的底線會被識別為無效
當前的解決方案是傳遞 client_id和 clientId 均可被識別，已完成迭代相容
| 參數名 | 別名 |
|---|---|
| client_id | clientId |
| client_token | clientToken |
3.4 權限管理
針對非公開API，呼叫均需要做權限驗證。不同的場景、不同的應用，可呼叫的API範圍是不一樣的。管理者可以權限管理下，進行權限配置。
公開API可以隨意呼叫，不受權限驗證的約束。
注：目前不存在分組權限，意思是即使把某個分組權限開啟了，實質上也只是把當前分組下面的API的權限分配給了某個應用。
如果後續發生了API分組變更，或者該分組下API新增，那麼之前已設定好的API權限是不變的。
例如：針對一個應用，開啟目錄樹管理的分組權限，相當於開啟下屬所有API的權限。如果該分組下的API更換到其他分組，則該API仍保持權限開啟的狀態；如果在目錄樹管理的分組下，新增API，則該API為權限關閉狀態
3.5 日誌管理
在日誌管理中，管理者可以查看 API 的請求頻率和詳細記錄。
3.6 全局設定
