# Quan sát lượt chạy và khôi phục yêu cầu

> Đường dẫn cơ sở: `/api/rpa/browser/v1`. Trang này giải thích ngữ nghĩa của [bản ghi thực thi nút](/vi/browser-rpa/api/list-run-nodes) (`GET /runs/{runId}/nodes`) và cách dùng [biên nhận yêu cầu](/vi/browser-rpa/api/get-request-receipt) (`GET /requests/{key}`) để khôi phục một yêu cầu ghi sau khi mất kết nối.


## Bản ghi thực thi nút trả về những gì

`GET /runs/{runId}/nodes` trả về **bản ghi hiện tại** của từng lần gọi logic của nút. Đây không phải là nhật ký sự kiện. `items[].id` định danh một lần gọi. Các lần thử lại trong cùng một lần gọi sẽ cập nhật attempts/status/data/error của id đó. Lần lặp tiếp theo của vòng lặp hoặc một lần gọi quy trình con mới sẽ nhận id mới. data/error phản ánh lần thử hiện tại hoặc lần thử cuối cùng; không cung cấp toàn bộ lịch sử các lần thử. Bên gọi cập nhật bộ nhớ đệm của mình theo id và không được gộp bản ghi chỉ dựa trên nodeId.

Một bản ghi được công bố khi lần gọi bắt đầu. Các nút chưa bắt đầu, hoặc bị một điều kiện bỏ qua, không có bản ghi thực thi. Thiếu bản ghi không có nghĩa là thất bại; một lượt chạy missed có thể hoàn toàn không có bản ghi nút nào. Bản ghi được thêm vào cuối theo thứ tự ổn định của lần công bố đầu tiên, và máy chủ lưu thứ tự này ở nội bộ. Việc cập nhật trạng thái không làm thay đổi thứ tự này. Thứ tự không dựa theo startedAt hay nodeId, và không có tham số sắp xếp hay tham số đọc tăng dần nào. Trong thời gian bản ghi được lưu giữ, không có bản ghi riêng lẻ nào bị xóa. Việc dọn dẹp toàn bộ một lượt chạy vẫn tuân theo các quy tắc lưu giữ tài nguyên và quy tắc quyền.

### Lọc và phân trang

| Tham số | Mục đích |
|  --- | --- |
| nodeId | Lấy tất cả bản ghi lần gọi của một nút trong mẫu. Một vòng lặp có thể tạo ra nhiều bản ghi. |
| workflowRevisionId | Giới hạn kết quả trong đúng bản sửa đổi của quy trình gốc hoặc của một quy trình con. Dùng tham số này để phân biệt các nút có cùng ID. |
| invocationPath | Sao chép nguyên trạng items[].invocationPath. Chỉ khớp chính xác. Đây là chuỗi không trong suốt (opaque); không đoán cú pháp của chuỗi này hay tự dựng chuỗi. |
| executionId | Khớp chính xác với items[].id, dùng để truy vấn một lần gọi đã biết. Phản hồi vẫn gọi trường này là id; không có trường executionId riêng. |
| status | Một trạng thái nút duy nhất: running/success/failed/cancelled. Đây không phải là trạng thái lượt chạy. |
| page / pageSize | Giá trị mặc định là 1/20, và pageSize nằm trong khoảng 1–100. Giữ cố định kích thước trang trong mỗi vòng quét. |


Mọi bộ lọc được kết hợp bằng AND. Chuỗi được so khớp chính xác với giá trị gốc và phân biệt chữ hoa chữ thường, không loại bỏ khoảng trắng và không chuẩn hóa Unicode. Chuỗi rỗng, khóa truy vấn lặp lại, nhiều trạng thái nối bằng dấu phẩy, tham số truy vấn không xác định và giá trị enum không hợp lệ đều trả về 400. Để lấy nhiều nút, hãy truy vấn riêng từng nút, hoặc đọc kết quả không có bộ lọc nodeId rồi lọc cục bộ. Bộ lọc hợp lệ nhưng không có kết quả khớp, hoặc số trang vượt quá phạm vi, sẽ trả về 200 với items=[] và total bằng số kết quả khớp hiện tại. Lượt chạy mà bạn không có quyền truy cập, hoặc không tồn tại, được xử lý là 403/404. total là số bản ghi. Đây không phải là số nút của mẫu hay số thứ tự sự kiện.

Ví dụ (chỉ là đường dẫn yêu cầu; không có nghĩa là đã thực hiện lệnh gọi nào):

```http
GET /api/rpa/browser/v1/runs/run_example/nodes?page=1&pageSize=30
GET /api/rpa/browser/v1/runs/run_example/nodes?nodeId=read_url&page=1&pageSize=30
GET /api/rpa/browser/v1/runs/run_example/nodes?status=failed&page=1&pageSize=30
GET /api/rpa/browser/v1/runs/run_example/nodes?executionId=node_execution_example
```

