Quick BI：建立API資料來源

步驟一：建立API串連

您需要在此步驟中配置API串連的基礎認證資訊、串連方式及參數設定，具體操作說明如下。

1. 配置基礎認證下各項內容的資訊。

   參數名稱	描述
   串連名稱	API介面在Quick BI資料來源列表顯示的自訂名稱。 名稱由漢字、數字、字母、底線（_）或短劃線（-）組合而成。
   介面地址	輸入API介面的請求地址。
   請求類型	選擇API介面的請求類型，支援GET和POST兩種類型，預設為GET。 GET：通常用於請求伺服器上的資源，為資料檢索行為，不能修改伺服器上的資料。 POST：通常用於向伺服器傳輸資料，例如提交表單，可以修改伺服器上的資料。

2. 選擇串連方式，支援選擇抽取或直連。

   • 抽取：支援手動或周期性定時更新資料，適用於資料即時性要求低的情境。

   • 直連：支援直連API查詢，即時更新資料，適用於即時性要求高的小資料量情境。

     直連方式支援開啟短效緩衝，緩衝時間可以選擇5分鐘、10分鐘、30分鐘。開啟後，在一定時間內可避免重複發送請求，保護源端API服務訪問效能不受影響，並節省API服務的調用費用。

     說明

     直連模式下，每次請求返回的資料量應滿足以下條件：不超過10MB，同時列數不超過100列，行數不超過1000行。

     

3. （可選）在參數設定中配置需要傳參的資料，您可以按需決定是否配置。

   參數名稱	描述
   普通參數	請求地址後面的參數即為普通參數，格式為url?key1=value1&key2=value2。 您可以單擊添加參數，通過普通參數傳參。例如，對於資料量過大的API介面，您可以通過分頁的方式請求，提供一個動態參數 ${PageIndex} 進行傳參。關於參數的具體介紹請參見參數介紹。
   頭參數	存放在Header中的即為頭參數。 通常不變的量通過Header傳參，支援手動增（①）刪（②）改（③）Header參數。 關於參數的具體介紹請參見參數介紹。
   請求體	當基礎認證中的請求類型為POST時，參數設定中可維護請求體資訊。 請求體通常用於攜帶使用者需要向伺服器發送的資料，其具體內容和格式，需要您根據當前API的欄位內容自行編寫。 Quick BI支援JSON、x-www-form-urlencoded兩種請求體格式。 JSON：處理複雜的資料結構，適用於資料中包含嵌套對象或數組的情境。 x-www-form-urlencoded：處理簡單的索引值對資料，適用於表單提交的簡單情境。
   授權驗證	您可以選擇無需授權驗證，也可以選擇基礎認證和摘要認證。 具體說明請參見http認證鑒權01基本認證和摘要認證。
   前置請求	如果在請求API之前，需要執行一些準備工作或驗證步驟，例如：需要先通過鑒權介面拿到Token才能順利調用當前API，此時您可以為當前API設定前置請求。 設定完成後，在調用主 API 前，系統將按序執行已添加的“前置請求”。同時，支援將該請求中的響應結果儲存為動態參數，引用至主 API 的頭參數、普通參數、請求體，或其他前置請求中，以實現參數的動態擷取。 關於前置請求的使用樣本，請參見操作樣本。 說明 最多支援添加3個前置請求。

4. 點擊測試連接，成功後進入下一步。

步驟二：解析請求結果

在解析請求結果環節下的資料結構地區，會呈現當前API請求返回的所有欄位，您可以根據需要選中欄位並修改欄位類型。

步驟三：資料同步設定

在資料同步設定環節中，設定API資料來源的更新周期。

1. 點擊更新周期選擇框，在下拉式清單中，選擇API資料來源的更新周期，支援選擇手動更新或定時更新。

   說明

   僅當串連設定中的串連方式為抽取時，才需配置更新周期。

   

   • 選擇手動更新，手動觸發後，才會進行資料的同步。

   • 選擇定時更新並配置更新頻率（天級或小時級）後，則每日會定時進行資料的同步。

