API輸入-分頁取數- FineDatalink 幫助文檔

文檔創建者：Roxy

編輯次數：10

最近更新：Nikozhan 于 2026-03-11

1. 概述

1.1 版本

FineDataLink 版本	功能變動
4.1.3	-

1.2 應用場景

需要使用 FineDataLink 取出 API 資料時，由於資料量限制或者API回應時間，有時需要分頁取數。

1.3 功能簡介

位置	功能說明
參數指派節點、資料同步節點取出 API 資料時	「進階配置」設定項中，可開啟「分頁取數」按鈕，對源端 API 資料進行分頁取數，分頁方式支援：頁碼、偏移、游標

位置

功能說明

參數指派節點、資料同步節點取出 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 計算總頁數，當取數次數>=總頁數時，終止循環

要素

說明

API基本情況

1）取數時需要填入 pageNum（頁數）和pageSize（單頁大小）這兩個參數

2）API呼叫成功後，會傳回 totalNum（總資料條數）

分頁方式

因為有 pageNum（頁數）和pageSize（單頁大小）這兩個參數，我們可考慮根據頁碼進行分頁

結束條件

由於有 totalNum ，可透過 totalNum/pageSize 計算總頁數，當取數次數>=總頁數時，終止循環

2.1.2 功能說明

所有分頁方式的分頁取數中，分頁結束條件邏輯：先執行迴路本體，再判斷是否終止循環。範例：假設頁數 pageNum>=totalpages 時，停止執行，當 totalpages 為 8，pageNum 也為 8 時，會先執行 pageNum 為 8 的循環，再終止執行。

維度	說明
取數限制	限制分頁取數的次數。預設為128 不能為空，限制最大值為 10000 當達到循環上限時，還未滿足分頁結束條件，也結束分頁取數，並報錯
分頁方式-頁碼	參數：只能在這個「API輸入算子」內使用、為算子級參數、且同名優先最高；在單次調取API結束後，再自增；使用者可在 Query 參數和Body內的各種格式下使用，與標準的參數用法無差異；更新策略：初始值：使用者可配置初始值，預設為1，不能為空增長間隔：使用者不能修改增長間隔，預設為1，不能為空使用者配置起始值和增長間隔後，每次循環後執行自增動作，自增邏輯為：pageNum=pageNum+增長間隔分頁結束條件： http status：本次循環的API傳回 http status JSONPath：本次循環的API傳回body作為基礎，在這個基礎上透過寫JSONPath獲取資訊（僅支援傳回單個值，如果傳回是陣列或者JSON物件，也格式化為字串）；當回應體的jsonPath沒有時，則取空 requestTimes：分頁取數的循環次數，如果在循環容器中的API輸入算子，該取數次數循環容器每次循環分開計數 pageNum：頁碼參數$pageNum 注：值可以引用參數。
分頁方式-偏移	參數：只能在這個「API輸入算子」內使用、為算子級參數、且同名優先最高；在單次調取API結束後，再自增；使用者可在Query參數和Body內的各種格式下使用，與標準的參數用法無差異；更新策略：初始值：使用者可配置初始值，預設為1，不能為空增長間隔：使用者用可配置增長間隔，預設為20，不能為空使用者配置起始值和增長間隔後，每次循環後執行自增動作，自增邏輯為：offset=offset+增長間隔分頁結束條件： http status：本次循環的API傳回 http status JSONPath：本次循環的API傳回body作為基礎，在這個基礎上透過寫JSONPath獲取資訊（僅支援傳回單個值，如果傳回是陣列或者JSON物件，也格式化為字串）；當回應體的jsonPath沒有時，則取空 requestTimes：分頁取數的循環次數，如果在循環容器中的API輸入算子，該取數次數循環容器每次循環分開計數 offset：偏移參數$offset 注：值可以引用參數
分頁方式-游標	游標：只能在這個「API輸入算子」內使用、為算子級參數、且同名優先最高；用於鏈式循環場景，每次循環後執行繼承更新動作；使用者可在Query參數和Body內的各種格式下使用，與標準的參數用法無差異；更新策略：預設值：預設為空，使用者可輸入、允許為空、支援參數引用，游標參數更新：當回應體的jsonPath沒有時，則取空使用者可以使用本次循環的API傳回的body作為基礎，在這個基礎上透過寫JSONPath作為更新後的值（僅支援傳回單個值，如果傳回是陣列或者JSON物件，也格式化為字串）注：先判斷分頁結束條件，再執行游標參數更新。分頁結束條件： http status：本次循環的API傳回 http status JSONPath：本次循環的API傳回body作為基礎，在這個基礎上透過寫JSONPath獲取資訊（僅支援傳回單個值，如果傳回是陣列或者JSON物件，也格式化為字串）；當回應體的jsonPath沒有時，則取空 requestTimes：分頁取數的循環次數，如果在循環容器中的API輸入算子，該取數次數循環容器每次循環分開計數 cursor：游標參數$cursor 注：值可以引用參數

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 功能說明

設定項	說明
取數限制	限制分頁取數的次數。預設為128 不能為空，限制最大值為 10000 當達到循環上限時，還未滿足分頁結束條件，也結束分頁取數，並報錯
參數	offset參數，代表偏移同名優先最高在單次調取API結束後，再自增使用者可在Query參數和Body內的各種格式下使用，與標準的參數用法無差異
更新策略	初始值：使用者可配置初始值，預設為1，不能為空增長間隔：使用者用可配置增長間隔，預設為20，不能為空使用者配置起始值和增長間隔後，每次循環後執行自增動作，自增邏輯為：offset=offset+增長間隔
分頁結束條件	http status、JSONPath、requestTimes說明請參見本文 3.1.2 節內容 offset：偏移參數$offset 注：值可以引用參數

