UiPath Documentation
maestro
latest
false
Maestro Orchestrate 用户指南
重要 :
新发布内容的本地化可能需要 1-2 周的时间才能完成。

多实例标记

Configure multi-instance markers in Maestro Orchestrate to run a task once per item in a collection, sequentially or in parallel.

概述​

使用标记配置任务，使“列表”变量中的每个元素运行一次，从而创建多次顺序或并行执行。访问“BPMN 入门”章节中的“标记”，获取标记和概念指导。

何时使用多实例标记​

当您有一个项目列表并且需要为每个项目运行一次同一任务时，请使用多实例标记 — 例如：

  • 验证发票 ID 列表中的每个发票
  • 通过为每条记录调用外部 API，丰富一组记录
  • 向列表中的每位收件人发送通知

如果没有标记，您需要使用序列流构建手动循环，这样更难读取和跟踪。多实例标记有助于保持流程图的简洁，并在执行追踪记录中查看每个项目的状况。每个项目的运行情况都会单独显示，并显示各自的状态和输出。

如果注重顺序或每次运行都依赖于上一次运行，请使用“顺序”模式。如果项目相互独立且希望达到更大的吞吐量，请使用“并行”模式。

支持的集合类型​

Maestro Orchestrate treats the following collection types as loopable for multi-instance execution. If your variable is one of these types, you can use it directly in the Items field:

  • System.Collections.Generic.List<T>
  • System.Collections.Generic.IList<T>
  • System.Collections.Generic.IEnumerable<T>
  • System.Collections.IEnumerable
  • System.Data.DataTable
  • Newtonsoft.Json.Linq.JArray
  • collectionDataType以 List为开头的类型
  • collectionDataType以 Array为开头的类型
  • 原始 .NET 数组，例如 int[]、string[]、、bool[]、double[]、decimal[]、 long[]

保持每个项目的工作幂等且持续时间短。如果您需要在所有迭代完成后将结果收集到单个变量，请使用“输出”和“更新变量”部分。

如何添加多实例标记​

重要提示：

在将任务转换为多实例之前，先配置任务的操作。应用标记时，多实例配置会绑定到任务当前的输出。如果当时未选择任何操作，绑定的将是任务的默认输出占位符，而不是操作的实际输出；之后再选择操作不会刷新该绑定。随后，每次迭代都会写入未绑定的输出，并在运行时于汇总变量中生成null条目。如果您已先将任务转换为多实例，请参阅“汇总变量包含 null ”部分，了解取消并重新应用的相关解决方法。

  1. 在画布上选择任务，然后在属性面板中配置其操作。确认“输出”部分反映了您选择的操作，例如，智能体操作会公开一个类型化response输出和一个Error输出。仅在“输出”部分与所选操作匹配后再继续。

  2. 在任务上方的元素工具栏中，选择“迭代”。

  3. 选择“顺序多实例”或“并行多实例”。

    标记将显示在任务形状的底部。

  4. 在“属性”面板中，展开“多实例”。

  5. 在“项目”中，选择您要迭代的列表变量，例如 vars.invoiceList。

    This tells Maestro Orchestrate which collection to process. Without an Items value, the task runs once as a normal task, not once per element. Maestro Orchestrate creates one execution per element in the list.

  6. 可以选择性地展开“错误处理”并启用“失败时重试”，以独立重试各个项目运行。有关配置选项，请参阅“元素级重试”。

结果​

该任务会配置为多实例标记，并在选定列表变量中对每个元素迭代一次。根据所选标记类型，每次迭代会按顺序运行或并行运行。

备注：

只有任务支持多实例。您选择的标记类型（顺序或并行）将决定执行顺序。

引用当前项目​

The Multi-instance section only needs the Items list — that's where you tell Maestro Orchestrate which collection to iterate over. Iterator expressions go in a different place: the Inputs section of the task, where you map the current item to a specific input for each run.

您使用的表达式取决于标记是直接应用于任务，还是任务在从多实例任务调用的子流程中运行。

场景表达式使用位置
直接应用于任务的标记iterator.item在任务的“输入”字段中
任务在从多实例任务调用的子流程中运行iterator[0].item在子流程任务的“输入”字段中
备注：

iterator[0].item 中的 [0] 是指任务在子流程中运行时的最外部的迭代器作用域。在标准单级多实例中，您将始终使用 [0]，没有 iterator[1]。

要传递当前的整个元素，请使用 iterator.item。要传递单个属性，请使用 iterator.item.propertyName。以下是相关示例:

  • iterator.item.invoiceId
  • iterator.item.customer.email
  • { id: iterator.item.id, flags: ["recheck"] }

