API xử lý lô giúp gửi nhiều yêu cầu trong một lần gọi, nhưng không biến chúng thành một giao dịch thành công đồng loạt. Một lô có thể chứa mục đã tạo xong, mục bị từ chối và mục chưa biết kết quả. Nếu người vận hành chỉ nhìn HTTP 200 rồi báo hoàn tất, hoặc gửi lại cả file khi thấy một lỗi, dữ liệu có thể thiếu hoặc bị tạo trùng.
API xử lý lô có hai cấp kết quả
Cấp ngoài trả lời máy chủ có nhận và xử lý phong bì của lô hay không. Cấp trong trả lời từng yêu cầu nghiệp vụ. Hợp đồng API cần quy định cách phân biệt hai cấp này, trường định danh mục, trạng thái, mã lỗi và thông tin có thể gửi lại. Không suy ra tính nguyên tử chỉ từ tên endpoint “batch”.
Microsoft Graph là ví dụ rõ: kết quả từng request được gắn ID và status riêng, thứ tự trả về không nhất thiết giống thứ tự gửi. Quy tắc này không tự động áp dụng cho mọi API, nhưng cho thấy vì sao client phải đọc hợp đồng thay vì nối kết quả theo vị trí trong mảng. Nếu nhà cung cấp không mô tả partial success, đó là câu hỏi cần giải đáp trước tích hợp.
Sổ kết quả phải theo item, không chỉ theo file
| Trường | Ý nghĩa | Cách dùng |
|---|---|---|
| batch_id | Lần gửi phong bì | Tra cứu request chung |
| item_id | Mục nghiệp vụ ổn định | Ghép kết quả không dựa thứ tự |
| attempt_id | Lần thử của mục | Không ghi đè lịch sử lần trước |
| outcome | Thành công / lỗi / chưa rõ | Quyết định phục hồi |
| remote_id | ID đối tượng đã tạo | Kiểm tra tác động thực tế |
Mỗi mục cần giữ khóa nghiệp vụ hoặc cơ chế idempotency đúng hợp đồng. Một attempt mới không có nghĩa được tạo một đơn hàng mới. Với dữ liệu sửa đổi, cần giữ phiên bản hoặc điều kiện tiền đề để không dùng kết quả cũ ghi đè thay đổi mới. Không đưa token hoặc nguyên văn dữ liệu nhạy cảm vào sổ phục hồi chỉ để tiện debug.
Ví dụ giả định: ba yêu cầu trong một lô
Lô B-01 gồm ba cập nhật danh mục. Mục A có ID kết quả và đã đọc lại đúng giá trị; mục B bị từ chối vì mã đơn vị không hợp lệ; mục C thiếu response dù phong bì được nhận. A được khóa trạng thái hoàn tất. B cần sửa dữ liệu rồi tạo attempt tiếp theo. C cần tra cứu trạng thái hoặc đối tượng đích trước khi quyết định gửi lại.
Đây là ba đường xử lý khác nhau. “Gửi lại mục lỗi” chỉ phù hợp khi lỗi đã xác định và API cho phép thử lại. Một mục chưa rõ kết quả không được tự gán thất bại. Nếu API không có cách đối chiếu hoặc khóa chống trùng, cần giữ HOLD và xác nhận với nhà cung cấp, thay vì biến sự thiếu thông tin thành thao tác ghi mới.
Phụ thuộc giữa các mục cần được khai báo
Một lô có thể yêu cầu tạo công ty trước, rồi tạo liên hệ trỏ vào công ty đó. Cần biết API có hỗ trợ phụ thuộc hay không, xử lý tuần tự hay song song và trả trạng thái gì khi bước trước thất bại. Không dùng thứ tự dòng trong file làm cam kết thực thi nếu API không quy định như vậy.
Đối với mục phụ thuộc, bảng phục hồi cần ghi cả prerequisite ID. Sau khi sửa bước trước, không mặc định bước sau sẽ tự chạy lại. Kiểm tra trạng thái từng mục và tạo danh sách thực thi còn thiếu. Khi giới hạn tốc độ áp dụng riêng từng request bên trong batch, gom nhiều mục cũng không có nghĩa được bỏ qua hạn mức.
Tiêu chí nghiệm thu phục hồi
Ca thử đề xuất nên có response đảo thứ tự, một mục lỗi dữ liệu, một mục chưa rõ kết quả và một mục phụ thuộc bị chặn. Kết quả mong đợi là sổ item khớp đúng ID; phần đã thành công không bị thực hiện lại; phần chờ xác minh không tự retry; lỗi được trả lại đúng người sửa. Đây là kế hoạch thử, không phải bài kiểm tra đã chạy.
Trước khi giao phát triển, hãy chuẩn bị một response đã che bí mật và cách tra cứu đối tượng đích. Nếu cần trao đổi với Onter về tích hợp, bảng batch–item–attempt giúp xác định rõ phần cần bổ sung: parser kết quả, màn hình ngoại lệ hay cơ chế đối chiếu. Không cần thay toàn bộ hệ thống khi vấn đề chỉ nằm ở phục hồi từng mục.
Đọ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: API trả 429: đặt ngân sách retry để không làm nghẽn hàng chờ.
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 xử lý lô. 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.
