# Chạy mẫu bằng API

Tiếp tục trong cùng phiên Bash và thư mục làm việc như ở phần [bắt đầu nhanh](/vi/browser-rpa/quickstart). Trước tiên, hãy kiểm tra xem ứng dụng có hỗ trợ các thao tác mà trang này dùng hay không:

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

Chọn một hồ sơ trình duyệt Chromium. ID môi trường là `envId` của hồ sơ. Nếu bạn chỉ biết tên hồ sơ, hãy tìm hồ sơ bằng `ml-cli env find --keyword <keyword>` hoặc `POST /api/env/page` trong [Local API trình duyệt](/vi/api-reference/browser/local-api), và loại bỏ mọi kết quả mơ hồ trước khi chạy. Để xác nhận loại trình duyệt, hãy kiểm tra rằng `POST /api/env/detail` trả về `browserTypeId: 1`. Truyền ID dưới dạng chuỗi. Vị trí trong danh sách và cổng gỡ lỗi không phải là ID hồ sơ.

## 1. Kiểm tra trước phiên bản đã lưu

Dùng cùng ID mẫu, phiên bản, môi trường và tham số cho bước kiểm tra trước và cho lượt chạy. Cung cấp mỗi giá trị tham số dưới dạng `{kind:"json",value:...}`. Tham số riêng tư được gửi dưới dạng văn bản thuần, còn tham số tệp dùng đường dẫn cục bộ tuyệt đối (dùng mảng khi có nhiều tệp). Ví dụ này không có tham số riêng tư. Chỉ tiếp tục khi báo cáo xác thực đầy đủ và hiển thị `valid: true`. Nếu hồ sơ đang bận, hãy chờ đến khi lượt chạy trước giải phóng trạng thái cách ly của nó.

```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. Bắt đầu lượt chạy

```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 nghĩa là lượt chạy đã được đăng ký chứ chưa hoàn tất. Hãy giữ lại ID lượt chạy, khóa ban đầu và bản sửa đổi mẫu đã được cố định. Lỗi hết thời gian chờ ở tầng truyền tải không hủy lượt chạy: hãy dùng [khôi phục yêu cầu](/vi/browser-rpa/local-api#kh%C3%B4i-ph%E1%BB%A5c) trước khi gửi một yêu cầu ghi khác.

## 3. Chờ trạng thái kết thúc

```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
```

Vòng lặp kiểm tra lượt chạy đang hoạt động sau mỗi 3 giây và lượt chạy đang xếp hàng sau mỗi 5 giây, rồi dừng sau 100 lần kiểm tra. Các trạng thái đang hoạt động là `queued`, `preparing`, `running` và `cancel_requested`. Các trạng thái kết thúc là `success`, `failed`, `cancelled`, `stopped` và `missed`. Hãy giữ tổng số yêu cầu quan sát ở mức tối đa 40 yêu cầu mỗi phút, và tuân theo `Retry-After` khi nhận 429 hoặc 503.

## 4. Đọc kết quả

```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
```

Ví dụ này trả về `outputs.result: "https://example.com/"`. Hãy kiểm tra `data.run.hasNodeErrors`, `data.run.isolation.state`, và cả `data.result.outputs` lẫn `data.result.error`: một lượt chạy có thể thành công trong khi một số nút đã thất bại và bị bỏ qua.

Bản ghi thực thi nút được phân trang. Khi lượt chạy còn đang hoạt động, hãy đọc từ trang 1 ở mỗi vòng kiểm tra và gộp kết quả theo `items[].id`. Sau khi lượt chạy đạt trạng thái kết thúc, hãy đọc tất cả các trang mà không lọc theo trạng thái. Endpoint tạo phẩm chỉ trả về siêu dữ liệu. Hãy che thông tin nhạy cảm trong đầu ra trước khi chia sẻ.

Thao tác hủy là một yêu cầu: hãy tiếp tục kiểm tra trạng thái kết thúc thực tế và trạng thái cách ly. Không tự động chạy lại khi kết quả chưa chắc chắn hoặc môi trường vẫn đang bị cách ly. Để biết chi tiết, hãy xem [Lấy chi tiết lượt chạy](/vi/browser-rpa/api/get-run), [Liệt kê lượt thực thi nút](/vi/browser-rpa/api/list-run-nodes) và [Quan sát lượt chạy và khôi phục yêu cầu](/vi/browser-rpa/api/observation).