在任务中引用当前项目​

将多实例标记直接应用于任务时，请在“属性”面板的“输入”部分使用 iterator.item，将当前元素传递到每次运行。

“属性”面板引用​

  • 操作：选择任务的运行方式（Integration Service 操作、智能体操作，如果仅用于建模，则为“无”）。

  • 输入：显示由所选操作定义的参数。对于要填充当前列表项目的每个参数，如需传递整个元素，请将其值设置为 iterator.item，如需传递特定属性，请设设置为 iterator.item.propertyName。

  • 输出：定义每次迭代返回的内容。在任务上配置操作时，操作的输出（通常是response，智能体操作还会额外包含Error）会自动显示在此处，并且每个输出都会通过“值”标签绑定到其来源。要在操作输出之外为每次迭代添加额外值，请选择“+ 新增”，并为其命名。如果此处列出的条目未能反映操作所公开的内容（例如，“值”标签显示的是通用占位符类型，而非操作的实际输出类型），请参阅“汇总变量包含 null”。

  • 更新变量：指定所有迭代完成后由哪个流程变量存储汇总的输出。选择“设置变量值”，然后选择目标变量——例如vars.validationResults。该变量包含一个数组，每次迭代对应一个条目：如果每次迭代返回 String，则为 String 数组；如果每次迭代返回 Object，则为 Object 数组。在“顺序”模式下，各条目遵循输入顺序排序。在“并行”模式下，各项顺序取决于迭代完成的先后顺序，不作保证。

在子流程中引用当前项目​

当任务在从多实例任务调用的子流程中运行时，当前项目无法直接作为 iterator.item 使用。相反，请在子流程任务的“输入”中使用 iterator[0].item，访问从父多实例任务传递的元素。

“属性”面板引用​

  • 操作：配置任务与外部系统、API 或智能体交互的方式。

  • 输入：为任务所需的每个值添加输入。如需传递当前的整个元素，请将值设置为 iterator[0].item，如需传递特定属性，则设置为 iterator[0].item.propertyName。

    示例 — 如果您的列表包含带有 id 字段的对象，请在“属性”面板的“输入”部分添加一个条目：

    • 输入字段名称：currentItemId
    • 值: iterator[0].item.id

    将 .id 替换为列表对象中的实际属性名称。

示例​

示例：验证发票列表​

此示例显示如何配置“服务”任务，以便为列表中的每个发票运行一次任务。

1. 准备一个列表变量​
  1. 打开“数据管理器”。
  2. 创建变量：
    • 名称：invoiceList
    • 类型：对象数组或字符串数组
    • 默认值：["INV-001", "INV-002", "INV-003"]
2. 添加“服务”任务并配置操作​

  1. 将“服务”任务添加到画布，并将其命名为“验证发票”。

  2. 选定任务后，打开“属性”面板中的“操作”部分，然后配置针对每张发票运行的智能体：

    • 操作：选择“开始并等待智能体“。
    • 智能体：选择负责验证发票的智能体。智能体必须已存在于您的租户中。您可以在 Agent Builder 中创建智能体。

  3. 确认“输出”部分反映了该智能体的操作——response输出应以其实际输出类型显示，并与Error并列显示。仅在两者匹配后才继续下一步。

3. 将任务转换为多实例​
  1. 选中任务后，打开元素工具栏并选择“选择标记”→“顺序多实例”。
  2. 在属性面板中，展开“多实例”，并将“项目”设置为vars.invoiceList。
4. 将当前项目映射到输入​

选择操作后，“输入”部分将显示该操作定义的参数，例如 RPA 工作流的输入参数或智能体的参数。

若想用当前列表项填充某个参数，请选择该参数的数值字段，然后输入iterator.item：

  • 如需传递当前的整个元素，请使用 iterator.item，例如字符串 "INV-001"（如果您的列表包含字符串）。
  • 如需传递特定属性，请使用 iterator.item.propertyName，例如 iterator.item.id（如果您的列表包含对象）。

5. 调试流程​
  1. 选择“调试”→“分步调试”。
  2. Maestro Orchestrate runs Validate invoice once per list item.
结果​

执行追踪记录会显示每张发票运行一次，每次都会标记其项目值。

要并行运行所有项目，而非顺序运行，请在步骤 2 中选择“并行多实例”。另请参阅下面的扇出示例。

示例：扇出并收集结果​

