多实例标记

概述

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

何时使用多实例标记

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

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

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

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

支持的集合类型

Maestro 将以下集合类型视为可循环的多实例执行。如果您的变量是以下类型之一，则可以直接在“项目”字段中使用：

• 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. In the element toolbar above the task, select Iteration.

   

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

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

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

   

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

   这会指示 Maestro 要处理哪个集合。若无“项目”值，任务将作为常规任务运行一次，而非每个元素运行一次。Maestro 为列表中的每个元素创建一次执行。

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

结果

该任务配置为多实例标记，并对所选列表变量中的每个元素迭代一次。每次迭代将按顺序或并行运行，具体取决于所选的标记类型。

备注：

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

引用当前项目

“多实例”部分仅需要“项目”列表，您可以在其中指示 Maestro 要迭代哪个集合。迭代器表达式会进入不同的位置：任务的“输入”部分，每次运行时，都会将当前项目映射到特定输入。

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

场景	表达式	使用位置
直接应用于任务的标记	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. With the task selected, open the element toolbar and select Select markers → Sequential multi-instance.
2. 在属性面板中，展开“多实例”，并将“项目”设置为vars.invoiceList。

4. 将当前项目映射到输入

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

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

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

5. 调试流程

1. 选择“调试”→“分步调试”。
2. Maestro 会为每个列表项目运行一次“验证发票”。

结果

“执行跟踪记录”显示每个发票的一次运行，每个运行都标有其项目值。

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

示例：扇出并收集结果

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

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

结果

多实例任务按发票 ID 并行运行一次，系统会在所有迭代完成后将聚合结果收集到配置的变量中。

运行时行为

1. 扇出/扇入：Maestro 为每个项目创建一个活动实例，并在所有实例完成后完成组。
2. 排序：在“顺序”模式下保证；在“并行”模式下不保证。
3. 并发：并行模式会并发运行项目，受平台限制和资源可用性的约束。
4. 失败：每个项目的结果都是独立的。定义下游逻辑，用于处理部分失败（例如，根据阈值继续、重试或停止）。
5. 可观察性：每次项目运行都在执行追踪记录中单独跟踪，显示每个项目的状态和结果。

故障排除

汇总变量包含 null

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

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

要修复现有任务：

1. In the element toolbar, select Select markers and remove the multi-instance marker to convert the task back to a regular task.
2. 确认已选中操作，并且“输出”部分反映该操作（例如，由该操作产生的类型化输出response，以及智能体操作的Error）。
3. Re-apply the marker with Select markers → Sequential multi-instance or Parallel multi-instance.
4. 在“输出”部分，验证各条目是否仍与操作的输出相匹配。

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

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

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

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

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

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

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

最佳实践

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

备注：

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

阅读“标记（BPMN 入门）”以获取标记和概念指导，阅读“BPMN 支持”以了解 Maestro 中支持的 BPMN 元素完整列表。

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