Maestro 用户指南

多实例标记

link

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

• 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[]

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

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

   

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

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

   

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

   

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

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

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

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

引用任务中的当前项目​

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

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

  

• 输出：定义每次迭代返回的内容。为任务配置操作后，该操作的输出（通常为response ，对于智能体操作为Error ）将自动显示在此处，并且每个输出通过“值芯片”与其来源绑定。要在每次迭代中除了操作的输出之外添加额外值，请选择“+ 添加新值”并为其命名。如果此处列出的条目未反映您的操作公开的内容（例如，值芯片显示通用占位符类型，而不是操作的实际输出类型），请参阅聚合变量包含 null 值。

• 更新变量：所有迭代完成后，指定哪个流程变量存储聚合输出。选择“设置变量值” ，然后选择目标变量，例如vars.validationResults 。该变量保存一个数组，每次迭代只有一个条目：如果每次迭代返回字符串，则为字符串数组；如果每次迭代返回对象，则为对象数组。在顺序模式下，条目遵循输入的顺序。在并行模式下，顺序与迭代完成的顺序相同，但无法保证顺序。

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

• 操作：配置任务与外部系统、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. 将当前项目映射到输入​

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

5. 调试流程​

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

示例：扇出并收集结果​

1. 确保列表变量（例如vars.invoiceIds ）由上一个步骤填充，例如调用外部 API 的“服务”任务。

2. 添加名为“验证发票”的服务任务，并在常规任务中配置验证单个发票的操作。确认“输出”部分反映了操作 — response条目应显示操作的实际输出类型。

3. 选定任务后，选择“更改元素” → “并行多实例” 。

4. 在“多实例”部分中，将“项目”设置为vars.invoiceIds 。

5. 在“输入”部分中，将iterator.item映射到操作的发票 ID 参数 — 例如，将invoiceId输入设置为iterator.item 。

6. 在“输出”部分中，验证操作的response输出是否已列出并且绑定到操作的结果。如果每次迭代都需要额外的聚合值，请选择“+新增”并进行定义。如果列出的输出与您的操作公开的输出不匹配，则表示在配置操作之前应用了标记；请参阅聚合变量包含空值。

7. 在“更新变量”部分中，选择“设置变量值” ，然后选择用于存储聚合结果的变量，例如vars.validationResults 。所有迭代完成后，每个发票的此变量包含一个条目 — 如果您的操作返回字符串，则为字符串数组；如果您的操作返回对象，则为对象数组。

   

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

聚合变量包含 null 值​

1. 在元素工具栏中，选择“更改元素” ，然后将任务转换回常规任务。
2. 确认已选择操作，并且确认“输出”部分反映了该操作（例如，操作输入response ，加上智能体操作Error ）。
3. 使用“更改元素” → “顺序多实例”或“并行多实例”再次将任务转换为多实例。
4. 在“输出”部分中，验证条目仍与操作的输出匹配。

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

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

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