# API でテンプレートを実行

[クイックスタート](/ja/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 <keyword>` または [ブラウザ Local API](/ja/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 は、実行が登録されたことを示します。実行が完了したという意味ではありません。実行 ID、元のキー、固定されたテンプレートのリビジョンを保持しておいてください。通信のタイムアウトによって実行がキャンセルされることはありません。別の書き込みを送信する前に、[リクエストのリカバリー](/ja/browser-rpa/local-api#%E3%83%AA%E3%82%AB%E3%83%90%E3%83%AA%E3%83%BC)の手順を実施してください。

## 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` です。監視のリクエストはすべて合わせて 1 分あたり 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` をもとにマージします。実行が終了状態になった後は、ステータスで絞り込まずにすべてのページを読み取ります。成果物のエンドポイントはメタデータのみを返します。出力を共有する前に、機密性の高い内容をマスクしてください。

キャンセルは要求にすぎません。実際の終了状態と分離状態を引き続き確認してください。結果が不確かな場合や、環境がまだ隔離されている場合は、自動的に再実行しないでください。詳しくは、[実行の詳細を取得](/ja/browser-rpa/api/get-run)、[ノード実行一覧](/ja/browser-rpa/api/list-run-nodes)、[実行の監視とリクエストのリカバリー](/ja/browser-rpa/api/observation)を参照してください。