API tác vụ dài không nên buộc người dùng giữ một kết nối mở cho đến khi xuất xong báo cáo hoặc xử lý hết hồ sơ. Một cách thiết kế là nhận yêu cầu, trả mã công việc rồi cho client đọc trạng thái ở một địa chỉ riêng. Điểm quan trọng không phải chỉ trả HTTP 202, mà là giữ được danh tính và vòng đời của công việc sau khi request ban đầu kết thúc.
Hợp đồng API tác vụ dài phải trả lời gì?
Người gọi cần biết công việc nào đã được tiếp nhận, đọc trạng thái ở đâu và kết quả cuối được lấy bằng cách nào. Mẫu Asynchronous Request-Reply của Azure mô tả phản hồi có Location trỏ đến status endpoint và Retry-After gợi ý khoảng kiểm tra. Đây là một mẫu thiết kế; API đang tích hợp có thể dùng quy ước khác và cần được đọc theo hợp đồng riêng.
Không dùng mã HTTP của lần polling làm toàn bộ trạng thái nghiệp vụ. Status endpoint có thể trả HTTP 200 vì truy vấn trạng thái thành công trong khi công việc vẫn Running hoặc đã Failed. Client cần đọc trường trạng thái được định nghĩa, phân biệt lỗi lấy trạng thái với lỗi của chính công việc.
| Trường | Vai trò | Điều kiện cần rõ |
|---|---|---|
| job_id | Định danh ổn định | Không đổi khi người dùng mở lại trang |
| status | Pending, Running, trạng thái cuối | Chuyển trạng thái nào được phép? |
| status_url | Nơi kiểm tra tiến độ | Ai được đọc? |
| result | Kết quả hoặc địa chỉ kết quả | Hạn lưu và quyền truy cập |
| error | Lý do thất bại có thể xử lý | Không lộ bí mật nội bộ |
Đóng tab không được làm mất công việc
Client nên giữ job ID theo cơ chế phù hợp để mở lại được trạng thái, thay vì tự tạo công việc mới sau mỗi lần refresh. Lưu job ID không có nghĩa được đưa dữ liệu nhạy cảm vào URL hoặc kho lưu trữ thiếu kiểm soát. Server vẫn phải kiểm tra quyền của người đang đọc, kể cả khi họ có đường dẫn status cũ.
Nếu request tạo job bị mất phản hồi, cần đối chiếu bằng khóa yêu cầu hoặc cơ chế idempotency được API hỗ trợ. Không thể giải quyết sự không chắc chắn bằng cách cứ tạo thêm một job. Phân biệt rõ người dùng “xem lại công việc cũ” với “yêu cầu chạy một công việc mới”. Hai thao tác có hệ quả và chi phí khác nhau.
Ví dụ giả định: xuất báo cáo cuối tháng
Người dùng yêu cầu xuất báo cáo, nhận job J-01 rồi đóng trình duyệt. Khi quay lại, màn hình tra cứu J-01 thay vì gửi lại lệnh xuất. Nếu J-01 thành công, người dùng thấy kết quả và thời hạn tải. Nếu thất bại, họ thấy lỗi đủ để xử lý và lựa chọn tạo lần chạy mới có chủ ý. Nếu job đã hết thời gian lưu, màn hình phải nói rõ không còn tra cứu được, không suy ra báo cáo chưa từng được tạo.
Đó là ví dụ về hành vi mong đợi, không phải công cụ đã triển khai. Một thanh tiến độ cũng cần có nguồn: nếu backend không đo được phần trăm thật, nên hiển thị giai đoạn hoặc trạng thái chờ thay vì phần trăm tăng giả. Thời gian ước tính phải được phân biệt với cam kết hoàn tất.
Polling có giới hạn và đường dừng
Đọc quá dày làm tăng tải nhưng không khiến job hoàn tất nhanh hơn. Cần tuân theo hướng dẫn của API, có giới hạn chờ và xử lý lỗi mạng riêng. Khi nhận trạng thái cuối, client dừng polling. Khi quyền bị từ chối, không tiếp tục gọi bằng token cũ vô hạn. Nếu người dùng yêu cầu hủy, phải biết đó là gửi yêu cầu hủy hay đã xác nhận hủy hoàn tất.
Status endpoint nên mô tả thời điểm cập nhật gần nhất để phân biệt công việc đang chạy với công việc không còn tín hiệu. Không tự đổi Running thành Failed chỉ vì giao diện chờ lâu, trừ khi hợp đồng quy định timeout và cơ chế xác nhận tương ứng. Cần có đường cho người vận hành tra cứu job treo mà không lộ nội dung báo cáo cho mọi người.
Kiểm tra trước khi đưa vào sử dụng
Các ca cần chuẩn bị gồm đóng rồi mở tab, mất phản hồi tạo job, job thất bại, kết quả hết hạn và người khác thử mở status URL. Mỗi ca phải có trạng thái mong đợi cùng nguồn bằng chứng. Bài này không tuyên bố các ca đã chạy.
Để trao đổi phạm vi tích hợp với Onter, hãy mang theo hợp đồng tạo job, status response và quy tắc lưu kết quả đã che bí mật. Từ đó có thể xác định phần thiếu nằm ở backend, polling hay màn hình khôi phục công việc, thay vì chỉ tăng timeout của trình duyệt.
Đọc thêm theo vấn đề liên quan: API timeout khi tạo đơn: xác minh kết quả trước khi gửi lại.
Đọc thêm theo vấn đề liên quan: Email API trả 202: phân biệt accepted, delivered và vào inbox.
Trao đổi phạm vi phát triển và tích hợp tại dịch vụ gia công phần mềm Onter. Tài liệu mẫu cần được che thông tin nhạy cảm trước khi chia sẻ.
Nguồn kỹ thuật
Tài liệu chính thức cho chủ đề API tác vụ dài. Quy trình, bảng kiểm và ví dụ trong bài là đề xuất biên tập; chưa phải log triển khai hay chứng nhận sản phẩm.
