Получение объектов

GoogleAdsService – это единый сервис для получения объектов и создания отчетов в Google Ads API. В сервисе есть методы, которые:

  • Получать определенные атрибуты объектов.
  • Получение показателей эффективности объектов за определенный диапазон дат.
  • Упорядочивать объекты по их признакам.
  • Используйте условия, чтобы указать, какие объекты вы хотите получить в ответе.
  • Ограничьте количество возвращаемых объектов.

GoogleAdsService может возвращать результаты двумя способами:

  • GoogleAdsService.SearchStream возвращает все строки в одном потоковом ответе, что более эффективно для больших наборов результатов (более 10 000 строк). Рекомендуется, если ваше приложение скачивает полные наборы результатов или обрабатывает строки в виде потока.
  • GoogleAdsService.Search разбивает большие ответы на страницы с результатами. Это удобно, если интерактивное приложение показывает результаты постранично.

Подробнее о разбиении на страницы и потоковой передаче…

Отправить запрос

GoogleAdsService.SearchStream ожидает SearchGoogleAdsStreamRequest, а GoogleAdsService.Search – SearchGoogleAdsRequest. Оба типа запросов включают:

  • customer_id
  • Запрос на языке Google Рекламы (query), в котором указано, к какому ресурсу нужно обратиться, какие атрибуты, сегменты и показатели получить и какие условия использовать, чтобы ограничить набор возвращаемых объектов.

В зависимости от метода запрос также поддерживает поля, относящиеся к конкретному методу:

  • SearchGoogleAdsStreamRequest (только SearchStream):
    • Необязательный параметр summary_row_setting, позволяющий запросить строку сводки с агрегированными показателями.
  • SearchGoogleAdsRequest (только Search):
    • Необязательный параметр page_token, позволяющий получить следующий пакет результатов при использовании разбивки на страницы (значение page_size фиксировано и составляет 10 000 строк; если задать page_size в запросе, возникнет ошибка RequestError.PAGE_SIZE_NOT_SUPPORTED).
    • Необязательное сообщение search_settings для настройки return_summary_row, return_total_results_count и omit_results.
    • Необязательное логическое значение validate_only, позволяющее проверить запрос, не выполняя его.

Подробную информацию о языке запросов Google Ads API можно найти в руководстве по языку запросов Google Ads API.

Как обработать ответ

Метод GoogleAdsService возвращает список объектов GoogleAdsRow (внутри пакетов SearchGoogleAdsStreamResponse или в виде разбитого на страницы списка SearchGoogleAdsResponse).

Каждый объект GoogleAdsRow представляет собой объект, возвращенный запросом, и состоит из набора атрибутов, которые заполняются на основе полей, запрошенных в предложении SELECT. Атрибуты, не включенные в предложение SELECT, не заполняются в объектах GoogleAdsRow в ответе.

Например, хотя у ad_group_criterion есть атрибут status, поле status атрибута ad_group_criterion строки не заполняется в ответе на запрос, в котором предложение SELECT не включает ad_group_criterion.status. Аналогично, атрибут campaign строки не заполняется, если предложение SELECT не включает поля из ресурса campaign.

Каждая строка GoogleAdsRow может иметь разные атрибуты и показатели по сравнению с другой строкой в том же наборе результатов. Поэтому строки следует рассматривать как объекты, а не как фиксированные строки таблицы.

Типы перечисления UNKNOWN и UNSPECIFIED

Ресурсы, возвращаемые со значением enum UNKNOWN, не полностью поддерживаются в этой версии API, а UNSPECIFIED указывает, что поле enum не было задано или не было запрошено в предложении SELECT. Ресурсы со значением перечисления UNKNOWN могли быть созданы в других интерфейсах, например в интерфейсе Google Рекламы. Вы можете выбирать показатели, если ресурс имеет тип UNKNOWN, но не можете изменять ресурс через API. Например, это может быть кампания или тип объявления, доступные в интерфейсе, но не поддерживаемые в версии API, к которой вы обращаетесь.

Ниже указано, что следует учитывать.

  • Ресурс с типом UNKNOWN может поддерживаться в более поздней версии API или оставаться UNKNOWN неопределенное время.
  • Новые объекты с типом UNKNOWN могут появиться в любой момент. Эти объекты обратно совместимы, поскольку значение перечисления UNKNOWN присутствует в каждом перечислении в API. Ресурсы возвращаются с UNKNOWN, чтобы вы могли точно оценить общие показатели эффективности аккаунта.
  • К ресурсам UNKNOWN могут быть прикреплены подробные показатели, которые можно запрашивать.
  • Ресурсы UNKNOWN обычно полностью видны в интерфейсе Google Рекламы.
  • Ресурсы UNKNOWN обычно нельзя изменить через API.

Сегментирование

Ответ содержит по одному объекту GoogleAdsRow для каждого сочетания следующих параметров:

  • Экземпляр основного ресурса, указанного в пункте FROM.
  • Значение каждого выбранного поля segments

Например, ответ на запрос, который выбирает FROM campaign и содержит segments.ad_network_type и segments.date в предложении SELECT, содержит по одной строке для каждой комбинации следующих элементов:

  • campaign
  • segments.ad_network_type
  • segments.date

Результаты неявно сегментируются по каждому экземпляру основного ресурса, а не по значениям отдельных выбранных полей. Пример:

SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

приведет к тому, что в отчете будет по одной строке на каждую кампанию, а не на каждое уникальное значение поля campaign.status.

Назад
Изменение объектов
Далее
Метаданные ресурса