1. 概述
1.1 版本說明
| FineDataLink 版本 | 功能變動 |
|---|---|
| 1.5 | 資料來源中的資料源類型支援 API |
| 4.1.7.3 | 「進階配置」中支援指定回應資料字元編碼方式，詳情參見：資料同步-API |
| 4.2.9.4 | JSON 解析後支援自訂匯出欄位 |
歷史版本更新
| FineDataLink 版本 | 功能變動 |
|---|---|
| 4.0.9 |
|
| 4.0.10 | API交互優化、支援 text/plain 格式的請求內容 |
| 4.0.11 | API中 webservice API取數優化，詳情參見：API输入-Webservice |
| 4.0.13 | JSON 回傳值處理優化 |
| 4.0.17 | API 支援自訂認證 |
| 4.0.19 | 資料去向支援 API 匯出，同時資料來源 API 支援關閉 SSL 證件驗證，詳情參見 API關閉證件驗證 |
| 4.0.23 | API 配置中的 body 請求內容支援使用 Content-Type 為 form-data 和 x-www-form-urlencoded 請求格式， 允許新增多行、每行均為自訂輸入、支援引用參數 |
| 4.1.1 |
|
| 4.1.3 | 支援分頁取數，詳情參見：API輸入-分頁取數 |
1.2 應用場景
使用者希望取出 API 資料後做進一步的資料處理再儲存，此時，資料同步-API 不能滿足需求。
1.3 功能說明
「資料轉換」節點中新增「API 輸入」算子，使用「API 輸入」算子API取數後，可繼續使用其他算子對API資料進行處理。如下圖所示：
注1：若API回傳值為較簡單的 JSON 格式，不需要複雜的解析處理，可直接使用 資料同步-API 進行API取數。
注2：「API 輸入」算子從 API API取數時，可使用參數，參數值可為動態，參數使用的位置請參見本文第四章說明，具體範例請參見本文第五章說明。
2. 前提條件
1）關於 API API資訊介紹，詳情參見：API入門
2）在使用 API API進行取數時，可以提前用 Postman 或者其他 API 除錯工具進行測試，確定 API 的可用性。如下圖所示：
3）需要註冊「API協定（定時）」功能點。
3. 使用限制
1）當前 FDL 內建請求逾時時間是 10s，如果 API 查詢傳回時間超過 10s 將導致任務失敗。
若使用者的資料量較大，API請求時間較長，4.0.13 及之後版本的 FDL API取數時可以在 Header 內使用 FDLTimeout 欄位增大逾時時間。
需注意參數名稱為FDLTimeout，使用者不能自訂參數名的大小寫（參數名大小寫敏感）；參數值需要寫入正整數，且單位為秒（s）。如下圖所示：
注：若資料量較大，JSON 格式資料建議取消勾選「將解析後的JSON資料展開為二維表」，否則會增載入入回應時間。
2）API API取數時，可以在「回傳值處理」設定項中對 JSON 資料進行解析，但對比 JSON解析算子 ，功能上有一定限制，如下表所示：
| 對比項 | 差別 |
|---|---|
| JSON解析算子 | 1）JSON解析算子 中可一次性解析多個欄位，回傳值處理設定項中只能解析一個欄位 2）回傳值處理設定項中若勾選「將解析後的JSON資料展開為二維表」，將只能解析一層路徑；JSON解析算子 可以解析多層路徑 |
| API取數時，回傳值處理設定項（本文 4.1 節內容） |
所以，若API回傳值為較簡單的 JSON 格式，不需要複雜的解析處理，可在回傳值處理設定項中進行解析；否則，建議使用 JSON解析算子 進行解析。
3）若 URL 中的參數值包含[]，需要使用 encodeURIComponent 編碼後再填入，否則會呼叫API失敗。
4. 功能概述
API 取數時，設定介面如下圖所示：
注1：從 API API取出的資料，可匯出為參數（使用參數匯出、參數指派節點、全局參數-指派參數）；或匯出到資料庫、API、簡道雲、檔案系統等位置中。
注2：API API取數時，當 API 使用了 https ，可以取消證件有效性驗證；在 Headers 內新增一個參數，參數名為SSL-certificate-verification，值為 false 即可。詳情請參見：注意事項
4.1 各設定項說明
| 序號 | 內容 | 說明 | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| A | 請求方法 | FDL 支援 GET 和 POST 兩種請求方式。關於 API API說明詳情參見：API入門 | ||||||||||||||||||||||
| B | API地址 | 需要呼叫API的 URL | ||||||||||||||||||||||
| C | 請求參數 URL 傳參(Query參數) |
| ||||||||||||||||||||||
| D | Authorization 認證類型 |
| ||||||||||||||||||||||
| E | Headers 請求參數 |
| ||||||||||||||||||||||
| F | Body 請求內容 | 注：選擇POST請求方式時展示此選項 Body中支援格式選擇，TEXT、JSON、XML body 內容寫法如下：
格式為：GET:"a=123&b=456" POST:{"a":123,"b"=456} | ||||||||||||||||||||||
| G | TLS/SSL 自簽章認證 | 當 API配置了 https 時，支援自簽章證件 配置自簽章證件後，當進行 https 請求時，按照 SSL/TLS 協定進行請求處理 注：支援.p12、.jks的檔案類型
| ||||||||||||||||||||||
| H | 回應內容如果是JSON格式，可進行後續的處理 | 為空預設解析首層節點，可用「$.父節點.子節點」的格式自訂解析層級，例如： 一層：$.store；兩層：$.store.book 詳情請參見本文 4.2 節內容 | ||||||||||||||||||||||
| I | 呼叫頻率控制 | 應用場景： 有的API限制了呼叫頻率，比如有API一分鐘只能呼叫 3 次，超過這個限制本次執行實體會等待 設定「呼叫頻率控制」為每分鐘執行 3 次，分頁取數時，若頁數為 6 頁，第一分鐘的前幾秒呼叫 3 次 API 取前 3 頁資料，等第二分鐘到來後，再呼叫 3 次取最後 3 頁資料 功能說明： 在一個任務實體中，分頁取數多次呼叫 API 受「呼叫頻率控制」控制 控制頻率：秒/分鐘/小時/天
例如控制呼叫頻率為 1 分鐘一次，則任務執行後可以看到日誌，API 一分鐘呼叫一次： | ||||||||||||||||||||||
| J | 分頁取數 | 詳情請參見：API輸入-分頁取數 | ||||||||||||||||||||||
| k | 回應字元編碼 | 指定回應資料字元編碼方式 支援 UTF-8、UTF-16、GBK 三種方式 將按照字元編碼方式解析 API 回應資料 |
4.2 回傳值處理說明
API資料回傳值如果是 JSON 格式，想要取出指定的 JSON 陣列，可以使用「回傳值處理」直接解析 JSON 資料。
資料類型轉換列表：
| 類型分類 | 欄位類型 |
|---|---|
| 整數類 | long，int |
| 字串類 | string |
| 浮點類 | double，float |
| 布爾類 | boolean |
| 日期時間類 | date |
| 其他類型 | 顯示為空 |
以 https://fine-build.oss-cn-shanghai.aliyuncs.com/finedata/doc/book.json 為例。
4.2.1 預設回傳值
API 取數預設傳回的結果將包括所有物件，同時解析首層的節點
即傳回 store、store.book、store.bicycle、store.bicycle.color、store.bicycle.price 資料。
4.2.2 指定回傳值
可以填寫自訂的 JSON 路徑控制只傳回結果中的單個 JSON 物件或者 JSON 陣列
使用「父節點.子節點」的格式自訂解析層級，例如： 一層：store；兩層：store.book；三層：store.book.author
例如想要取出 store 物件中 book 陣列資料，可以在路徑中輸入：$.store.book，可以獲取到 book 陣列下的所有資料，如下圖所示：
例如想要取出 store 物件中的資料，可以在路徑中輸入：$.store，可以獲取到 store 物件下的首層節點的資料：book、bicycle、bicycle.color、bicycle.price，如下圖所示：
更多 JSON 解析運算式詳情參見：JSONPath運算式
4.3 與參數功能配合使用說明
4.3.1 說明
API API取數時，支援引用參數的設定項為：
| 設定項 | 說明 | 備註 |
|---|---|---|
| Params(Query參數) | 參數值支援引用參數 | FDL 中配置和使用參數說明請參見：如何配置並使用參數 |
| Authorization 認證類型 | Bearer Token：Token值支援引用參數 其他認證：Authorization 值支援引用參數 | |
| Headers 請求參數 | 支援引用參數 | |
| Body 請求內容 | Body 內容中支援引用參數 |
API資料匯出為參數說明如下表所示：
| 說明 |
|---|
| 參數指派 節點、參數匯出 算子、全局參數-指派參數 都支援將 API 資料匯出為參數，支援獲取API回應的回應頭header、回應體body、狀態碼 參數指派節點、全局參數-指派參數適用場景： 1）API回傳值為較簡單的 JSON 格式，不需要複雜的解析處理 2）全局參數-指派參數與參數指派節點差別：全局參數-指派參數匯出的參數，可供多個定時任務使用；參數指派節點匯出的參數，只能供參數指派節點的下游節點使用 參數匯出算子適用場景： 1）API取數後，資料需要進行復雜處理後，再匯出為參數 2）一般情況下使用流程： 範例參考： API取數-獲取企業微信人員資訊 文檔的第一章到 2.2 節內容 |
API取數時引用參數說明：使用參數
4.3.2 注意事項
1）無論是API取數時引用參數，或者API資料匯出為參數，都建議參數設定預設值，便於引用參數的節點/算子查看效果；若參數值動態變化（例如每個參數值只能生效 2 分鐘），除錯任務時，想查看參數引用效果需要更新參數預設值。
注：定時任務每次運作都會獲取最新參數值來執行。
2）呼叫API時使用參數：
若參數存在空值，呼叫API將獲取不到資料，所有在呼叫API前，需要過濾掉空值。
需要的參數可能需要加密，建議使用 SparkSQL編碼、加密、解密函式 實現
若需要動態生成簽章值，建議使用「Spark SQL」算子，或使用函式將對應的值連結出來（SQL 腳本、新增計算列等）。
上一篇：不同寫入方式效果說明