API Ad Manager cung cấp các tập hợp dữ liệu, thường là trong các phương thức List. Các bộ sưu tập có thể có kích thước tuỳ ý và được phân trang trong các phản hồi API.
Thông tin cơ bản
Thông báo yêu cầu cho bộ sưu tập xác định một trường số nguyên pageSize không bắt buộc để chỉ định số lượng kết quả tối đa cần trả về.
Đặt tham số pageSize thành một số dương, nhỏ hơn 1000. Nếu bạn không đặt giá trị nào hoặc đặt tham số thành 0, API sẽ sử dụng giá trị mặc định là 50. Nếu bạn đặt tham số thành một giá trị âm, API sẽ trả về lỗi INVALID_ARGUMENT.
Tham khảo tài liệu tham khảo về tài nguyên, ví dụ: AdBreaks, để biết giá trị pageSize cụ thể của tài nguyên.
API có thể trả về ít kết quả hơn số lượng được yêu cầu (kể cả không có kết quả nào), ngay cả khi chưa đến cuối bộ sưu tập. Sử dụng sự hiện diện của trường nextPageToken để xác định xem có kết quả bổ sung nào trong tập hợp hay không.
Thông báo phản hồi cho các bộ sưu tập xác định một trường chuỗi nextPageToken. Bạn có thể dùng trường này để truy xuất trang tiếp theo. Trường nextPageToken sẽ trống khi đạt đến cuối bộ sưu tập. Đây là cách duy nhất để xác định xem bạn đã đến cuối một bộ sưu tập hay chưa.
Thông báo yêu cầu cho các bộ sưu tập xác định một trường chuỗi pageToken không bắt buộc để chuyển sang trang tiếp theo trong bộ sưu tập. Bạn được phép thay đổi pageSize trong yêu cầu cho các trang tiếp theo. Tất cả các đối số khác phải giống nhau; nếu có bất kỳ đối số nào khác, API sẽ trả về lỗi INVALID_ARGUMENT.
Ví dụ:
cURL
Yêu cầu ban đầu
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500
{
"adUnits": [ ... ],
"nextPageToken": "eCGwAcs6hUerggzd2DGv"
}
Yêu cầu trang tiếp theo
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500&pageToken=eCGwAcs6hUerggzd2DGv
{
"adUnits": [ ... ]
}
Tổng kích thước
Thông báo phản hồi cho các tập hợp cung cấp một số nguyên totalSize biểu thị tổng số thực thể sau khi áp dụng bộ lọc. Trường này chỉ được điền sẵn khi được yêu cầu trong mặt nạ trường.
GET https://admanager.googleapis.com/v1/networks/123456/adUnits?$fields=adUnits,nextPageToken,totalSize
Sắp xếp kết quả
Thông báo yêu cầu cho các bộ sưu tập xác định một trường chuỗi orderBy để chỉ định thứ tự sắp xếp.
Giá trị phải là danh sách các trường được phân tách bằng dấu phẩy. Ví dụ: foo,bar. Thứ tự sắp xếp mặc định là tăng dần. Để chỉ định thứ tự giảm dần cho một trường, hãy thêm hậu tố desc; ví dụ: foo desc, bar. Các ký tự khoảng trắng dư thừa trong cú pháp sẽ bị bỏ qua. Các giá trị orderBy foo, bar desc, foo , bar desc và foo,bar desc đều tương đương nhau. Các trường con được chỉ định bằng ký tự ., chẳng hạn như foo.bar hoặc address.street.
Chỉ hỗ trợ sắp xếp trên các trường nguyên thuỷ.
Bỏ qua kết quả
Các phương thức cho một thao tác phân trang xác định một trường số nguyên skip để bỏ qua kết quả. Giá trị bỏ qua đề cập đến số lượng tài nguyên riêng lẻ cần bỏ qua, chứ không phải số lượng trang.
Ví dụ:
Một yêu cầu không có mã thông báo trang và có giá trị bỏ qua là 30 sẽ trả về một trang kết quả duy nhất bắt đầu từ kết quả thứ 31.
Một yêu cầu có mã thông báo trang tương ứng với kết quả thứ 51 (vì 50 kết quả đầu tiên được trả về trên trang đầu tiên) và giá trị bỏ qua là 30 sẽ trả về một trang kết quả duy nhất bắt đầu từ kết quả thứ 81.
Nếu bạn cung cấp một giá trị bỏ qua khiến con trỏ di chuyển qua cuối tập hợp kết quả, thì phản hồi sẽ là 200 OK với một tập hợp kết quả trống không có nextPageToken.