API Ad Manager cung cấp các tập hợp dữ liệu, phổ biến nhất 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 các bộ sưu tập xác định trường pageSize số nguyên tuỳ chọn để 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 dành riêng cho tài nguyên.
API có thể trả về ít kết quả hơn số lượng đã yêu cầu (bao gồm cả kết quả rỗng), ngay cả khi không phải là kết quả cuối cùng của tập hợp. Sử dụng sự hiện diện của trường nextPageToken để xác định xem có kết quả nào khác 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 trường nextPageToken chuỗi, có thể dùng để truy xuất trang tiếp theo. Trường nextPageToken sẽ trống khi đế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 pageToken chuỗi không bắt buộc để chuyển đến 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ó đối số nào khác thì 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 đại diện cho tổng số thực thể sau khi áp dụng bộ lọc. Trường này chỉ được điề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ả
Yêu cầu thông báo cho các bộ sưu tập xác định trường orderBy chuỗi để 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 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ợ việc sắp xếp trên các trường gốc.
Bỏ qua kết quả
Các phương thức cho một thao tác phân trang xác định trường skip số nguyên để 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ụ:
Yêu cầu không có mã thông báo phân trang và giá trị bỏ qua là 30 sẽ trả về một trang kết quả 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ả 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 tập hợp kết quả trống không có nextPageToken.