API Менеджера рекламы предоставляет наборы данных, чаще всего в методах списка. Коллекции могут иметь произвольный размер и разбиваться на страницы в ответах API.
Основы
Сообщения запроса для коллекций определяют необязательное целочисленное поле pageSize
, чтобы указать максимальное количество возвращаемых результатов.
Если pageSize
не установлен или равен 0, используется значение по умолчанию 50. Если pageSize
превышает максимальный размер страницы, равный 1000, API принудительно увеличивает размер страницы до 1000. Отрицательные значения приводят к ошибке INVALID_ARGUMENT
.
API может вернуть меньше результатов, чем запрошено (включая нулевые результаты), даже если это не конец коллекции. Используйте наличие поля nextPageToken
, чтобы определить, есть ли в коллекции дополнительные результаты.
Ответные сообщения для коллекций определяют строковое поле nextPageToken
, которое можно использовать для получения следующей страницы. Поле nextPageToken
становится пустым, когда достигается конец коллекции. Это единственный способ определить, достигли ли вы конца коллекции.
Сообщения запроса для коллекций определяют необязательное строковое поле pageToken
для перехода к следующей странице коллекции. Изменения pageSize
в запросе последующих страниц разрешены. Все остальные аргументы должны быть одинаковыми; если какие-либо аргументы отличаются, API возвращает ошибку INVALID_ARGUMENT
.
Пример
КУЛЬ
Первоначальный запрос
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500
{
"adUnits": [ ... ],
"nextPageToken": "eCGwAcs6hUerggzd2DGv"
}
Запрос следующей страницы
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500&pageToken=eCGwAcs6hUerggzd2DGv
{
"adUnits": [ ... ]
}
Общий размер
Ответные сообщения для коллекций предоставляют целое число totalSize
, которое представляет общее количество сущностей после применения фильтрации. Это поле заполняется только по запросу в маске поля .
GET https://admanager.googleapis.com/v1/networks/123456/adUnits?$fields=adUnits,nextPageToken,totalSize
Результаты заказа
Сообщения запроса для коллекций определяют строковое поле orderBy
для указания порядка сортировки.
Значения должны представлять собой список полей, разделенных запятыми. Например: foo,bar
. По умолчанию порядок сортировки — по возрастанию. Чтобы указать порядок убывания поля, добавьте суффикс desc
; например: foo desc, bar
. Избыточные пробелы в синтаксисе игнорируются. Значения orderBy
foo, bar desc
, foo , bar desc
и foo,bar desc
эквивалентны. Подполя обозначаются знаком .
символ, например foo.bar
или address.street
.
Порядок поддерживается только для примитивных полей.
Пропустить результаты
Методы для операций с разбивкой на страницы определяют целочисленное поле skip
для пропуска результатов. Значение пропуска относится к количеству отдельных ресурсов, которые необходимо пропустить, а не к количеству страниц.
Например:
Запрос без токена страницы и значением пропуска 30 возвращает одну страницу результатов, начиная с 31-го результата.
Запрос с токеном страницы, соответствующим 51-му результату (поскольку первые 50 результатов были возвращены на первой странице) и значением пропуска, равным 30, возвращает одну страницу результатов, начиная с 81-го результата.
Если указано значение пропуска, из-за которого курсор перемещается за конец коллекции результатов, ответом будет 200 OK
с пустым набором результатов без nextPageToken
.