### Thăm dò đúng cách

Ở mỗi vòng, hãy đọc lại tập đã chọn từ page=1 và ghi đè bộ nhớ đệm theo id. Nếu lần đọc đầu tiên có 30 bản ghi gồm 20 success và 10 running, lần đọc thứ hai vẫn bao gồm 30 bản ghi đó, và lúc này chúng có thể là 25 success, 3 failed và 2 running. total vẫn có thể là 30; không nối thêm chúng vào dữ liệu cục bộ thành 60 bản ghi. Không tiếp tục từ "nodeId cuối cùng", "total trước đó" hoặc "trang cuối cùng" để thay cho việc làm mới trạng thái. Tất cả các cách này đều bỏ sót cập nhật của các bản ghi cũ hơn.

Trong khi lượt chạy đang diễn ra, phân trang không đảm bảo một bản chụp nhanh nhất quán giữa các trang. Nếu một bản ghi biến mất khỏi status=running, điều đó chỉ chứng minh rằng lần đọc này không trả về bản ghi đó; sự thay đổi của tập đã lọc cũng có thể khiến phân trang bỏ qua bản ghi. Hãy đọc lại bản ghi theo executionId, hoặc chờ lần kiểm tra cuối cùng. Không suy ra thành công, thất bại hay đã dừng. Danh sách rỗng cũng không chứng minh rằng lượt chạy đã kết thúc.

Chúng tôi khuyến nghị xác định trạng thái kết thúc bằng [chi tiết lượt chạy](/vi/browser-rpa/api/get-run), sau đó đọc tất cả các trang bản ghi thực thi nút mà không dùng bộ lọc để làm bước kiểm tra cuối cùng. Nếu bạn chỉ quan tâm đến một nút, ít nhất hãy bỏ bộ lọc status, và nêu rõ rằng báo cáo chỉ bao gồm tập con đó. Bản chiếu (projection) cuối cùng của các nút phải được lưu bền trước khi trạng thái kết thúc của lượt chạy được công bố. Sau trạng thái kết thúc, không bản ghi nào có thể vẫn ở trạng thái running. Lần gọi không thể xác nhận đã kết thúc được đánh dấu failed (error.code là OUTCOME_UNKNOWN hoặc RPA_INTERRUPTED), và endedAt/durationMs có thể là null. Bằng chứng về thành công, hủy hoặc dừng không bao giờ bị làm giả. Bản chiếu ở trạng thái kết thúc được giữ ổn định trong thời gian lưu giữ. Các lần kiểm tra trạng thái bên ngoài sau đó không âm thầm viết lại kết quả này.

run.isolation mô tả trạng thái cách ly và ranh giới cho việc dùng lại môi trường. Trường này không chứng minh được một hành động có xảy ra trên trang web hay không, hoặc đã xảy ra bao nhiêu lần. Kết quả chưa biết vẫn là chưa biết và không được tự động chạy lại.

Mọi yêu cầu đọc trang trong mọi vòng đều được tính vào ngân sách yêu cầu dùng chung. Chúng tôi khuyến nghị thăm dò cách nhau ít nhất 3 giây với lượt chạy đang hoạt động và ít nhất 5 giây với lượt chạy đang xếp hàng. Giữ tổng số yêu cầu quan sát và khôi phục ở mức không quá 40 yêu cầu mỗi phút. Khi có nhiều trang, hãy kéo dài chu kỳ của một vòng đầy đủ. Nếu ngân sách không đủ, bạn có thể tạm dừng hoặc bỏ dở lần quét hiện tại, nhưng không được báo cáo một tập mới đọc được một phần là đầy đủ. Bước kiểm tra trạng thái kết thúc phải đọc mọi trang. Nếu giới hạn không cho phép điều đó, hãy nói rõ.

### Kích thước dữ liệu

Yêu cầu cục bộ cũng cần phản hồi có giới hạn kích thước. Theo mặc định, capabilities.limits.nodeDataBytes=65536 và nodePageBytes=8388608. Phản hồi capabilities cho biết giá trị thực tế.

data không bị che. Trường này trả về nguyên trạng giá trị thực tế (chỉ handle của phần tử và frame xuất hiện dưới dạng `{kind,available:false}`). Kích thước byte của data được đo theo JSON UTF-8 dạng gọn (ký tự không thuộc ASCII được xuất nguyên trạng, không dùng escape \u). Nếu data vượt quá giới hạn cho mỗi bản ghi, toàn bộ data được trả về là null kèm dataTruncated=true. JSON không bao giờ bị cắt giữa chừng, và status/error của nút không bị ảnh hưởng. Nếu không tạo ra dữ liệu nào, data là null và dataTruncated=false. Tác nhân AI không được coi kết quả bị lược bỏ là kết quả rỗng hoặc là lượt chạy thất bại. Hiện chưa có endpoint tải xuống nào cho phép vượt qua giới hạn này.

