Skip to main content
Mọi endpoint danh sách /v1 đều trả về cùng một envelope và phân trang theo cùng một cách: dựa trên token, chỉ tiến về phía trước.

List envelope

string
Luôn là "list".
array
Trang tài nguyên, theo một thứ tự ổn định và xác định.
string | null
Truyền giá trị này làm page_token trong yêu cầu tiếp theo để lấy trang kế tiếp. Giá trị là null khi không còn kết quả nào nữa.
boolean
Cho biết còn kết quả nào ngoài trang này hay không.

Tham số yêu cầu

integer
mặc định:"25"
Kích thước trang. Một số nguyên từ 1 đến 500. Các giá trị nằm ngoài phạm vi này sẽ trả về 400 với mã invalid_request.
string
next_page_token từ phản hồi trước đó. Bỏ qua tham số này đối với trang đầu tiên.
Không có tham số offset, không có khả năng duyệt ngược về trang trước và không có tổng số chính xác. Để đếm một tập hợp, hãy duyệt toàn bộ tập hợp đó.
Ngoại lệ: GET /v1/cohorts/{id}/members chỉ trả về tối đa 50 hàng mỗi trang ngay cả khi bạn yêu cầu limit cao hơn. has_more và next_page_token vẫn phản ánh đúng phần còn lại của Nhóm.
Hãy xác thực bằng một trong hai dạng thông tin xác thực Basic — xem Quickstart (apikey:secret hoặc secret:). Đặt BASE thành máy chủ theo khu vực của tổ chức — xem Khu vực.

Duyệt một danh sách

Tải LIVING_SECURITY_API_KEY từ trình quản lý bí mật của quý vị như trong quickstart. Ví dụ này cần entity:read; khóa được dùng cho hướng dẫn yêu cầu đầu tiên có thể cần được cấp thêm quyền đó. Cài đặt requests cho Python hoặc jq cho ví dụ shell. Cả hai ví dụ đều ghim một phiên bản, giữ nguyên các bộ lọc và từ chối chuyển hướng. Các ví dụ dừng khi có lỗi và sau 1,000 trang thay vì báo cáo một lượt duyệt dở dang là đã hoàn tất. Thời gian chờ đọc của Python chỉ giới hạn thời gian không hoạt động, không giới hạn tổng thời lượng tác vụ; hãy áp dụng thời hạn cho tác vụ trong phần tích hợp của quý vị. Hãy yêu cầu từng trang cho đến khi next_page_token là null. Nên ưu tiên limit=500 cho các lần đọc hàng loạt để bao phủ toàn bộ tập hợp với ít yêu cầu hơn — xem giới hạn tốc độ.

Giữ nguyên bộ lọc trong khi phân trang

Page token là các con trỏ đã ký và không trong suốt (opaque). Mỗi token được gắn với tổ chức, tài khoản dịch vụ đã xác thực, phiên bản hợp đồng và đúng bộ lọc của yêu cầu đã tạo ra token đó. Việc thay đổi bất kỳ yếu tố nào trong số đó giữa chừng — chẳng hạn thêm bộ lọc type ở trang thứ hai — sẽ trả về 400 với mã invalid_request trên tham số page_token:
400 Invalid request
Để thay đổi bộ lọc, hãy bắt đầu lượt duyệt mới từ trang đầu tiên.
Hãy coi page_token là một chuỗi không trong suốt: truyền lại đúng nguyên trạng như đã nhận. Không giải mã, không lưu trữ lâu dài và không tự tạo token — định dạng nội bộ của chúng có thể thay đổi bất kỳ lúc nào mà không cần báo trước.
Các endpoint danh sách từ chối những tham số truy vấn mà chúng không hỗ trợ bằng 400 invalid_request nêu tên tham số đó. Hãy xem tài liệu tham chiếu của từng endpoint để biết các bộ lọc được hỗ trợ.

Xử lý tập hợp bị gián đoạn hoặc thay đổi

Các ví dụ này không tự động thử lại khi gặp lỗi. Đối với 429, hãy tuân thủ Retry-After và làm theo hướng dẫn thử lại có giới hạn. Giữ nguyên khu vực, tài khoản dịch vụ, phiên bản, bộ lọc và page token của trang được xử lý thành công gần nhất khi thử lại một lần đọc. Việc thay đổi thông tin xác thực không cấp quyền truy cập: mỗi yêu cầu vẫn kiểm tra các quyền hiện hành. Việc đọc nhiều trang không phải là ảnh chụp nhanh (snapshot) của tập hợp. Các hàng có thể thay đổi trong khi quý vị duyệt. Hãy xử lý tài nguyên theo id ổn định của chúng và làm cho các thao tác ghi ở hạ nguồn có tính idempotent; việc khởi động lại có thể trả về một hàng lần nữa. Nếu một token bị từ chối, hãy kiểm tra lỗi page_token và sửa yêu cầu trước khi bắt đầu lại từ trang đầu tiên. Không âm thầm loại bỏ dữ liệu đã xử lý trước đó và không đánh dấu một lần xuất bị gián đoạn là đã hoàn tất. Để có tổng số báo cáo chính xác, hãy dùng tài nguyên báo cáo phù hợp thay vì coi một lượt duyệt danh sách trực tiếp là ảnh chụp nhanh.