2. 點擊完成即可建立API資料來源。成功後，可以在API資料來源管理介面，看到您建立的資料來源。

   支援在此通過單擊API資料來源右側的表徵圖編輯API資料來源。

   說明

   不支援編輯串連方式。

   

步驟一：建立API串連

在建立API串連環節中，按以下步驟配置資訊。

1. 配置基礎認證資訊。

   • 串連名稱：本例以API介面的業務意義作為名稱，填入擷取使用者考勤資料。

   • 介面地址：在API文檔頁面擷取其請求地址。

   • 請求類型：在API文檔頁面擷取其請求類型，本例為POST。

2. 配置串連方式。

   本例只需擷取當天的考勤資料，對資料的即時性要求較低，因此串連方式選擇抽取。

   

3. 配置前置請求。

   在調用擷取使用者考勤資料介面（以下稱為主API介面）前，需要提前通過擷取企業內部應用的access_token介面擷取access_token，並將其注入在主API介面的請求地址中，才能順利調用主API介面擷取考勤資料。因此本例需要將擷取access_token步驟配置在前置請求中，並將其作為普通參數拼接到主API介面的請求地址。具體前置請求配置操作如下。

   1. 點擊前置請求頁簽下的添加前置請求操作。

   2. 在添加前置請求彈窗中，完成以下配置。

      • 串連名稱：本例填入鑒權介面的業務意義，即擷取企業內部應用的access_token。

      • 介面地址：通過介面文檔擷取鑒權介面的請求地址。

      • 請求類型：通過介面文檔擷取鑒權介面的請求類型，本例為GET。

      • 普通參數：根據介面文檔，請求地址後需要攜帶appkey及appsecret參數，因此在普通參數中添加appkey及appsecret，並輸入對應值。完成後參數將會被自動拼接到請求地址後。

      • 頭參數：本例保持預設設定，即選中Content-Type為application/json，以告訴接收請求的伺服器，傳輸資料的格式為JSON；Connection為keep-alive，以告訴接收請求的伺服器，當前請求需要持久串連。

   3. 點擊串連測試，即可在請求結果模組中，查看當前請求的返回資訊。同時，Quick BI將為您自動解析請求結果中包含的欄位，您可以在動態參數模組中按需選擇欄位作為動態參數，並在主API中通過${參數名稱}的方式進行引用；也可以僅執行前置請求而不傳遞動態參數（即不設定動態參數）。

      本例需要將前置請求中擷取的access_token，作為動態參數傳遞至主API中，因此本例建立access_token動態參數。

      說明

      最多可添加10個動態參數。

      

4. 配置普通參數。

   本例根據主API調用要求，需要將前置請求中建立的動態參數access_token，通過${參數名稱}的方式引用至主API的普通參數中，因此在普通參數頁簽下點擊添加參數操作。

   說明

   動態參數支援引用至主API的普通參數、頭參數、請求體或其他前置請求中，在實際操作中您可以按需選擇。

   

5. 填入參數名稱，點擊參數值輸入框中的表徵圖，在喚起的變數面板中按需選擇參數，完成後點擊表徵圖儲存配置。

   本例需將變數面板切換至動態參數頁簽，在該頁簽下展示了當前流程中已建立的動態參數，選擇${access_token}。

6. 配置請求體。

   本例請求類型為POST，因此需要根據擷取企業內部應用的access_tokenAPI的請求參數內容，編寫請求體。

   • JSON格式範例程式碼如下：

     {
         "work_date": "2024-11-14",
         "userid": "user01"
     }

   • x-www-form-urlencoded格式範例程式碼如下：

     work_date=2024-11-14&userid=user01

7. 其餘參數配置。

   本例頭參數及授權驗證保持預設設定。

8. 點擊串連測試，成功後進入下一步。

步驟二：解析請求結果

在解析請求結果環節中，選中需要的欄位並調整其欄位類型，完成後點擊下一步。

步驟三：資料同步設定

1. 在資料同步設定環節中，設定本例API資料來源的更新周期為手動更新。

   

2. 點擊完成，成功建立擷取使用者考勤資料API資料來源。