循环容器逻辑说明

1.1 版本說明

1.2 應用場景

• 使用者需要從 API 取數， API 的參數來自資料庫內的一欄欄位。由於 API中，參數每次只能讀取一個參數值，所以需要將資料庫的某列欄位值逐個匯出為參數，遍曆所有參數從 API 取數。

• 資料量非常大時，使用者希望分段執行，每次只取出一段時間內的資料，直至取出所有時間段內的資料。

1.3 功能簡介

「循環容器」節點+參數 聯合使用，可滿足分批抽取資料的場景。如下圖所示：

FDL 中，遍歷循環方式下又分為：遍歷循環（For-Each Loop）、並行遍歷（For-Each Parallel）。

1.3.2 条件循环

• 若想使用「循環容器」功能，需註冊「循環容器」功能點。詳情請參見：FineDataLink功能点注册授权

• 參數指派的參數只能給其下遊節點使用，循環容器內也是一樣的。

• 「循環容器」節點內不能拖入的節點類型：「呼叫任務」節點和「循環容器」節點。

3.1 遍曆循環（For-Each Loop）

3.1.1 使用說明

「循環容器」節點前，需要使用「參數指派節點」節點或者「參數匯出」算子匯出參數，然後在「循環容器」中遍曆所有參數從資料庫/API中取數。

注：每次循環使用的參數，來自容器外&循環容器上遊。

為便於理解，下面以一個範例說明遍曆循環。詳情參見文檔：循环容器典型示例-API取数 

場景：

API API中包含參數 data_id，可取出特定 data_id 的API資料。

現在 data_id 儲存在資料庫中，希望取出這些 data_id 對應的API資料，其中 API API每次只能取出一個 data_id 對應的資料。

方案：

使用「參數指派」節點將儲存在資料庫中的 data_id 取出並匯出為參數，將這些參數傳遞給「循環容器」。

「循環容器」中拖入「資料同步」節點從 API 取數，每次取數時只使用一個 data_id ，直到所有 data_id 都被使用停止循環。

注：「參數指派」節點中建議設定一個除錯值（預設值），便於下遊節點引用參數後查看效果，除錯值不參與實際運作。

3.1.2 循環限制

循環次數上限。預設128次，使用者可手動調整，上限為10000次，不可為空。

注：若使用的循環次數超過 10000，4.1.10.2 以及之後的版本可以使用 循环容器循环次数无限制插件

3.1.3 循環方式

可選擇遍曆循環、條件循環。

1）遍曆循環參數（陣列）中的元素，遍曆結束則循環結束，循環次數與遍曆物件的元素個數一緻。循環次數由欄位值的個數決定。

• 當遍曆值不為空時，傳回布爾值：true，繼續下一次循環。

• 當遍曆值為空時，傳回布爾值：false，結束容器內的循環。

2）條件循環說明請參見本文 3.2 節內容。

3.1.4 遍曆物件

選擇上遊設定的參數，選擇的參數逐行獲取值，未選擇的參數直接獲取值。

當選擇遍曆循環（for-each）時，必須選擇遍曆物件。

當選擇條件循環（do-while）時，遍曆物件可選。

「遍曆物件」設定為循環容器上遊的參數指派，可以選擇單個和多個，但限制只能選擇循環容器上遊的參數。

3.1.5 執行條件

當選擇遍曆循環（for-each）時，無需選擇執行條件。

3.1.6 故障容許度機制

若使用者希望循環容器內能忽略節點的報錯繼續執行循環，而不是停止下一次循環。例如：取出数据为空导致循环终止解决方案中出現的循環取數時，一次獲取的批量資料可能為空，則希望此時還能繼續執行循環取數，則可使用該功能。

• 預設不勾選：當一次循環中有節點執行報錯，不再進行下一次循環。

• 當勾選時：循環容器中有一個節點報錯時，繼續執行循環（在日誌中需要匯出單次循環中的錯誤資訊），此循環容器的執行結果還是執行失敗。

3.2 條件循環（Do-While Loop）

3.2.1 使用說明

條件循環需要同時滿足以下兩個條件：

• 具備每次循環取數的參數：使用參數指派、參數匯出、內建參數等，設定每次循環取數需要用到的參數。參數可以來自容器外，也可以來自容器內。

• 具備循環結束條件：根據實際場景設定循環結束條件，當不符合循環條件時，結束循環。參數可以來自容器外，也可以來自容器內。

為便於理解，下面以一個範例說明遍曆循環。詳情參見文檔：分页取数-按页数取数 

場景：

API文檔中包含的參數如下圖所示，其中 pageIndex 表示資料頁數；pageSize 表示在每一頁的資料條數：

某企業現在需要將某業務工單資料全部取出以供業務分析使用。

方案說明：

3.2.2 循環方式

循環限制、遍曆物件、故障容許度機制詳細說明請參見本文 3.1 節內容。

條件循環：

先執行一次迴路本體，再判斷條件。設定循環執行和結束的條件，循環次數由條件決定。

• 當條件判斷傳回布爾值：true，繼續下一次循環；

• 當條件判斷傳回布爾值：false，結束容器內的循環。

注：4.1.1 及之後版本，産品內條件判斷邏輯進行了統一，每個運算子的說明可參見：條件判斷邏輯說明

3.2.3 執行條件

1）循環方式為「條件循環」時，必須配置「執行條件」。