Nếu toàn bộ phản hồi dạng gọn của một trang (bao gồm data, error, artifacts và meta) vượt quá giới hạn, endpoint trả về 413 RPA_LIMIT_EXCEEDED với details là `{limit:"nodePageBytes",maxBytes:<actualLimit>}`. Endpoint không âm thầm trả về ít mục hơn. Bên gọi giảm pageSize và quét lại từ page=1. Nếu pageSize=1 vẫn vượt quá giới hạn, hãy báo cáo giới hạn này và không thử lại vô hạn. Không nhầm lẫn giới hạn phần thân yêu cầu với giới hạn phản hồi.

## ID yêu cầu và ID lượt chạy

[Lấy biên nhận yêu cầu](/vi/browser-rpa/api/get-request-receipt) dùng đường dẫn `GET /requests/{key}`, và operationId của thao tác này là `getRequestReceipt`.

| ID | Bên tạo | Mục đích |
|  --- | --- | --- |
| Idempotency-Key / khóa trong đường dẫn | Công cụ hoặc SDK của bên gọi tạo một UUID trước khi gửi và lưu trữ lâu dài UUID đó. | Định danh một ý định ghi nghiệp vụ và cho phép bạn lấy lại kết quả sau khi mất kết nối. Người dùng thông thường không cần nhập thủ công. |
| meta.requestId | Máy chủ tạo giá trị này cho mỗi yêu cầu HTTP mà máy chủ xử lý. | Khắc phục sự cố và truy vết. Lần thử lại với cùng khóa vẫn nhận một requestId khác, nên bạn không thể dùng giá trị này để lấy lại phản hồi mà bạn chưa nhận được. |
| runId | Máy chủ tạo giá trị này khi đăng ký một lượt chạy. | Truy vấn chi tiết lượt chạy và kết quả thực thi nút. |


Nếu bạn nhận được phản hồi 202 cho POST /runs như bình thường, hãy dùng trực tiếp data.id. Bạn không cần truy vấn biên nhận yêu cầu. Hết thời gian chờ hoặc mất kết nối chỉ có nghĩa là "chưa nhận được kết quả". Không được gọi đó là "tạo thất bại". Hãy truy vấn bằng khóa ban đầu. Với accepted, hãy chờ. committed nghĩa là thao tác ghi nghiệp vụ đã được commit và đang chờ công bố; không đăng ký lại lượt chạy. Với completed kèm operation=startRun, resourceId=result.id=runId, và result là RunSummary **tại thời điểm đăng ký**, không phải kết quả thực thi hiện tại. Sau khi có runId, hãy truy vấn [chi tiết lượt chạy](/vi/browser-rpa/api/get-run) và [bản ghi thực thi nút](/vi/browser-rpa/api/list-run-nodes). failed là một lần thất bại đã được xác nhận rằng yêu cầu không tạo commit nghiệp vụ nào. unknown vẫn là chưa chắc chắn; không tạo khóa mới để chạy lại.

Phản hồi 404 thông thường không chứng minh rằng chưa có gì được tạo. Chỉ RPA_REQUEST_NOT_COMMITTED kèm details.safeToRetrySameKey=true mới cho phép khôi phục bằng khóa ban đầu và yêu cầu ban đầu. Phần thân mới hoặc If-Match mới là một ý định mới, vì vậy trước tiên bạn phải làm rõ kết quả chưa chắc chắn của ý định ban đầu. Việc hết hạn phát lại sau 24 giờ và các quy tắc tombstone tuân theo [ma trận khôi phục](/vi/browser-rpa/api/recovery). Chỉ những ID tài nguyên mà quyền hiện tại cho phép mới có thể được trả về. Yêu cầu xóa ban đầu được khôi phục theo quyền của bản ghi tombstone; yêu cầu đó không bị báo sai là không tồn tại chỉ vì tài nguyên đã bị xóa.

Biên nhận yêu cầu áp dụng cho mọi yêu cầu ghi. Với createTemplate, resourceId là templateId; với startRun, resourceId là runId. Không coi mọi resourceId đều là runId.

Biên nhận và tài nguyên chỉ hiển thị trong phạm vi dữ liệu của tài khoản/nhóm/thành viên ban đầu. Việc chuyển tài khoản, nhóm hoặc thành viên sẽ đưa bạn sang một kho lưu trữ khác, nên việc không tìm thấy biên nhận cũ không chứng minh rằng yêu cầu ban đầu chưa chạy. Việc thay đổi token xác thực không làm thay đổi phạm vi dữ liệu hiện tại. RPA không có cơ chế cấp quyền hay thu hồi quyền riêng cho từng tài nguyên.