1. 概述
1.1 版本
| FineDataLink 版本 | 功能變動 |
|---|---|
| 4.1.3 | - |
1.2 應用場景
需要使用 FineDataLink 取出 API 資料時，由於資料量限制或者API回應時間，有時需要分頁取數。
1.3 功能簡介
| 位置 | 功能說明 |
|---|---|
| 參數指派節點、資料同步節點取出 API 資料時 | 「進階配置」設定項中，可開啟「分頁取數」按鈕，對源端 API 資料進行分頁取數，分頁方式支援：頁碼、偏移、游標
|
1.4 使用限制
當前只支援回傳值為 json 的 API。
2. 分頁方式說明
2.1 分頁方式為頁碼
2.1.1 取數邏輯
FineDataLink 提供 pageNum 這個參數進行分頁取數，代表頁數，可自訂該參數的初始值，增長間隔為1（不可自訂）。
比如取數時，設定從第一頁開始取數，下次從第二頁開始取數，以此類推，分頁取數的次數限制為 10000 次。
使用者還需根據實際情況設定循環結束條件。
範例說明（幫助理解功能）：
比如有個 API API，存在大量資料，需要進行分頁取數：
| 要素 | 說明 |
|---|---|
| API基本情況 | 1）取數時需要填入 pageNum（頁數）和pageSize（單頁大小）這兩個參數 2）API呼叫成功後，會傳回 totalNum（總資料條數） |
| 分頁方式 | 因為有 pageNum（頁數）和pageSize（單頁大小）這兩個參數，我們可考慮根據頁碼進行分頁 |
| 結束條件 | 由於有 totalNum ，可透過 totalNum/pageSize 計算總頁數，當取數次數>=總頁數時，終止循環 |
2.1.2 功能說明
所有分頁方式的分頁取數中，分頁結束條件邏輯：先執行迴路本體，再判斷是否終止循環。範例：假設頁數 pageNum>=totalpages 時，停止執行，當 totalpages 為 8，pageNum 也為 8 時，會先執行 pageNum 為 8 的循環，再終止執行。
| 維度 | 說明 |
|---|---|
| 取數限制 | 限制分頁取數的次數。
|
分頁方式-頁碼 | 參數：
更新策略：
使用者配置起始值和增長間隔後，每次循環後執行自增動作，自增邏輯為：pageNum=pageNum+增長間隔 分頁結束條件：
注：值可以引用參數。 |
| 分頁方式-偏移 | 參數：
更新策略：
使用者配置起始值和增長間隔後，每次循環後執行自增動作，自增邏輯為：offset=offset+增長間隔 分頁結束條件：
注：值可以引用參數 |
| 分頁方式-游標 | 游標：
更新策略：
注：先判斷分頁結束條件，再執行游標參數更新。
分頁結束條件：
注：值可以引用參數 |
2.2 分頁方式為偏移
2.2.1 取數邏輯
在API 分頁取數時，偏移（offset） 是指從結果集的開頭開始跨越的記錄數量，它決定了當前請求從哪一筆資料開始傳回。
簡單來說，偏移就是“跨越前面多少筆資料，從第幾條開始拿”。
核心概念：
偏移（offset）：指定查詢結果的起始位置，即跨越多少條記錄後開始傳回資料。索引從 0 開始，所以 offset=0 表示從第 1 筆資料開始，offset=10 表示跨越前 10 條，從第 11 條開始取數。
限制條數（limit）：指定每次請求最多傳回多少筆資料。
範例：
比如有個 API API，存在大量資料，需要進行分頁取數：
| 要素 | 說明 | |
|---|---|---|
| API基本情況 | 呼叫API時，需要需要填寫偏移和限制條數參數 | |
| 分頁方式 | 可考慮用偏移的分頁方式 | |
| 結束條件 | 比如一共有 10 筆資料，從第一筆資料開始取數（startrow）,每次最多取 3 條，那麼需要取 4 次，最後一次的資料條數為 2 條，那麼循環結束條件就是：最後一次的資料條數<limit參數的值 如果每次取兩條，那麼取 5 次取完，那麼循環結束條件可設定為最後一次取數條數>0 可以用其他標準設定結束條件，根據實際情況設定
|
提示:
具體範例可參考：分頁取數-按偏移取數
2.2.2 功能說明
| 設定項 | 說明 |
|---|---|
| 取數限制 | 限制分頁取數的次數。
|
| 參數 | offset參數，代表偏移
|
| 更新策略 |
使用者配置起始值和增長間隔後，每次循環後執行自增動作，自增邏輯為：offset=offset+增長間隔 |
| 分頁結束條件 | http status、JSONPath、requestTimes說明請參見本文 3.1.2 節內容
|
2.3 分頁方式為游標
2.3.1 取數邏輯
游標分頁邏輯：類似於書簽，記錄當前位置（游標），從這個位置開始取下一次的資料。
範例：
比如有個 API API：
| 要素 | 說明 |
|---|---|
| API基本情況 | 1）取數時需要傳入 cursor 參數，代表從哪個位置開始取數 最開始傳0，後續傳傳回參數中的next_cursor值 2）呼叫API後,傳回參數:
|
| 游標取數邏輯 | 根據API基本情況，可看出： 1）分頁結束條件：has_more 為 false，代表資料已經取完，應該結束分頁
2）取數時具體設定：
|
2.3.2 功能說明
| 設定項 | 說明 |
|---|---|
| 取數限制 | 限制分頁取數的次數。
|
| 參數 | cursor 參數
|
| 更新策略 | 1）預設值：預設為空，使用者可輸入、允許為空、支援參數引用， 2）游標參數更新：
注：先判斷分頁結束條件，再執行游標參數更新。 |
| 分頁結束條件 |
http status、JSONPath、requestTimes說明請參見本文 3.1.2 節內容
|
3. 通用說明
勾選了分頁取數後， API 資料源其他功能說明：
| 功能 | 說明 |
|---|---|
| 重試 | 若 API 輸入分頁取數單次執行呼叫API失敗，沒有重試邏輯，按整個資料轉換節點重試 |
| 呼叫頻率控制 | 在一個任務實體中，分頁取數多次呼叫API受「呼叫頻率控制」控制 |
|
因為每次分頁取數時獲得 json 可能不一樣，如果找不到相應json路徑，則為空
因為每次分頁取數時獲得 json 可能不一樣，每次將json展開二維表時，如果遇到新的屬性，則新增列 沒有相關屬性的分頁取數，相關列為空 |
| 回傳值格式 | 當回應體格式為 xml 時，不支援分頁取數 |
資訊類型（參數指派）
| 如果參數指派同時解析回應體、回應頭、狀態碼，將每次取數獲得回應拼成一個N列N行的二維表 |
上一篇：API輸入