2）需要設定結束條件，條件中的參數可以是循環容器外的參數，也可以是循環容器內的參數，也可以是自訂參數。

4.2.19.1 及之後版本，規範了同名參數的使用邏輯；例如下圖，紅色背景的節點都匯出參數且同名，執行條件中若想使用參數：

• 並行節點的同名參數不可用，即序號1和序號2處的參數不能用 。

• 參數同名優先：容器內指派參數>上游指派參數（容器外上游節點匯出的參數）>任務靜態參數>全局參數>內建參數，存在高優先的同名參數時，低優先的同名參數不能選中，由於 4 的優先大於 3，所以 3 匯出的參數不能用

• 遵循節點先後遠端優先，1的參數優先大於4 ，所以 4 的參數也不能用 。

3）循環容器的條件循環是 do-while 循環，特點是第一次執行循環時，不論執行條件是否滿足，都會執行；第一次之後的循環需要滿足執行條件 。

例如執行條件設定為${loopTimes}<1，第一次循環時，由於${loopTimes}初始值為1，雖然不滿足執行條件，但依然會執行，第一次執行結束後終止循環 。

3.3 並行遍歷（For-Each Parallel）

4.2.19.1 及之後版本新增該方式 。

應用場景：

API 取數場景中，有時需要遍歷 id 或者其他參數去查詢每個參數值對應的資料並落庫，使用者發現任務運作較慢，希望循環容器支援併發 。

功能簡介：

假設使用參數 a、b、c、d遍歷取數，該方式下，可同時使用參數 a、參數b、參數 c 進行取數，多個執行緒同時跑，各自獨立，彼此不等待 。

功能說明：

設定項	說明
最大併發數	可輸入 2-10 的正整數 將根據指定併發數量並行運作多次循環，正常運作情況下相互之間不影響，預設情況下，一次遍歷出錯時，立即終止未開始的遍歷  注：當並行寫入同一張表時，主鍵更新的寫入方式可能會導致鎖表 点击展开更多
其餘設定項	請參見本文 3.1 節內容

運作邏輯與日誌說明：

4.1 內建參數

詳情參見：${loopTimes}

4.2 容器內參數規則

4.2.1 參數使用

容器內可以使用「參數指派」，「參數指派」匯出的值形成容器內的參數：

1）容器內參數僅可在容器內使用，不可向容器外傳遞；

2）容器內參數優先最高，優先大於其他所有容器外參數和內建參數。

3）對「參數指派」中單個參數匯出的欄位值個數進行限制，限制最多不能超過 10000 個。注：若使用的參數超過 10000，4.1.10.2以及之後的版本可以使用循環容器循環次數無限制插件 。

4.1.0 之前版本，容器內使用正文型參數時，需要手動新增單引號。

4.2.2 參數效果預覽

應用場景：

若參數除錯值處填寫了多個參數，循環容器內的節點使用參數預覽時，多個參數值會被識別成一個值，無法正常預覽資料，需要去前面節點修改除錯值。

功能簡介：

4.2.4.3 及之後的版本，若參數除錯值處填寫了多個參數，循環容器內的節點使用參數預覽時，可以模擬循環執行情況。如下圖所示：

注 1：最多模擬 5 次循環執行結果；每次循環執行使用的參數為填入的參數除錯值。

注 2：4.2.10.1 及之後版本，不支援模擬循環執行情況。

4.2.3 升級相容說明

4.1.0 之前版本中，「循環容器」節點中引用參數時，會自動去掉參數的單引號，所以「循環容器」節點在使用正文型（分隔符選擇正文型分隔）參數需要手動加上單引號。

4.1.0 及之後版本，「循環容器」節點中引用參數時，不再自動去掉參數的單引號，所以「循環容器」節點在使用正文型（開啟閉包符）參數時無需手動加上單引號。

「參數指派節點+循環容器」場景中，若「參數指派」節點匯出參數的分隔符選擇「正文型分隔」，在循環容器內使用參數時加了單引號，升級到 4.1.0 及之後版本時，需要手動去掉單引號。

允許循環容器內的節點不必須透過遠端建立聯系，原因是循環容器內隱藏的有一個start和end節點。

在建立完成循環容器節點時，同時也自動建立完成了三個內部節點：start節點（循環開始節點）、循環任務節點、end節點（循環結束判斷節點），透過內部節點組織成內部節點流程，實現任務的循環運作。

1）若定時任務中包含「循環容器」節點，運作任務後，「日誌」Tab 下會展示最近 5 次循環資訊。如下圖所示：

日誌的詳細程度可在「任務控制-任務屬性」中設定，若設定為 INFO 的日誌級別，可查看每次循環使用到的參數值。

2）「統計」Tab 下可以查看「資料同步」節點和「資料轉換」節點的讀寫資訊。

若「循環容器」節點中包含「資料同步」節點、「資料轉換」節點，可點選「循環容器」查看具體讀寫資訊：顯示所有成功的讀取、寫入記錄。

3）若「循環容器」中勾選「節點報錯時，繼續執行循環」按鈕，且循環次數較多，若想查看失敗原因，建議到 fanruan.log 中進行查看（不支援查看循環失敗次數）。

使用循環容器獲取 API API資料，若 API 需要的 token 不斷變化，為保證呼叫 API API時 token 不失效，可使用參數指派節點將 token 匯出為參數，呼叫 API 時直接使用參數。