# Bắt đầu lượt chạy

> operationId: `startRun`


## Yêu cầu

Endpoint này bắt đầu một lượt chạy mẫu. Endpoint chỉ chấp nhận một mẫu đã lưu hoàn chỉnh. Không hỗ trợ bản nháp, nút đơn lẻ hay chế độ tùy ý. Mọi tham số đều dùng {kind:"json",value:…}. Truyền tham số riêng tư dưới dạng chuỗi văn bản thuần, và truyền tham số tệp dưới dạng đường dẫn cục bộ tuyệt đối (một chuỗi cho một tệp, một mảng chuỗi cho nhiều tệp). Xem [ParameterValues](/vi/browser-rpa/api/data-types#parametervalues). Tham số không xác định sẽ bị từ chối. Lượt chạy từ bên ngoài có cùng khả năng như lượt chạy trong ứng dụng, không giới hạn loại nút hay kiểu tham số. Các yêu cầu có cùng khóa được đăng ký tối đa một lần. Điều này không đảm bảo các hành động trên trang web của bên thứ ba chỉ được thực hiện đúng một lần.

- **Điều kiện tiên quyết**: Người dùng đã cho phép lượt chạy. Bạn đã truy vấn môi trường thực tế và vượt qua bước xác thực với purpose=run, và bạn dùng đúng phiên bản mẫu đã lưu.
- **Xác thực truy cập**: Giống như ở các phần khác của Local API; xem [Xác thực](/vi/api-reference/getting-started/authentication). Tài nguyên thuộc phạm vi dữ liệu của tài khoản/nhóm hiện tại.
- **Tác dụng phụ**: Lệnh gọi này đăng ký một lượt chạy với bản chụp nhanh cố định của mẫu và các phụ thuộc của mẫu. Sau đó, lượt chạy có thể khởi động trình duyệt và gây ra tác dụng phụ trên các trang web.
- **Tín hiệu hoàn tất**: 202 kèm Location và runId chỉ có nghĩa là việc đăng ký đã thành công. Để biết kết quả thực thi, hãy đọc chi tiết lượt chạy cho đến khi lượt chạy đạt trạng thái kết thúc.
- **Thử lại**: Để khôi phục cùng ý định, hãy dùng lại khóa ban đầu, phần thân ban đầu (nếu có) và If-Match ban đầu (khi endpoint này yêu cầu). Khi hết thời gian chờ HTTP, trước tiên hãy [kiểm tra biên nhận yêu cầu](/vi/browser-rpa/api/get-request-receipt). Không tạo khóa mới.


### Endpoint

```http
POST /api/rpa/browser/v1/runs
```

Local API: `http://127.0.0.1:<port>/api/rpa/browser/v1/runs`. Dùng cổng được cấu hình trong ứng dụng.

### Header

| Tham số | Kiểu | Bắt buộc | Mô tả và ràng buộc |
|  --- | --- | --- | --- |
| `Authorization` | string | Khi bật xác thực Local API | Xem [Xác thực](/vi/api-reference/getting-started/authentication). |
| `Idempotency-Key` | string | Không | Khuyến nghị. Tạo một UUID cho mỗi ý định ghi mới và giữ nguyên UUID đó khi thử lại sau khi mất kết nối; cùng một khóa không bao giờ được thực thi hai lần. Nếu không có header này thì không có cơ chế chống trùng lặp, nên việc thử lại sau khi hết thời gian chờ có thể thực hiện lại thao tác ghi. Nếu có, giá trị phải là UUID. Định dạng "uuid" |
| `X-RPA-Catalog-Revision` | string | Có | catalogRevision do GET capabilities trả về. |


Kiểu nội dung: `Content-Type: application/json` (bắt buộc).

### Tham số đường dẫn

Không có.

### Tham số truy vấn

Không có.

### Phần thân yêu cầu

| Trường | Kiểu | Bắt buộc | Mô tả và ràng buộc |
|  --- | --- | --- | --- |
| `templateId` | string | Có | ID mẫu đích (ID đám mây của mẫu trong Mẫu tùy chỉnh của ứng dụng, là một chuỗi số). Độ dài tối thiểu 1; độ dài tối đa 128. |
| `version` | integer | Có | Phiên bản mẫu có thể chỉnh sửa hiện tại. Đọc giá trị này từ phản hồi thực tế. Tối thiểu 1. |
| `environmentId` | string | Có | ID của một môi trường thực tế. Lấy ID từ truy vấn môi trường. Độ dài tối thiểu 1; độ dài tối đa 128. |
| `parameters` | [ParameterValues](/vi/browser-rpa/api/data-types#parametervalues) | Có | Ánh xạ từ tên tham số sang {kind:json,value:JSON} (văn bản thuần cho tham số riêng tư, đường dẫn cục bộ tuyệt đối cho tham số tệp; xem ParameterValues). Dùng {} khi không có tham số. |


Mô hình đầy đủ: [StartRun](/vi/browser-rpa/api/data-types#startrun).

### Ví dụ yêu cầu

Đây là ví dụ minh họa trong tài liệu; ví dụ này chưa được gửi tới một ứng dụng đang chạy thực tế. Đặt `RPA_BASE_URL` theo mô tả trong [Quy ước API](/vi/browser-rpa/api/common). Các biến tài nguyên, bản sửa đổi danh mục và ETag lấy từ phản hồi thực tế.

Lưu toàn bộ JSON dưới đây thành `start-run.request.json`. Thay mọi giá trị có định danh chứa `example` bằng giá trị từ phản hồi thực tế. ID nút trong ví dụ tạo mẫu là ID cục bộ trong phạm vi quy trình và có thể giữ nguyên.

```json
{
  "templateId": "template_example",
  "version": 1,
  "environmentId": "environment_example",
  "parameters": {
    "targetUrl": {
      "kind": "json",
      "value": "https://example.com"
    }
  }
}
```

```bash
curl -i -X POST "${RPA_BASE_URL}/runs" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${RPA_REQUEST_KEY}" \
  -H "X-RPA-Catalog-Revision: ${RPA_CATALOG_REVISION}" \
  --data-binary @start-run.request.json
```

## Phản hồi

### 202

202 kèm Location và runId chỉ có nghĩa là việc đăng ký đã thành công. Để biết kết quả thực thi, hãy đọc chi tiết lượt chạy cho đến khi lượt chạy đạt trạng thái kết thúc.

| Header | Mô tả |
|  --- | --- |
| `Location` | URL chi tiết của lượt chạy đã đăng ký. |


Phần thân: `application/json`. Trường `data` ở cấp cao nhất dùng mô hình bên dưới. Về `meta`, xem [Metadata](/vi/browser-rpa/api/data-types#metadata).

| Trường | Kiểu | Bắt buộc | Mô tả và ràng buộc |
|  --- | --- | --- | --- |
| `id` | string | Có | ID duy nhất của tài nguyên hoặc nút. Lấy ID từ phản hồi trước đó; không tự đoán. Độ dài tối thiểu 1; độ dài tối đa 128. |
| `status` | [RunStatus](/vi/browser-rpa/api/data-types#runstatus) | Có | Trạng thái hiện tại, được đối chiếu với enum của mô hình. |
| `template` | object | Có | Toàn bộ phần thân của mẫu đề xuất, hoặc bản tóm tắt mẫu được cố định cho lượt chạy. Đọc trường này theo mô hình chứa nó. |
| `environment` | object | Có | Bản tóm tắt môi trường đích được cố định cho lượt chạy. |
| `createdAt` | integer | Có | Thời điểm tạo, tính bằng mili giây Unix. Tối thiểu 0. |
| `startedAt` | integer hoặc null | Có | Thời điểm bắt đầu. Là null nếu lượt chạy chưa bắt đầu (luôn có trong bản ghi nút). |
| `endedAt` | integer hoặc null | Có | Thời điểm kết thúc. Là null nếu lượt chạy chưa kết thúc. |
| `startAfter` | integer hoặc null | Có | Thời điểm bắt đầu sớm nhất, tính bằng mili giây Unix, khi tác vụ của mẫu được đặt bắt đầu trễ. Trước thời điểm đó, lượt chạy ở trạng thái queued và không chiếm dụng môi trường. Là null khi không có độ trễ hoặc với lượt chạy gỡ lỗi. |
| `hasNodeErrors` | boolean | Có | Cho biết có lỗi nút nào xảy ra hay không. Không chỉ xem trạng thái tổng thể mà bỏ qua trường này. |
| `isolation` | object hoặc null | Có | Trạng thái cách ly của môi trường, hoặc null. Khi trạng thái là quarantined, không thể dùng lại môi trường. |


**Các trường của `template`**

| Trường | Kiểu | Bắt buộc | Mô tả và ràng buộc |
|  --- | --- | --- | --- |
| `template.id` | string | Có | ID duy nhất của tài nguyên hoặc nút. Lấy ID từ phản hồi trước đó; không tự đoán. Độ dài tối thiểu 1; độ dài tối đa 128. |
| `template.title` | string | Có | Tên hiển thị. Khi ghi mẫu, dài 1–100 ký tự sau khi loại bỏ khoảng trắng ở hai đầu. |
| `template.version` | integer | Có | Phiên bản mẫu có thể chỉnh sửa hiện tại. Đọc giá trị này từ phản hồi thực tế. Tối thiểu 1. |
| `template.revisionId` | string | Có | ID bản sửa đổi bất biến. Độ dài tối thiểu 1; độ dài tối đa 128. |


**Các trường của `environment`**

| Trường | Kiểu | Bắt buộc | Mô tả và ràng buộc |
|  --- | --- | --- | --- |
| `environment.id` | string | Có | ID duy nhất của tài nguyên hoặc nút. Lấy ID từ phản hồi trước đó; không tự đoán. Độ dài tối thiểu 1; độ dài tối đa 128. |
| `environment.name` | string | Có | Tên công khai. |


**Các trường của `isolation`**

| Trường | Kiểu | Bắt buộc | Mô tả và ràng buộc |
|  --- | --- | --- | --- |
| `isolation.state` | `quarantined` / `released` | Có | Trạng thái cách ly của môi trường: quarantined hoặc released. |
| `isolation.reason` | string | Có | Lý do không khả dụng, lý do cách ly hoặc lý do cần kiểm tra khi chạy. |
| `isolation.since` | integer | Có | Thời điểm bắt đầu cách ly, tính bằng mili giây Unix. Tối thiểu 0. |
| `isolation.releasedAt` | integer hoặc null | Có | Thời điểm giải phóng. Là null nếu môi trường chưa được giải phóng. |


### Ví dụ phản hồi

Mọi ID, dấu thời gian, giá trị băm và kết quả lượt chạy đều là dữ liệu ví dụ. Các giá trị này không cho thấy ví dụ đã được thực thi.

```json
{
  "data": {
    "id": "run_example",
    "status": "queued",
    "template": {
      "id": "template_example",
      "title": "Read the page URL",
      "version": 1,
      "revisionId": "revision_example_1"
    },
    "environment": {
      "id": "environment_example",
      "name": "Example browser profile"
    },
    "createdAt": 1793318400000,
    "startedAt": null,
    "endedAt": null,
    "startAfter": null,
    "hasNodeErrors": false,
    "isolation": null
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

### Phản hồi lỗi

| HTTP | error.code | Cách xử lý |
|  --- | --- | --- |
| 409 | RPA_TEMPLATE_VERSION_CONFLICT | Trước tiên hãy kiểm tra biên nhận để xác nhận rằng yêu cầu chưa được commit. Sau đó đọc mẫu và quyết định ý định mới. |
| 409 | RPA_ENVIRONMENT_BUSY | Môi trường đang bận hoặc đang bị cách ly, và không thể đưa lượt chạy vào hàng đợi. Hãy truy vấn trạng thái. |
| 409 | RPA_CATALOG_CHANGED | Trước tiên hãy kiểm tra biên nhận. Sau khi xác nhận yêu cầu chưa được commit, hãy làm mới header danh mục. Sau đó bạn có thể khôi phục bằng phần thân/If-Match/khóa ban đầu. |
| 409 | RPA_REQUEST_CONFLICT | Phương thức/đường dẫn/phần thân/If-Match gửi kèm cùng khóa khác với ý định ban đầu. |
| 504 | RPA_REQUEST_TIMEOUT | Lỗi này chỉ có nghĩa là thời gian chờ HTTP đã hết. Trước tiên hãy kiểm tra biên nhận của yêu cầu ban đầu. |


Khi phát lại một thao tác ghi bằng cùng khóa, ETag của phản hồi ban đầu được giữ nguyên (nếu có; ETag này có thể đã cũ). Biên nhận chỉ chứa dữ liệu, không có header phản hồi. Để tiếp tục chỉnh sửa, trước tiên bạn phải gửi một yêu cầu GET. Xem [Quy ước API](/vi/browser-rpa/api/common).

Về các lỗi 400/401/403/404/429/5xx thường gặp và các trường mô tả thất bại, xem [Lỗi và khôi phục](/vi/browser-rpa/api/common#l%E1%BB%97i-v%C3%A0-kh%C3%B4i-ph%E1%BB%A5c). Ví dụ phản hồi lỗi (403):

```json
{
  "error": {
    "code": "RPA_PERMISSION_DENIED",
    "message": "The request Host or Origin is not allowed, or the current identity can't access the target environment",
    "retryable": false,
    "issues": [],
    "details": null
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

## Liên quan

[Tham chiếu Local API](/vi/browser-rpa/local-api) · [Quy ước API](/vi/browser-rpa/api/common) · [Mô hình dữ liệu](/vi/browser-rpa/api/data-types) · [Cấu trúc quy trình](/vi/browser-rpa/api/workflow) · [Bắt đầu nhanh](/vi/browser-rpa/quickstart)

Nếu không thể phân giải môi trường trình duyệt, yêu cầu bắt đầu sẽ trả về 422 RPA_ENVIRONMENT_UNAVAILABLE. Trước tiên hãy kiểm tra danh sách môi trường hiện có và trạng thái của ứng dụng, rồi chạy lại bước kiểm tra trước. Cả lần bắt đầu thành công lẫn lần phát lại bằng cùng khóa đều giữ `Location: /api/rpa/browser/v1/runs/<runId>`.