uip Maestro 流实例

“uip Maestro 流程实例”的语法和选项，用于检查和引导单个 Flow 流程实例。

uip maestro flow instance检查和控制单个流程实例— 已发布的 Flow 流程的一次执行。即使侧边栏条目显示为instances ，命令名称也为单数 ( instance )。

所有子命令都需要uip login并遵循全局选项。退出代码遵循标准合同。

此页面与uip maestro bpmn instance共享其实现 — 相同的缺陷和修复程序适用于这两个页面。

大纲

uip maestro flow instance list                <instance-id>             -f <folder-key> [-l <limit>] [--next-page <cursor>] [--process-key <k>] [--package-id <id>] [--error-code <code>] [--status <status>]... [--from-date <iso-8601>] [--to-date <iso-8601>]
uip maestro flow instance get                 <instance-id>             -f <folder-key>
uip maestro flow instance pause               <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance resume              <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance cancel              <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance retry               <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance migrate             <instance-id> <new-version> -f <folder-key> [--comment <text>]
uip maestro flow instance variables           <instance-id>             -f <folder-key> [--parent-element-id <id>]
uip maestro flow instance variables-set       <instance-id>             -f <folder-key> --inputs <json|@file>
uip maestro flow instance variables-all       <instance-id>             -f <folder-key>
uip maestro flow instance global-variables    <instance-id>             -f <folder-key>
uip maestro flow instance incidents           <instance-id>             -f <folder-key>
uip maestro flow instance asset               <instance-id>             -f <folder-key>
uip maestro flow instance cursors             <instance-id>             -f <folder-key>
uip maestro flow instance goto                <instance-id> <transitions> -f <folder-key>
uip maestro flow instance element-executions  <instance-id>             -f <folder-key>
uip maestro flow instance element cancel      <instance-id> <element-id> -f <folder-key> [--comment <text>]
uip maestro flow instance element retry       <instance-id> <element-id> -f <folder-key> [--comment <text>]
uip maestro flow instance message send        -f <folder-key> [--inputs <json|@file>]

每个子命令都需要-f, --folder-key <key> 。

常见选项

• -f, --folder-key <key> （必填） — 文件夹密钥 (GUID)。
• --comment <text> （仅限操作命令） — 与操作一起记录的可选注释。如果省略，则作为空字符串发送。

子命令

uip Maestro 流实例列表

列出文件夹中定义为 Flow 流程 ( processType=Flow ) 的实例。

选项

选项	默认	描述
-l, --limit <n>	DEFAULT_PAGE_SIZE	要返回的项目数。范围为1-500 — 比此 CLI 的常规 1-10000 约定更严格，因为实例 API 按光标而不是偏移量进行分页。
--next-page <cursor>	—	上一个响应的 Pagination.NextPage 中的光标。此 API 根本不支持 --offset — 非零 --offset 快速失败，并显示错误，告知您要使用 --next-page。
--process-key <k>	—	按流程密钥 (GUID) 筛选。对于点式包标识符，请使用 --package-id。
--package-id <id>	—	按包 ID 筛选。
--error-code <code>	—	按错误代码筛选。
--status <status>	—	按实例状态筛选。可重复(OR 语义)。值：Canceling、Cancelled、Completed、Faulted、Paused、Pausing、Pending、Resuming、Retrying、Running、Upgrading。
--from-date <iso-8601>	—	仅包含在此时间戳当天或之后开始的实例，例如2026-01-01T00:00:00Z。
--to-date <iso-8601>	—	仅包含在此时间戳不高于其开始的实例。

数据形状

Code: "InstanceList" ， Data是流程实例对象数组。

uip Maestro 流实例获取

按 ID 获取单个实例。

数据形状： Code: "InstanceGet" ， Data是流程实例对象。

uip Maestro 流实例暂停

暂停正在运行的实例。数据形状： Code: "InstancePaused" 。

uip Maestro 流实例继续

恢复已暂停的实例。数据形状： Code: "InstanceResumed" 。

uip Maestro 流实例取消

取消正在运行的实例。数据形状： Code: "InstanceCanceled" 。

uip Maestro 流实例重试

重试发生故障的实例。数据形状： Code: "InstanceRetried" 。

uip Maestro 流实例迁移

将实例迁移到其他包版本。

参数： <instance-id> 、 <new-version> （目标包版本）。

