API Ad Manager предоставляет коллекции данных, чаще всего в виде List ). Размеры коллекций могут быть произвольными, а в ответах API данные передаются постранично.
Основы
В сообщениях запроса для коллекций указывается необязательное целочисленное поле pageSize , определяющее максимальное количество возвращаемых результатов.
Установите параметр pageSize на положительное число, меньшее 1000 Если вы не зададите никакого значения или установите параметр равным нулю, API будет использовать значение по умолчанию, равное 50 Если вы установите параметр на отрицательное значение, API вернет ошибку INVALID_ARGUMENT .
Для получения информации о значении pageSize специфичном для данного ресурса, обратитесь к справочной документации по ресурсу, например, AdBreaks .
API может вернуть меньше результатов, чем запрошено (включая нулевые результаты), даже если коллекция еще не завершена. Используйте наличие поля nextPageToken , чтобы определить, есть ли в коллекции дополнительные результаты.
В ответных сообщениях для коллекций определяется строковое поле nextPageToken , которое можно использовать для получения следующей страницы. Поле nextPageToken становится пустым, когда достигается конец коллекции. Это единственный способ определить, достигнут ли конец коллекции.
В запросах к коллекциям указывается необязательное строковое поле pageToken для перехода на следующую страницу в коллекции. Допускаются изменения pageSize в запросе на последующие страницы. Все остальные аргументы должны быть одинаковыми; если какие-либо аргументы отличаются, API возвращает ошибку INVALID_ARGUMENT .
Пример
cURL
Первоначальный запрос
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 , представляющее общее количество сущностей после применения фильтрации. Это поле заполняется только по запросу в поле mask .
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 для пропуска результатов. Значение skip указывает количество отдельных ресурсов, которые следует пропустить, а не количество страниц.
Например:
Запрос без токена страницы и со значением пропуска 30 возвращает одну страницу результатов, начиная с 31-го результата.
Запрос с токеном страницы, соответствующим 51-му результату (поскольку первые 50 результатов были возвращены на первой странице), и значением пропуска 30 возвращает одну страницу результатов, начиная с 81-го результата.
Если указано значение пропуска, которое приводит к перемещению курсора за пределы набора результатов, в ответ будет отправлен код 200 OK с пустым набором результатов без nextPageToken .