# Tạo mẫu

> operationId: `createTemplate`


## Yêu cầu

Tạo một mẫu. Cả bốn trường đều bắt buộc: title, description, workflow và dependencies. Yêu cầu không được chứa account, team, owner, active hoặc compiledDefinition. Gửi trực tiếp giá trị mặc định của tham số riêng tư dưới dạng văn bản thuần. Các giá trị này được ghi nguyên trạng vào nội dung mẫu đám mây, giống như cách trình chỉnh sửa của ứng dụng máy tính lưu chúng. Mẫu mới không thể dùng giá trị giữ chỗ `publicState:"retained"`. Giống như GET, phản hồi trả về giá trị mặc định của tham số riêng tư dưới dạng văn bản thuần. Biên nhận idempotency không lưu nội dung mẫu. Khi phát lại với cùng khóa, máy chủ đọc lại mẫu đám mây và trả về nội dung hiện tại của mẫu. Xem [Giá trị mặc định riêng tư](/vi/browser-rpa/api/workflow#3-gi%C3%A1-tr%E1%BB%8B-m%E1%BA%B7c-%C4%91%E1%BB%8Bnh-ri%C3%AAng-t%C6%B0). Các trường như script, đường dẫn cục bộ và thông tin xác thực có thể nhận trực tiếp giá trị literal. Sau khi nhận phản hồi, hãy dùng quy trình do máy chủ trả về. Không tiếp tục coi bản nháp bạn đã gửi là phiên bản cuối cùng. Nút hành động có thể chỉ chứa browserAction và browserUi.inputs. Máy chủ bổ sung các trường còn thiếu gồm title, inputs, inputsValues, browserUi.bindings và browserUi.exception giống như trình chỉnh sửa của ứng dụng máy tính, và tạo data.outputs (xem [Các trường do máy chủ bổ sung](/vi/browser-rpa/api/workflow#c%C3%A1c-tr%C6%B0%E1%BB%9Dng-do-m%C3%A1y-ch%E1%BB%A7-b%E1%BB%95-sung)). Quy trình trong phản hồi, và trong các lần đọc GET sau đó, là cấu trúc đầy đủ đã được bổ sung các trường này.

- **Điều kiện tiên quyết**: Bạn đã đọc hợp đồng nút và hoàn tất bước kiểm tra trước với purpose=save. Ngay cả khi không có phụ thuộc, bạn vẫn phải gửi dependencies=[].
- **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ụ**: Tạo một mẫu trong mục "Mẫu tùy chỉnh" của tài khoản hiện tại trong ứng dụng máy tính (mẫu đám mây cá nhân). Mẫu xuất hiện sau khi danh sách trong ứng dụng được làm mới. Quy trình không được chạy.
- **Tín hiệu hoàn tất**: 201 trả về Template đã chuẩn hóa, id, version, revisionId và ETag, nghĩa là việc lưu đã hoàn tất.
- **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/templates
```

Local API: `http://127.0.0.1:<port>/api/rpa/browser/v1/templates`. 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 |
|  --- | --- | --- | --- |
| `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. Độ dài tối thiểu 1; độ dài tối đa 100. |
| `description` | string | Có | Văn bản mô tả. Bắt buộc khi ghi mẫu. Dùng chuỗi rỗng để xóa mô tả. Độ dài tối đa 1000. |
| `workflow` | [Workflow](/vi/browser-rpa/api/data-types#workflow) | Có | Đối tượng quy trình ở định dạng gốc của trình chỉnh sửa. Quy trình chạy theo thứ tự của nodes/blocks. |
| `dependencies` | array<[DependencyPin](/vi/browser-rpa/api/data-types#dependencypin)> | Có | Danh sách phụ thuộc mẫu con. Danh sách phải khớp một-một với các mẫu con được applySubProcess tham chiếu trong quy trình. revisionId là revisionId hiện tại của mẫu con (`remote:<childTemplateId>@<version>`). Nếu không có phụ thuộc, gửi []. Khi chạy, giống như trong ứng dụng máy tính, mỗi lượt chạy lấy một bản chụp nhanh cố định của phiên bản mới nhất của mẫu con tại thời điểm đó. Tối đa 1000 phần tử. |


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

### 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 `create-template.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
{
  "title": "Read the page URL",
  "description": "Visit the given page and return its URL",
  "workflow": {
    "editorVersion": 2,
    "editorParametersVersion": 1,
    "variables": {
      "type": "object",
      "properties": {
        "targetUrl": {
          "type": "string",
          "description": "HTTP(S) URL to visit"
        }
      },
      "required": [
        "targetUrl"
      ]
    },
    "nodes": [
      {
        "id": "start",
        "type": "start"
      },
      {
        "id": "visit",
        "type": "browser_gotoUrl",
        "data": {
          "browserAction": "gotoUrl",
          "browserUi": {
            "inputs": {
              "url": "${targetUrl}",
              "postWaitMs": 500
            }
          }
        }
      },
      {
        "id": "url_result",
        "type": "browser_getUrl",
        "data": {
          "browserAction": "getUrl",
          "browserUi": {
            "inputs": {
              "type": "href"
            }
          }
        }
      },
      {
        "id": "end",
        "type": "end",
        "data": {
          "inputsValues": {
            "status": {
              "type": "constant",
              "content": "success"
            },
            "message": {
              "type": "ref",
              "content": [
                "url_result",
                "data",
                "value"
              ]
            }
          }
        }
      }
    ]
  },
  "dependencies": []
}
```

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

## Phản hồi

### 201

201 trả về Template đã chuẩn hóa, id, version, revisionId và ETag, nghĩa là việc lưu đã hoàn tất.

| Header | Mô tả |
|  --- | --- |
| `ETag` | Định danh phiên bản mạnh của mẫu trong phản hồi này. Gửi nguyên giá trị này trong If-Match cho các thay đổi sau đó. |


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 |
|  --- | --- | --- | --- |
| `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. |
| `description` | string | Có | Văn bản mô tả. Bắt buộc khi ghi mẫu. Dùng chuỗi rỗng để xóa mô tả. |
| `workflow` | [Cấu trúc quy trình](/vi/browser-rpa/api/workflow) / [JSON Schema](/vi/browser-rpa/local-api#h%E1%BB%A3p-%C4%91%E1%BB%93ng-c%E1%BB%A5c-b%E1%BB%99-d%E1%BA%A1ng-m%C3%A1y-%C4%91%E1%BB%8Dc-%C4%91%C6%B0%E1%BB%A3c) | Có | Đối tượng quy trình ở định dạng gốc của trình chỉnh sửa. Quy trình chạy theo thứ tự của nodes/blocks. |
| `dependencies` | array<[DependencyPin](/vi/browser-rpa/api/data-types#dependencypin)> | Có | Danh sách phụ thuộc mẫu con. Danh sách phải khớp một-một với các mẫu con được applySubProcess tham chiếu trong quy trình. revisionId là revisionId hiện tại của mẫu con (`remote:<childTemplateId>@<version>`). Nếu không có phụ thuộc, gửi []. Khi chạy, giống như trong ứng dụng máy tính, mỗi lượt chạy lấy một bản chụp nhanh cố định của phiên bản mới nhất của mẫu con tại thời điểm đó. Tối đa 1000 phần tử. |
| `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. |
| `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. |
| `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. |
| `createdAt` | integer | Có | Thời điểm tạo, tính bằng mili giây Unix. Tối thiểu 0. |
| `updatedAt` | integer | Có | Thời điểm cập nhật gần nhất, tính bằng mili giây Unix. Tối thiểu 0. |
| `warnings` | array<[Issue](/vi/browser-rpa/api/data-types#issue)> | Có | Các vấn đề và hạn chế không cản trở việc lưu. Hãy đánh giá tác động của từng mục. |
| `redactedPaths` | array<string> | Có | Trường tương thích. Luôn là mảng rỗng trong phiên bản hiện tại. Local API không che nội dung mẫu. |


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

Quy trình trong phản hồi là cấu trúc đầy đủ sau khi máy chủ bổ sung các trường còn thiếu. Nút hành động có title, inputs, inputsValues, outputs và browserUi.bindings/exception đầy đủ. Các trường exception bạn không đặt sẽ nhận giá trị mặc định của trình chỉnh sửa. Khi không đặt timeout, giá trị là 30000 với nút hành động và 0 (không giới hạn thời gian) với nút điều khiển. Các trường bạn đặt tường minh được giữ nguyên.

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": {
    "title": "Read the page URL",
    "description": "Visit the given page and return its URL",
    "workflow": {
      "editorVersion": 2,
      "editorParametersVersion": 1,
      "variables": {
        "type": "object",
        "properties": {
          "targetUrl": {
            "type": "string",
            "description": "HTTP(S) URL to visit"
          }
        },
        "required": [
          "targetUrl"
        ]
      },
      "nodes": [
        {
          "id": "start",
          "type": "start"
        },
        {
          "id": "visit",
          "type": "browser_gotoUrl",
          "data": {
            "browserAction": "gotoUrl",
            "browserUi": {
              "inputs": {
                "url": "${targetUrl}",
                "postWaitMs": 500
              },
              "bindings": {},
              "exception": {
                "policy": "interrupt",
                "timeout": 30000,
                "retry": false,
                "retryTimes": 1,
                "retryInterval": 2,
                "screenshot": true
              }
            },
            "title": "Visit website",
            "inputs": {
              "type": "object",
              "properties": {}
            },
            "inputsValues": {},
            "outputs": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "description": "Execution status"
                },
                "startedAt": {
                  "type": "string",
                  "description": "Start time"
                },
                "endedAt": {
                  "type": "string",
                  "description": "End time"
                },
                "durationMs": {
                  "type": "number",
                  "description": "Duration (ms)"
                },
                "matchedIndex": {
                  "type": "number",
                  "description": "Match index"
                },
                "error": {
                  "type": "object",
                  "description": "Error message",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "data": {
                  "type": "object",
                  "description": "Result",
                  "properties": {
                    "tabId": {
                      "type": "string",
                      "description": "Tab ID"
                    },
                    "httpStatus": {
                      "type": "number",
                      "description": "HTTP status code"
                    },
                    "url": {
                      "type": "string",
                      "description": "URL"
                    },
                    "finalUrl": {
                      "type": "string",
                      "description": "Final URL"
                    },
                    "title": {
                      "type": "string",
                      "description": "Page title"
                    },
                    "isRedirected": {
                      "type": "boolean",
                      "description": "Redirected"
                    }
                  }
                }
              }
            }
          }
        },
        {
          "id": "url_result",
          "type": "browser_getUrl",
          "data": {
            "browserAction": "getUrl",
            "browserUi": {
              "inputs": {
                "type": "href"
              },
              "bindings": {},
              "exception": {
                "policy": "interrupt",
                "timeout": 30000,
                "retry": false,
                "retryTimes": 1,
                "retryInterval": 2,
                "screenshot": true
              }
            },
            "title": "Get URL",
            "inputs": {
              "type": "object",
              "properties": {}
            },
            "inputsValues": {},
            "outputs": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "description": "Execution status"
                },
                "startedAt": {
                  "type": "string",
                  "description": "Start time"
                },
                "endedAt": {
                  "type": "string",
                  "description": "End time"
                },
                "durationMs": {
                  "type": "number",
                  "description": "Duration (ms)"
                },
                "matchedIndex": {
                  "type": "number",
                  "description": "Match index"
                },
                "error": {
                  "type": "object",
                  "description": "Error message",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "data": {
                  "type": "object",
                  "description": "Result",
                  "properties": {
                    "url": {
                      "type": "string",
                      "description": "URL"
                    },
                    "origin": {
                      "type": "string",
                      "description": "Origin"
                    },
                    "pathname": {
                      "type": "string",
                      "description": "Path"
                    },
                    "query": {
                      "type": "object",
                      "properties": {},
                      "description": "Query parameters"
                    }
                  }
                }
              }
            }
          }
        },
        {
          "id": "end",
          "type": "end",
          "data": {
            "inputsValues": {
              "status": {
                "type": "constant",
                "content": "success"
              },
              "message": {
                "type": "ref",
                "content": [
                  "url_result",
                  "data",
                  "value"
                ]
              }
            }
          }
        }
      ]
    },
    "dependencies": [],
    "id": "template_example",
    "version": 1,
    "revisionId": "revision_example_1",
    "createdAt": 1793318400000,
    "updatedAt": 1793318400000,
    "warnings": [],
    "redactedPaths": []
  },
  "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_CATALOG_CHANGED | Trước tiên hãy kiểm tra biên nhận. Sau khi xác nhận thao tác ghi 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 khóa này 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. |
| 422 | RPA_VALIDATION_FAILED | Dùng issues.path để sửa toàn bộ quy trình. |


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. Trước khi tiếp tục chỉnh sửa, bạn phải GET mẫu. 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)