Màn hình báo đồng bộ thành công nhưng danh sách vẫn thiếu khách hàng. Trước khi nghi bộ lọc hoặc thao tác của người dùng, hãy kiểm tra chương trình có đọc hết các trang API hay chỉ nhận trang đầu. HTTP 200 cho biết yêu cầu được xử lý thành công theo endpoint; nó không tự chứng minh danh sách đã đầy đủ.
Chốt “đủ” theo phạm vi nào?
Ghi hệ thống nguồn, tài khoản được phép đọc, bộ lọc, thứ tự sắp xếp và thời điểm bắt đầu. Một tài khoản thiếu quyền không thể dùng để chứng minh toàn bộ dữ liệu của doanh nghiệp đã được lấy. Hai lượt chạy có bộ lọc khác nhau cũng không phải cặp số để đối chiếu trực tiếp.
Nếu nguồn cho phép chốt một snapshot hoặc mốc đọc nhất quán, ghi lại cơ chế đó. Nếu không có, phải nói rõ dữ liệu có thể thay đổi trong lúc phân trang. Cursor không mặc nhiên đồng nghĩa với snapshot; việc có chèn hoặc xóa bản ghi giữa hai lần gọi cần được kiểm tra theo tài liệu của nhà cung cấp.
Sổ lượt đọc giúp tìm đúng trang bị bỏ
| Trường ghi nhận | Mục đích |
|---|---|
| Run ID và dấu vân tay bộ lọc | Không trộn hai lượt đọc khác phạm vi |
| Số trang, số bản ghi nhận | Nhìn thấy trang rỗng hoặc lượt bị dừng |
| Khóa duy nhất và tổng khóa riêng biệt | Tách số nhận được khỏi số thực sự khác nhau |
| Trạng thái next và checkpoint | Biết còn trang và có thể tiếp tục từ đâu |
| Mốc đọc, lỗi và người đối chiếu | Giải thích chênh lệch thay vì chỉ ghi “xong” |
Không lưu nguyên URL có token hoặc cursor nhạy cảm vào báo cáo công khai. Checkpoint dùng để chạy lại cần được bảo vệ và gắn cùng bộ lọc; thay bộ lọc thì không tái sử dụng checkpoint cũ một cách tùy tiện.
Ví dụ giả định: 200 dòng chưa chắc là 200 khách hàng
Một lượt nhận hai trang, mỗi trang 100 dòng. Trang sau lặp lại 8 mã khách hàng đã thấy. Kết quả là 200 dòng nhận, nhưng chỉ 192 khóa riêng biệt. Không sửa báo cáo thành “đã đồng bộ 200 khách hàng”. Giữ cả hai số, xác định nguyên nhân lặp và tiếp tục theo cơ chế next của endpoint.
Với GitHub REST, tài liệu hướng dẫn dùng Link header khi endpoint phân trang. API khác có thể dùng trường next, cursor hoặc offset trong body. Không tự tăng số trang chỉ vì một API trước đây hoạt động như vậy, và cũng không kết luận “hết dữ liệu” chỉ vì trang có ít dòng hơn page size nếu hợp đồng API quy định cách khác.
Năm ca nên kiểm tra trước khi bàn giao
- Danh sách nhiều hơn một trang: các khóa cuối cùng vẫn có mặt.
- Trang kế tiếp lỗi: lượt chạy không ghi hoàn tất giả.
- Chạy tiếp từ checkpoint: không cộng đúp số lượng hoặc tác dụng ghi.
- Nguồn thay đổi giữa lượt: báo giới hạn nhất quán, không hứa tuyệt đối.
- Không còn next: lưu bằng chứng kết thúc theo đúng hợp đồng endpoint.
Sổ này chỉ kiểm tra việc liệt kê đầy đủ trong phạm vi đã chốt. Nó không thay thế đối chiếu tiền, quyền truy cập hay kiểm tra tác dụng của dữ liệu ghi sang hệ thống đích.
Khi cần rà lại luồng kết nối
Chuẩn bị endpoint đã che thông tin nhạy cảm, bộ lọc, một run thiếu dữ liệu và danh sách khóa kỳ vọng. Có thể dùng các bằng chứng đó khi trao đổi phạm vi gia công phần mềm. Nếu vấn đề nằm ở sự kiện cập nhật đến sai thứ tự, xem riêng cách phân biệt event ID và phiên bản dữ liệu; phân trang và thứ tự sự kiện là hai bài toán khác nhau.
Nguồn tham khảo và giới hạn
Tài liệu chính thức 1. Quy trình, bảng và ví dụ trong bài là đề xuất nghiệm thu; ví dụ giả định không phải dự án hoặc kết quả khách hàng của Onter. Phạm vi triển khai cần xác nhận theo hệ thống hiện hữu.
