BI RestAPI 資料集插件

1.1 版本

1.2 功能場景

BI Rest API資料集支援FineBI對接WEB API進行取數。

對接第三方的WEB API進行取數。

透過JSON解析傳回的資料。

直連資料集支援直連傳遞參數呼叫第三方的WEB API 。

1.3 注意事項

1）Rest API資料集不支援增量更新的方式 。

2.1 插件安裝

插件獲取：BI Rest API資料集插件

設計器插件安裝方法參照：設計器插件管理

伺服器安裝插件方法參照：伺服器插件管理

插件安裝、更新、禁用後重新啟動，都需要重啟FineBI才會生效。

2.2 使用流程

1）安裝插件後，公共資料的建立資料集中出現“Rest資料集”選項。

2）點選進入建立資料集介面，完成相關配置後，點選儲存。

3）在資料預覽模組，可以預覽新增的資料集，該資料集可以用於BI分析中。

2.3 面板配置說明

①：資料集名稱，可重新命名。

②：請求類型，支援GET和POST請求方式。

③：URL位址，填寫API完整地址即可。

URL參數：Query參數會自動連接到URL地址中。

API認證：支援的認證方式有：無認證、Basic Auth、Bearer Token、動態Token認證、其他認證（自訂Token）。

請求頭：新增請求頭參數 。

請求體：只有在POST請求方式下，才需要配置Body 。

表單方式支援：form-data 與 x-www-form-urlencoded 。

正文方式支援：TEXT、JSON、XML 。

回傳值處理：回傳值處理支援JSON解析，透過使用JsonPath語句，尋找節點、獲取想要的資料 。

參數設定：支援配置參數，可以在API配置中引用參數，URL、Query參數值、認證參數、Header參數值、Body中均可使用 。

引用形式：${參數名} 。

在直連資料集裏，此處參數支援實時傳參呼叫 。

2.4 全局配置

在“管理系統 > 系統管理 > 標準 > RestAPI全局配置”中可以進行全局配置，設定日誌和連結池相關屬性 。

1）當前預設都匯出為正文欄位。如需修改欄位類型，點選如圖所示的”編輯”按鈕，進行欄位類型轉換。

2）rest API資料集不支援增量更新的方式。

4.1 功能說明

動態Token鑑權用於以下場景：

業務API呼叫前，需要先請求一個取TokenAPI 。

Token不是固定值，而是需要按API傳回結果動態獲取 。

正式業務請求中，需要在Header、Query、Body或URL中引用該Token 。

Token存在有效期，希望在一定時間內複用，避免每次都重複獲取 。

整體執行流程如下：

先呼叫配置好的TokenAPI 。

從TokenAPI回應中按JSON Path提取Token值 。

將提取出的原始Token寫入運作時變數 ${dynamic_token} 。

執行正式業務請求，並將 ${dynamic_token} 取代到URL、Header、Query、Body中 。

4.2 配置入口

在資料集配置頁面中：

• 開啟配置TAB 。

• 找到認證方式 。

• 選擇 動態Token 。

可用運作時變數：

• ${dynamic_token}：取TokenAPI傳回並提取到的原始Token值 。

4.3 欄位說明

4.3.1 TokenAPIURL

填寫獲取Token的API地址 。

https://api.example.com/auth/token

說明：

• 支援資料集參數取代 。

• 該地址用於插件先發起一次Token請求 。

4.3.2 請求方式

當前支援：

• GET

• POST

說明：

• 若選擇POST，可以同時配置請求體 。

• 若不是GET，後端會按POST處理 。

4.3.3 Token JSON路徑

用於從TokenAPI回應中提取token欄位，文法為JSON Path 。

$.token

$.data.access_token

$.result.token

要求：

• 該路徑必須能提取到非空值 。

• 若提取結果為空，正式請求不會繼續執行，並提示獲取動態Token失敗 。

4.3.4 啟動快取

用於控制是否快取Token 。

• 關閉：每次執行業務請求前都重新獲取Token 。

• 開啟：命中快取時直接複用Token，不再重複呼叫TokenAPI 。

4.3.5 快取模式

啟動快取後可選兩種模式：

• 固定時長：手工指定快取秒數 。

• 從回應提取過期時長：從TokenAPI回應裏取TTL欄位 。

4.3.6 快取時長(秒)

僅在固定時長模式下生效 。

3600

說明：

• 表示Token快取1小時 。

• 小於等於0時，不會形成有效快取 。

4.3.7 過期時長JSON路徑

僅在從回應提取過期時長模式下生效 。

$.expires_in

$.data.expires

說明：

• 該欄位應為數字，或可轉換為數位的字串 。

