/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.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.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ảiLIVING_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ọctype ở trang thứ hai — sẽ trả về 400 với mã
invalid_request trên tham số page_token:
400 Invalid request
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ới429, 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.