2.3 分頁方式為游標

2.3.1 取數邏輯

游標分頁邏輯：類似於書簽，記錄當前位置（游標），從這個位置開始取下一次的資料。

範例：

比如有個 API API：

要素	說明
API基本情況	1）取數時需要傳入 cursor 參數，代表從哪個位置開始取數最開始傳0，後續傳傳回參數中的next_cursor值 2）呼叫API後,傳回參數: has_more ，若沒有資料，值為 fslse next_cursor：下一次分頁的游標
游標取數邏輯	根據API基本情況，可看出： 1）分頁結束條件：has_more 為 false，代表資料已經取完，應該結束分頁 2）取數時具體設定：

要素

說明

API基本情況

1）取數時需要傳入 cursor 參數，代表從哪個位置開始取數

最開始傳0，後續傳傳回參數中的next_cursor值

2）呼叫API後,傳回參數:

has_more ，若沒有資料，值為 fslse
next_cursor：下一次分頁的游標

游標取數邏輯

根據API基本情況，可看出：

1）分頁結束條件：has_more 為 false，代表資料已經取完，應該結束分頁

2）取數時具體設定：

提示:

具體範例可參考：分頁取數-分頁方式為游標

2.3.2 功能說明

設定項	說明
取數限制	限制分頁取數的次數。預設為128 不能為空，限制最大值為 10000 當達到循環上限時，還未滿足分頁結束條件，也結束分頁取數，並報錯
參數	cursor 參數同名優先最高用於鏈式循環場景，每次循環後執行繼承更新動作使用者可在Query參數和Body內的各種格式下使用，與標準的參數用法無差異
更新策略	1）預設值：預設為空，使用者可輸入、允許為空、支援參數引用， 2）游標參數更新：當回應體的jsonPath沒有時，則取空使用者可以使用本次循環的API傳回的body作為基礎，在這個基礎上透過寫JSONPath作為更新後的值（僅支援傳回單個值，如果傳回是陣列或者JSON物件，也格式化為字串）注：先判斷分頁結束條件，再執行游標參數更新。
分頁結束條件	http status、JSONPath、requestTimes說明請參見本文 3.1.2 節內容 cursor：游標參數$cursor 值可以引用參數

3. 通用說明

勾選了分頁取數後， API 資料源其他功能說明：

功能說明
重試若 API 輸入分頁取數單次執行呼叫API失敗，沒有重試邏輯，按整個資料轉換節點重試
呼叫頻率控制在一個任務實體中，分頁取數多次呼叫API受「呼叫頻率控制」控制
json路徑
將解析後的json資料展開為二維表
如果API節點只配置了分頁取數，將每次取數獲得的json拼成一個一欄N行的二維表（該二維表只有一欄 responseBody）
如果API節點本身配置了分頁取數&Json路徑，將每次取數獲得相應路徑下的json，拼成一個一欄N行的二維表（該二維表只有一欄responseBody）
因為每次分頁取數時獲得 json 可能不一樣，如果找不到相應json路徑，則為空
如果 API 節點本身配置了分頁取數&Json 路徑為「$.data」&勾選「將解析後的JSON資料展開為二維表」，將每次取數獲得相應路徑下 json 進行拆列，拼成一個N列N行的二維表
因為每次分頁取數時獲得 json 可能不一樣，每次將json展開二維表時，如果遇到新的屬性，則新增列
沒有相關屬性的分頁取數，相關列為空
回傳值格式當回應體格式為 xml 時，不支援分頁取數
資訊類型（參數指派）
回應體
回應頭
狀態碼
如果參數指派同時解析回應體、回應頭、狀態碼，將每次取數獲得回應拼成一個N列N行的二維表

功能	說明
重試	若 API 輸入分頁取數單次執行呼叫API失敗，沒有重試邏輯，按整個資料轉換節點重試
呼叫頻率控制	在一個任務實體中，分頁取數多次呼叫API受「呼叫頻率控制」控制
json路徑將解析後的json資料展開為二維表	如果API節點只配置了分頁取數，將每次取數獲得的json拼成一個一欄N行的二維表（該二維表只有一欄 responseBody）如果API節點本身配置了分頁取數&Json路徑，將每次取數獲得相應路徑下的json，拼成一個一欄N行的二維表（該二維表只有一欄responseBody）因為每次分頁取數時獲得 json 可能不一樣，如果找不到相應json路徑，則為空如果 API 節點本身配置了分頁取數&Json 路徑為「$.data」&勾選「將解析後的JSON資料展開為二維表」，將每次取數獲得相應路徑下 json 進行拆列，拼成一個N列N行的二維表因為每次分頁取數時獲得 json 可能不一樣，每次將json展開二維表時，如果遇到新的屬性，則新增列沒有相關屬性的分頁取數，相關列為空
回傳值格式	當回應體格式為 xml 時，不支援分頁取數
資訊類型（參數指派）回應體回應頭狀態碼	如果參數指派同時解析回應體、回應頭、狀態碼，將每次取數獲得回應拼成一個N列N行的二維表

已經是第一篇

已經是最後一篇

有幫助
沒幫助
只是瀏覽

中文（简体） English

中文（繁體）

API輸入-分頁取數

1. 概述

1.1 版本

1.2 應用場景

1.3 功能簡介

1.4 使用限制

2. 分頁方式說明

2.1 分頁方式為頁碼

2.1.1 取數邏輯

2.1.2 功能說明

2.2 分頁方式為偏移

2.2.1 取數邏輯

2.2.2 功能說明

2.3 分頁方式為游標

2.3.1 取數邏輯

2.3.2 功能說明

3. 通用說明

附件列表