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

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 Рекламы…

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

Функция 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

Ресурсы, возвращаемые со значением перечисления UNKNOWN, не полностью поддерживаются в этой версии API, а UNSPECIFIED указывает, что поле перечисления не задано или не было запрошено в предложении 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.

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