# 通过 API 运行模板

继续使用[快速开始](/zh/browser-rpa/quickstart)的 Bash 会话和工作目录。先确认客户端支持本页用到的操作：

```bash
jq -e '.data.operations as $ops | ["validateWorkflow","startRun","getRun","listRunNodes","listRunArtifacts"] - $ops | length == 0' capabilities.json
```

选择一个 Chromium 浏览器环境。环境 ID 就是该环境的 `envId`。只知道名称时，用 `ml-cli env find --keyword <关键词>` 或[浏览器 Local API](/zh/api-reference/browser/local-api) 的 `POST /api/env/page` 查询；有多个候选时先确认唯一目标。需要核实内核时，确认 `POST /api/env/detail` 返回 `browserTypeId: 1`。环境 ID 按字符串传递，列表序号和调试端口都不是环境 ID。

## 1. 对已保存的版本做运行预检

预检和启动必须使用相同的模板 ID、版本、环境和参数。参数值统一写成 `{kind:"json",value:...}`；私密参数传明文，文件参数传本机绝对路径，多个文件用数组。本例不使用私密参数。确认校验报告为 `valid: true` 且报告完整后再继续。环境被占用时，等待上一次运行释放隔离。

```bash
: "${RPA_ENVIRONMENT_ID:?Set the actual Chromium profile ID first}"
jq --arg env "$RPA_ENVIRONMENT_ID" '
  .data | {templateId:.id,version,environmentId:$env,
    parameters:{targetUrl:{kind:"json",value:"https://example.com"}}}
' created.json > start-run.json &&
jq '{purpose:"run",source:{kind:"template",templateId,version},
    environmentId,parameters}' start-run.json > validate-run.json &&
rpa_curl "$RPA_BASE_URL/validations" -H 'Content-Type: application/json' --data-binary @validate-run.json -o validation-run.json &&
jq '.data | {valid,issues,truncated,runtimeChecks}' validation-run.json &&
jq -e '.data.valid == true and .data.truncated == false' validation-run.json
```

## 2. 启动运行

```bash
([ -s run.key ] || uuidgen > run.key) &&
rpa_curl "$RPA_BASE_URL/runs" \
  -H 'Content-Type: application/json' \
  -H "X-RPA-Catalog-Revision: $RPA_CATALOG_REVISION" \
  -H "Idempotency-Key: $(cat run.key)" \
  --data-binary @start-run.json -o started.json &&
RPA_RUN_ID="$(jq -er '.data.id' started.json)" &&
jq '.data | {id,status,template}' started.json
```

HTTP 202 只表示运行已登记，不表示已完成。保留 run ID、原始 key 和冻结的模板修订。请求超时不等于运行被取消；再次写入前，先按[请求恢复](/zh/browser-rpa/local-api#%E6%81%A2%E5%A4%8D)查询原请求。

## 3. 等待运行结束

```bash
for attempt in $(seq 1 100); do
  rpa_curl "$RPA_BASE_URL/runs/$RPA_RUN_ID" -o run-detail.json || break
  status="$(jq -r '.data.run.status' run-detail.json)"
  echo "status: $status"
  case "$status" in
    success|failed|cancelled|stopped|missed) break ;;
    queued) sleep 5 ;;
    *) sleep 3 ;;
  esac
done
```

循环对活动中的运行每 3 秒查询一次，对排队中的运行每 5 秒查询一次，最多查询 100 次。活动状态为 `queued`、`preparing`、`running`、`cancel_requested`；终态为 `success`、`failed`、`cancelled`、`stopped`、`missed`。所有观察请求合计不超过 40 次/分钟；遇到 429 或 503 时遵循 `Retry-After`。

## 4. 读取结果

```bash
jq '.data | {status:.run.status,hasNodeErrors:.run.hasNodeErrors,
             isolation:.run.isolation,outputs:.result.outputs,error:.result.error}' run-detail.json &&
rpa_curl "$RPA_BASE_URL/runs/$RPA_RUN_ID/nodes?page=1&pageSize=20" -o run-nodes.json &&
rpa_curl "$RPA_BASE_URL/runs/$RPA_RUN_ID/artifacts" -o run-artifacts.json
```

本例预期返回 `outputs.result: "https://example.com/"`。同时检查 `data.run.hasNodeErrors`、`data.run.isolation.state`，以及 `data.result.outputs` 和 `data.result.error`：即使整体成功，也可能有节点失败后被跳过。

节点执行记录分页返回。运行进行中时，每轮从第 1 页重读，并按 `items[].id` 合并；运行到达终态后，不加 status 过滤读取全部分页。产物接口只返回元数据。分享运行结果前先对敏感内容脱敏。

取消只是提出请求：继续核对真实终态和隔离状态。结果不确定或环境仍处于隔离状态时，不要自动重新运行。详见[获取运行详情](/zh/browser-rpa/api/get-run)、[查询节点执行结果](/zh/browser-rpa/api/list-run-nodes)和[运行观察与请求恢复](/zh/browser-rpa/api/observation)。