场景：您从外部 API 收到发票 ID 列表，需要独立验证每个 ID，然后在下游步骤中使用汇总的结果。

  1. 确保列表变量（例如vars.invoiceIds）由前一步填充，例如调用外部 API 的服务任务。
  2. 添加名为“验证发票”的服务任务，并在常规任务上配置验证单张发票的操作。确认“输出”部分能反映所选操作，response条目应显示操作的实际输出类型。
  3. 选中任务后，选择“选择标记”→“并行多实例”。
  4. 在“多实例”部分，将“项目”设置为vars.invoiceIds。
  5. 在“输入”部分，将iterator.item映射到操作的发票 ID 参数，例如将invoiceId输入设置为iterator.item。
  6. 在“输出”部分，验证操作的response输出是否已列出并绑定到操作的结果。如果您需要为每次迭代额外汇总一个值，请选择“+ 新增”并进行定义。如果列出的输出与您的操作所公开的内容不匹配，则说明标记是在配置操作之前应用的；请参阅“汇总变量包含 null”。
  7. 在“更新变量”部分，选择“设置变量值”，然后选择用于存储汇总结果的变量，例如vars.validationResults。所有迭代完成后，该变量将包含针对每张发票对应的一个条目——如果操作返回 string，则为 string 数组；如果返回 Object，则为 Object 数组。
结果​

多实例任务会根据发票 ID 并行运行一次，所有迭代完成后，汇总结果会收集到配置的变量中。

运行时行为​

  1. Fan-out / fan-in: Maestro Orchestrate creates one activity instance per item and completes the group when all instances finish.
  2. 排序：在“顺序”模式下保证；在“并行”模式下不保证。
  3. 并发：并行模式会并发运行项目，受平台限制和资源可用性的约束。
  4. 失败：每个项目的结果都是独立的。定义下游逻辑，用于处理部分失败（例如，根据阈值继续、重试或停止）。
  5. 可观察性：每次项目运行都在执行追踪记录中单独跟踪，显示每个项目的状态和结果。

故障排除​

汇总变量包含 null​

即使每次迭代都成功运行，“更新变量”生成的汇总变量也会包含null（例如[null, null, null]）。

当任务在选择其操作之前就被转换为多实例时，就会出现这种情况。多实例配置会绑定到任务的默认输出占位符，而非操作的实际输出，之后再选择操作不会刷新该绑定。每次迭代都会写入一个未绑定的输出，汇总器则记录null。

要修复现有任务：

  1. 在元素工具栏中，选择“选择标记”，然后移除多实例标记，将任务转换回常规任务。
  2. 确认已选中操作，并且“输出”部分反映该操作（例如，由该操作产生的类型化输出response，以及智能体操作的Error）。
  3. 使用“选择标记”→“顺序多实例”或“并行多实例”重新应用标记。
  4. 在“输出”部分，验证各条目是否仍与操作的输出相匹配。

为避免在新任务上发生此情况，请始终先配置操作，再将任务转换为多实例。

项目输入将被忽略，任务仅运行一次​

任务仅运行一次，“项目”值会被视为常规输入。

当传递给“项目”的变量不属于受支持的集合类型时，就会发生这种情况。在数据管理器中，根据“受支持的集合类型”检查该变量的类型。如果您将列表定义为纯 string，请将其转换为 string 数组或 object 数组。

输出条目未反映操作的输出​

“输出”部分未显示您预期从所选操作中获取的条目，例如智能体操作应公开response和Error，但仅显示通用response占位符。

输出是在操作选择完成传播之前就捕获的。通过“更改元素”→“常规任务”取消多实例标记，确认“输出”部分反映该操作，然后重新应用标记。

最佳实践​

  1. 在扇出之前验证集合（检查空、null 或过大的列表）。
  2. 保持每个项目的工作时间短且具有容错功能。在适当的情况下添加重试。
  3. 仅聚合您需要的内容。 大型聚合可能会影响性能和可读性。
  4. 明确成功标准。多实例任务完成后，添加“排他网关”，用于评估聚合输出变量，例如，只有成功结果数量达到阈值时，才会路由到下一个步骤。
备注：

并行多实例以 50 个为单位，按批次执行元素。如果每个项目都是大型或复杂的 Object（包括多个键值对或嵌套结构），也应将集合的总大小控制在 50 以内，因为项目大小会影响可以持续并发的数量。

Read Markers (BPMN Primer) for notation and conceptual guidance, and BPMN support for the full list of BPMN elements supported in Maestro Orchestrate.

在子流程或调用活动中工作？ 有关变量作用域、输入/输出映射和“结束事件”变量，请参阅“子流程”。

此页面有帮助吗？

连接

需要帮助? 支持

想要了解详细内容？ UiPath Academy

有问题? UiPath 论坛

保持更新