# Thay thế mẫu

> operationId: `replaceTemplate`


## Yêu cầu

Thay thế toàn bộ mẫu. Đây không phải là PATCH: các trường bắt buộc bị thiếu sẽ không được tự động giữ lại, và các mảng được thay thế toàn bộ. Siêu dữ liệu hiển thị hợp lệ được giữ nguyên. Với giá trị mặc định riêng tư, hãy gửi văn bản thuần để ghi đè, hoặc gửi `publicState:"retained"` trên cùng trường của cùng mẫu để giữ lại. Bỏ qua defaultValue hoặc đặt enabled=false sẽ xóa giá trị này. Để biết chi tiết, 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). 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. Lần phát lại với cùng khóa sẽ đọ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). Nút hành động có thể chỉ khai báo browserAction và browserUi.inputs. Máy chủ bổ sung các trường title, inputs, inputsValues, browserUi.bindings và browserUi.exception còn thiếu giống như trình chỉnh sửa của ứng dụng, 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.

- **Điều kiện tiên quyết**: Bạn đã đọc toàn bộ mẫu hiện tại và ETag của mẫu, và bản đề xuất vượt qua bước xác thực để lưu. Xác thực inline nên kèm source.base.
- **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ụ**: Thay thế nguyên tử toàn bộ mẫu và tạo một phiên bản mới cùng một bản sửa đổi mới. Mẫu không được chạy.
- **Tín hiệu hoàn tất**: 200 trả về Template mới và ETag mới, nghĩa là toàn bộ nội dung cập nhật đã được lưu.
- **Thử lại**: Khôi phục cùng ý định bằng khóa ban đầu, phần thân ban đầu (nếu có) và If-Match ban đầu (nếu endpoint này yêu cầu). Khi hết thời gian chờ HTTP, trước tiên hãy [lấy 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
PUT /api/rpa/browser/v1/templates/{templateId}
```

Local API: `http://127.0.0.1:<port>/api/rpa/browser/v1/templates/{templateId}`. 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ề. |
| `If-Match` | string | Có | ETag chính xác từ phản hồi mẫu. Ký tự đại diện và nhiều giá trị đều bị từ chối. |


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

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

| Tham số | Kiểu | Bắt buộc | Mô tả và ràng buộc |
|  --- | --- | --- | --- |
| `templateId` | string | Có | ID của mẫu đích: ID đám mây của mẫu trong mục "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. |


### 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; chuỗi rỗng sẽ 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. Việc thực thi tuân theo thứ tự của nodes/blocks. |
| `dependencies` | array<[DependencyPin](/vi/browser-rpa/api/data-types#dependencypin)> | Có | Các phụ thuộc mẫu con. Các phụ thuộc này phải khớp một-một với các mẫu con mà 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ỗi lượt chạy cố định một bản chụp nhanh của các mẫu con mới nhất 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 `replace-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": 0
            }
          }
        }
      },
      {
        "id": "wait_before_read",
        "type": "browser_waitTime",
        "data": {
          "browserAction": "waitTime",
          "browserUi": {
            "inputs": {
              "timeoutType": "fixed",
              "timeout": 2000
            }
          }
        }
      },
      {
        "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 PUT "${RPA_BASE_URL}/templates/${RPA_TEMPLATE_ID}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${RPA_REQUEST_KEY}" \
  -H "X-RPA-Catalog-Revision: ${RPA_CATALOG_REVISION}" \
  -H "If-Match: ${RPA_ETAG}" \
  --data-binary @replace-template.request.json
```

## Phản hồi

### 200

200 trả về Template mới và ETag mới, nghĩa là toàn bộ nội dung cập nhật đã được lưu.

| 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 làm If-Match trong các lần sửa đổ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; chuỗi rỗng sẽ 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. Việc thực thi tuân theo thứ tự của nodes/blocks. |
| `dependencies` | array<[DependencyPin](/vi/browser-rpa/api/data-types#dependencypin)> | Có | Các phụ thuộc mẫu con. Các phụ thuộc này phải khớp một-một với các mẫu con mà 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ỗi lượt chạy cố định một bản chụp nhanh của các mẫu con mới nhất 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 ghi sẽ nhận giá trị mặc định của trình chỉnh sửa; nếu không ghi timeout, giá trị là 30000 với nút hành động và 0, nghĩa là 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": 0
              },
              "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": "wait_before_read",
          "type": "browser_waitTime",
          "data": {
            "browserAction": "waitTime",
            "browserUi": {
              "inputs": {
                "timeoutType": "fixed",
                "timeout": 2000
              },
              "bindings": {},
              "exception": {
                "policy": "interrupt",
                "timeout": 30000,
                "retry": false,
                "retryTimes": 1,
                "retryInterval": 2,
                "screenshot": true
              }
            },
            "title": "Wait",
            "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": {
                    "waitedMs": {
                      "type": "number",
                      "description": "Actual wait duration"
                    }
                  }
                }
              }
            }
          }
        },
        {
          "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": 2,
    "revisionId": "revision_example_2",
    "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ý |
|  --- | --- | --- |
| 428 | RPA_PRECONDITION_REQUIRED | Thiếu If-Match. Hãy đọc mẫu trước. |
| 412 | RPA_VERSION_CONFLICT | Trước tiên hãy kiểm tra biên nhận ban đầu. Sau khi xác nhận thao tác ghi chưa được commit, hãy đọc lại và hợp nhất, rồi dùng khóa mới cho ý định đã sửa đổi. |
| 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. 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. |
| 422 | RPA_VALIDATION_FAILED | Sửa toàn bộ quy trình theo chỉ dẫn của issues.path. |


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 hãy gửi một yêu cầu GET mới; 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)