• 若取值失敗或不是數字，會提示動態Token過期時長解析失敗 。

4.3.8 TokenAPI請求體

用於配置獲取Token時傳送的請求體 。

{

  "clientId": "demo_client",

  "clientSecret": "demo_secret"

}

說明：

• 僅在Token請求方式為POST時生效 。

• 若未手工設定Content-Type，插件會預設補 application/json 。

• 支援資料集參數取代 。

4.3.9 TokenAPI請求Header參數

用於配置獲取TokenAPI時附帶的請求頭 。

Content-Type: application/json

X-App-Id: demo-app

說明：

• 支援配置多個Header 。

• Header值支援資料集參數取代 。

4.4 正式請求中如何使用Token

動態Token拿到後，會提供變數 ${dynamic_token}，可用於以下位置：

• 正式請求URL 。

• Query參數 。

• Header參數 。

• Body內容 。

範例一：放在查詢參數中 。

token=${dynamic_token}

範例二：放在Header中 。

X-Access-Token: ${dynamic_token}

範例三：放在JSON請求體中 。

{

  "token": "${dynamic_token}",

  "keyword": "${keyword}"

}

4.5 配置範例

4.5.1 場景範例

先呼叫登入API：

POST /auth/login

Content-Type: application/json

{

  "username": "demo",

  "password": "123456"

}

傳回：

{

  "code": 0,

  "data": {

    "access_token": "abc123xyz",

    "expires_in": 7200

  }

}

再呼叫業務API：

GET /orders/list

X-Access-Token: abc123xyz

4.5.2 動態Token配置範例

可按下面方式填寫：

• TokenAPIURL：https://api.example.com/auth/login

• 請求方式：POST

• Token JSON路徑：$.data.access_token

• 啟動快取：是

• 快取模式：從回應提取過期時長

• 過期時長JSON路徑：$.data.expires_in

• TokenAPI請求Header參數：Content-Type=application/json

TokenAPI請求體：

{

  "username": "demo",

  "password": "123456"

}

正式業務請求中可這樣使用：

• Header：X-Access-Token = ${dynamic_token}

• Query：access_token = ${dynamic_token}

• Body："token": "${dynamic_token}"

4.6 預覽除錯建議

動態Token配置區自帶預覽按鈕，建議先單獨預覽TokenAPI，確認以下幾點：

• TokenAPIURL可存取 。

• 請求方式正確 。

• 請求Header和請求體正確 。

• 傳回結果中確實包含目標token欄位 。

• JSON Path能正確提取到值 。

如果TokenAPI預覽透過，再配置正式業務請求裏的 ${dynamic_token} 引用 。

4.7 注意事項

4.7.1 ${dynamic_token} 是保留運作時變數

不要把 dynamic_token 當作普通資料集參數使用 。

說明：

• 該變數由插件在運作時寫入 。

• 它會保留到正式請求發起前再取代 。

• 即使存在同名使用者參數，也不會改寫運作時動態Token值 。

4.7.2 TokenAPI參數取代範圍

當前支援資料集參數取代的Token配置項包括：

• TokenAPIURL 。

• TokenAPI請求體 。

• TokenAPI請求Header的值 。

不建議把動態運算式放在以下配置項中：

• Token JSON路徑 。

• 快取模式 。

• 快取時長 。

• 過期時長JSON路徑 。

4.7.3 快取鍵的組成

以下配置變化會影響快取命中：

• TokenAPIURL 。

• 請求方式 。

• 請求體 。

• Token JSON路徑 。

• Token請求Header 。

• 快取模式 。

• 快取時長 。

• 過期時長JSON路徑 。

只要這些配置變化，插件會認為是另一份Token快取 。

4.8 常見問題

4.8.1 為什麼提示獲取動態Token失敗？

請優先檢查：

• TokenAPIURL是否可存取 。

• 請求方式是否正確 。

• 請求Header和請求體是否正確 。

• Token JSON路徑是否能提取到值 。

• TokenAPI是否傳回了空token 。

4.8.2 為什麼快取沒生效？

請檢查：

• 是否已開啟快取 。

• 固定時長是否大於0 。

• 若按回應提取TTL，JSON路徑是否正確 。

• TTL欄位是否為數字 。

4.8.3 為什麼目標API沒有識別到Bearer Token？

因為動態Token只會提供運作時變數 ${dynamic_token}，不會自動幫你組裝：

Authorization: Bearer <token>

如果業務API必須要求Bearer前綴，請在正式請求Header中手工配置：

Authorization = Bearer ${dynamic_token}

補充：如果目標服務要求的是自訂Header，也可以直接把 ${dynamic_token} 放到對應Header、Query或Body欄位中 。