数据形状： Code: "InstanceMigrated" 。

uip Maestro 流实例变量

获取实例的变量。

选项： --parent-element-id <id> — 按父元素筛选变量。

数据形状： Code: "InstanceVariables" ， Data包含实例变量有效负载。

uip Maestro 流实例变量集

修补（部分更新）实例的变量。

选项

选项	描述
--inputs <value>	Patch 变量有效负载为 JSON 字符串、@file 路径，或通过标准输入管道传输。

数据形状

Code: "InstanceVariablesSet"。

uip Maestro 流实例变量全部

获取实例的所有变量，包括子流程变量（与 variables 不同，除非传递 --parent-element-id，否则 的范围限定为顶级流程）。

数据形状

Code: "InstanceVariablesAll"。

uip Maestro 流实例全局变量

获取实例的全局变量（在整个流程中共享，不限定于任何元素）。

数据形状

Code: "InstanceGlobalVariables"。

uip Maestro 流实例元素“取消”

取消正在运行的实例中的特定元素，而不是整个实例。

参数

• <instance-id> （必填项）
• <element-id> （必填项）

选项

• --comment <text> — 与操作一起记录的可选注释。

数据形状

Code: "ElementCanceled"。

uip Maestro 流实例元素重试

重试实例中的特定故障元素，而不是重试整个实例。

参数

• <instance-id> （必填项）
• <element-id> （必填项）

选项

• --comment <text> — 与操作一起记录的可选注释。

数据形状

Code: "ElementRetried"。

uip Maestro 流实例消息发送

向侦听此文件夹的工作流订阅发送消息 — 用于将外部事件传递到正在运行的流中（例如，流程正在等待的 Webhook 有效负载）。

选项

选项	描述
-f, --folder-key <key>	（必填）文件夹密钥 (GUID)。
--inputs <value>	消息有效负载为 JSON 字符串、@file 路径，或通过标准输入管道传输。

数据形状

Code: "MessageSent"。

uip Maestro 流实例事件

获取特定实例的事件。

数据形状： Code: "InstanceIncidents" ， Data是事件对象数组。

uip Maestro 流实例资产

获取附加到此实例版本的流程定义（ .flow资产）— 在调试以查看实例运行的确切图表时非常有用。

数据形状： Code: "InstanceAsset" ， Data是流 JSON。

uip Maestro 流程实例光标

获取当前执行光标位置 — 实例暂停的元素。

数据形状： Code: "InstanceCursors" 、 Data列出当前光标位置。

uip Maestro 流实例跳转至

将执行光标从一个元素移动到另一个元素。可用于通过跳过或重试特定节点来恢复发生故障的实例。

参数

• <instance-id> （必填项）
• <transitions> （必填） — 转换的 JSON 数组，每个转换都包含sourceElementId和targetElementId 。

uip maestro flow instance goto c3d4e5f6-… \
  '[{"sourceElementId":"Node_1","targetElementId":"Node_3"}]' \
  --folder-key c3d4e5f6-…

在调用 API 之前，CLI 验证 JSON 解析，并且每个条目都具有两个 ID。

数据形状

Code: "InstanceGoto"。

uip Maestro 流实例元素执行

获取实例每个元素的执行历史记录（运行了哪些内容、何时运行以及结果如何）。

数据形状

Code: "InstanceElementExecutions" ， Data是每个元素的执行历史记录。

示例

# Paginate through instances for a specific process
uip maestro flow instance list --folder-key <k> --process-key "InvoiceFlow.flow.Flow:1.0.0" --limit 50

# Pause, fix, resume
uip maestro flow instance pause   <id> --folder-key <k> --comment "Investigating"
uip maestro flow instance resume  <id> --folder-key <k>

# Skip a faulted node by moving the cursor forward, then retry
uip maestro flow instance cursors <id> --folder-key <k>
uip maestro flow instance goto    <id> '[{"sourceElementId":"A","targetElementId":"C"}]' --folder-key <k>
uip maestro flow instance retry   <id> --folder-key <k>

# Upgrade a long-running instance to a new package version
uip maestro flow instance migrate <id> "1.2.0" --folder-key <k> --comment "Patch release"

另请参阅

• uip maestro flow incident — 读取从特定实例分离的事件
• uip maestro flow job — 实例运行的作业视图
• uip maestro flow process — 启动新实例
• Orchestrator 作业
• 流概述