Phân trang
Lấy danh sách dài theo từng phần mà không bỏ sót bản ghi: kích thước trang, offset và con trỏ before.
Trên trang này
API trả danh sách dài, chẳng hạn khách hàng hoặc tin nhắn, thành từng trang. Việc lấy trang tiếp theo gọi là phân trang; chương trình không cần tải cả lịch sử trong một lần.
Có hai cách chỉ vị trí tiếp theo: bỏ qua số bản ghi đã đọc (offset) hoặc gửi dấu mốc của bản ghi cuối đã đọc (con trỏ). Tài liệu API cho biết mỗi điểm API dùng cách nào.
Cách 1: offset và X-Total-Count
limit đặt kích thước trang, còn offset là số bản ghi cần bỏ qua. Ví dụ, limit=50&offset=100 lấy tối đa 50 bản ghi sau 100 bản ghi đầu:
curl -H "Authorization: Bearer <TOKEN_CÁ_NHÂN>" \
"https://your-domain/api/bots/BOT_ID/users?limit=50&offset=100"
Tổng số bản ghi nằm trong header câu trả lời X-Total-Count. Sau mỗi trang, tăng offset bằng số bản ghi thực sự nhận được, đến khi đạt X-Total-Count. Nội dung trả về là mảng bản ghi của trang hiện tại.
Giới hạn của offset
offset lớn hơn 100.000 bị từ chối với mã 400 ở các điểm API có hỗ trợ offset. Câu trả lời hướng dẫn thu hẹp bộ lọc hoặc chuyển sang con trỏ. Offset lớn khiến cơ sở dữ liệu phải xử lý nhiều bản ghi bị bỏ qua, nên với danh sách lớn hãy dùng bộ lọc, con trỏ hoặc xuất dữ liệu.
Nếu danh sách dài hơn 100.000 bản ghi, bạn không thể đến cuối bằng offset. Hãy:
- thu hẹp kết quả theo thời gian, kênh hoặc trạng thái nếu điểm API hỗ trợ;
- dùng con trỏ nếu điểm API hỗ trợ cả hai cách, chẳng hạn danh sách thanh toán và bản ghi bộ sưu tập;
- dùng chức năng xuất dữ liệu nếu cần toàn bộ danh sách.
Kích thước tối đa tùy từng điểm API
Không có một giới hạn limit chung: có danh sách cho 200, 500 hoặc 1.000 bản ghi mỗi trang. Xem giới hạn chính xác trong tài liệu điểm API.
Khi limit quá lớn, một số điểm API trả 400 với lỗi như “limit must be at most 500, got 5000”. Những điểm khác âm thầm dùng giá trị mặc định, thường là 100, nên trang nhận được ngắn hơn yêu cầu.
Hãy đếm số bản ghi thực sự nhận được, không dùng limit để tăng offset. Nếu yêu cầu 5.000 nhưng chỉ nhận 100 mà vẫn tăng offset thêm 5.000, bạn sẽ bỏ sót phần lớn dữ liệu mà không thấy lỗi. Cũng đừng chỉ dựa vào trang rỗng để xác định đã hết: đối chiếu cả X-Total-Count và số bản ghi nhận được.
Cách 2: con trỏ before và has_more
Con trỏ dùng cho danh sách xếp theo thời gian, như tin nhắn trong cuộc trò chuyện. Yêu cầu có limit và con trỏ before tùy chọn, là ID hoặc dấu mốc của bản ghi cuối đã nhận:
curl -H "Authorization: Bearer <TOKEN_CÁ_NHÂN>" \
"https://your-domain/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"
Câu trả lời chứa một trang và cờ has_more. Khi cờ là true, yêu cầu trang tiếp theo với before là con trỏ của bản ghi cuối vừa nhận. Khi cờ là false, đó là trang cuối.
Chọn cách nào?
Bạn không tự chọn: mỗi điểm API quy định cách phân trang. Danh sách thông thường hay dùng offset và X-Total-Count; dòng sự kiện theo thời gian thường dùng before và has_more. Hãy kiểm tra tài liệu điểm API.
Tiếp theo
- Bắt đầu nhanh API — các yêu cầu đầu tiên.
- Lỗi — mã trạng thái.
- Giới hạn và kích thước — giới hạn yêu cầu.