1. 概述
1.1 版本说明
| FineDataLink 版本 | 功能变动 |
|---|---|
| 4.0.3.1 | 新增「循环容器」节点，满足多个节点循环执行的场景 |
| 4.0.30 | 「循环容器」外的节点允许拖到容器内；其中有连线连接的节点不能单独拖入容器内，需要整组选中，一起拖入容器内 |
| 4.1.0 | 调整参数在循环容器中的使用逻辑，详见 4.2.2 节 |
| 4.1.1 | 循环容器支持设置容错机制 当循环容器中有节点报错时（例如API循环取数时取出数据为空），支持继续执行循环，详情参见第三章 |
1.2 应用场景
用户使用 API 数据源 取数， API 数据源的参数来自数据库内的一列字段内或者API接口中，但是 API 参数每次只能读取一个参数值，所以需要参数赋值支持将参数值逐行输出，下游节点通过数据同步或者数据转换对参数值进行遍历。
1.3 功能简介
「循环容器」节点可满足循环遍历的场景，且需要与参数赋值节点或者数据转换中的参数输出联合使用，将参数赋值节点或者参数输出作为上游节点，将参数赋值节点或者参数输出的输出结果赋值给循环容器节点后，一次次循环来遍历赋值节点的输出结果。
循环包括两种：
遍历循环：遍历完跳出循环执行。
条件循环：不满足条件时跳出循环执行。
2. 使用限制
若想使用「循环容器」功能，需注册「循环容器」功能点。详情请参见：FineDataLink注册授权
循环容器中的节点必须在创建节点，即在拖入节点至画布界面的时候直接拖入循环容器中，不能直接把循环外的节点拖进去，否则该节点在循环容器中不生效。
参数赋值的参数只能给其下游节点使用，循环容器内也是一样的。
「循环容器」节点内不能再拖入的节点类型：「调用任务」节点和「循环容器」节点。
3. 功能说明
| 维度 | 分类 | 说明 |
|---|---|---|
| 参数赋值 | 上下游依赖 | 参数赋值节点或者参数输出作为上游节点，将参数赋值节点或者参数输出的输出结果赋值给循环容器节点后，一次次循环来遍历赋值节点的输出结果。
|
| 循环限制 | 循环次数上限 | 默认128次，用户可手动调整，上限为10000次，不可为空。 |
| 循环方式 | 遍历循环 （for-each） | 遍历循环参数（数组）中的元素，遍历结束则循环结束，循环次数与遍历对象的元素个数一致。循环次数由字段值的个数决定。
|
条件循环 （do-while） | 先执行一次循环体，再判断条件。设定循环执行和结束的条件，循环次数由条件决定。
注：4.1.1 及之后版本，产品内条件判断逻辑进行了统一，每个运算符的说明可参见：条件判断逻辑说明 | |
| 遍历对象 | 参数赋值 | 选择上游设置的参数，选择的参数逐行获取值，未选择的参数直接获取值 当选择遍历循环（for-each）时，必须选择遍历对象 当选择条件循环（do-while）时，遍历对象可选 「遍历对象」设置的循环容器上游的「参数赋值」，可以选择单个和多个，但限制只能选择循环容器上游的参数。
|
| 执行条件 | 当选择条件循环（do-while）时，执行条件必选 当选择遍历循环（for-each）时，无需选择执行条件 需要设定结束条件，条件中的参数可以是循环容器外的参数，也可以是循环容器内的参数，也可以是自定义参数。
| |
| 容错机制 | 若用户希望循环容器内能忽略节点的报错继续执行循环，而不是停止下一次循环。例如：API循环取数时取出数据为空中出现的循环取数时，一次获取的批量数据可能为空，则希望此时还能继续执行循环取数，则可使用该功能。
|
4. 容器内参数
4.1 内置参数
内置参数 | 生效范围 | 定义 |
|---|---|---|
| ${loopTimes} | 循环容器内部 | 容器内当前循环次数，初次为1，后续每次循环递增加1。 |
详情参见：${loopTimes}
4.2 容器内参数规则
4.2.1 规则说明
容器内可以使用「参数赋值」，「参数赋值」输出的值形成容器内的参数：
容器内参数仅可在容器内使用，不可向容器外传递；
容器内参数优先级最高，优先级大于其他所有容器外参数和内置的参数。
对「参数赋值」中单个参数输出的字段值个数进行限制，限制最多不能超过 10000 个
4.1.0 之前版本，容器内使用文本型参数时，需要手动添加单引号。
4.2.2 升级兼容说明
4.1.0 之前版本中，「循环容器」节点中引用参数时，会自动去掉参数的单引号，所以「循环容器」节点在使用文本型（分隔符选择文本型分隔）参数需要手动加上单引号。
4.1.0 及之后版本，「循环容器」节点中引用参数时，不再自动去掉参数的单引号，所以「循环容器」节点在使用文本型（开启闭包符）参数时无需手动加上单引号。
「参数赋值节点+循环容器」场景中，若「参数赋值」节点输出参数的分隔符选择「文本型分隔」，在循环容器内使用参数时加了单引号，升级到 4.1.0 及之后版本时，需要手动去掉单引号。
5. 节点组成
允许循环容器内的节点不必须通过连线建立联系，原因是循环容器内隐藏的有一个start和end节点。
在创建完成循环容器节点时，同时也自动创建完成了三个内部节点：start节点（循环开始节点）、循环任务节点、end节点（循环结束判断节点），通过内部节点组织成内部节点流程，实现任务的循环运行。
6. 运行日志
场景 | 报错日志 |
|---|---|
容器内无节点，为空。 | 2022-04-27 10:34:00 任务构建失败 异常节点：【循环容器】 容器内容为空 |
选择【遍历循环（foreach）】时未设置循环参数； | 2022-04-27 10:34:00 任务构建失败 异常节点：【循环容器】 遍历对象为空 |
选择【条件循环（do-while）】时未配置结束条件 | 2022-04-27 10:34:00 任务构建失败 异常节点：【循环容器】 结束条件为空 |
| 容器循环执行时，超过了设定的最大循环次数。 | yyyy-mm-dd hh:mm:ss 执行失败【节点名称】 超出循环次数限制 - 请检查结束条件的合理性或调整循环次数限制 |
7. 应用示例
推荐循环容器典型应用场景：循环容器典型示例
使用内置参数${loopTimes}的循环容器场景：API取数-按页数取数
目前「循环容器」节点不支持嵌套循环，替代方案可参见：API取数-慧策接口获取库存全量数据
上一篇：调用循环容器任务
