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

Сервис GoogleAdsService — это унифицированный сервис для получения объектов и формирования отчетов в рамках API Google Ads. Сервис содержит методы, которые:

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

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

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

Узнайте больше о различиях между пейджингом и потоковой передачей .

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

Для использования метода поиска требуется объект SearchGoogleAdsRequest , который состоит из следующих атрибутов:

• customer_id
• query на языке запросов Google Ads, указывающий, к какому ресурсу следует обратиться, какие атрибуты, сегменты и метрики следует получить, а также условия, используемые для ограничения возвращаемых объектов.
• (Только GoogleAdsService.Search ) Необязательный page_token для получения следующей партии результатов при использовании постраничной навигации .

Для получения более подробной информации о языке запросов Google Ads ознакомьтесь с руководством по языку запросов Google Ads .

Обработать ответ

Сервис GoogleAdsService возвращает список объектов GoogleAdsRow .

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

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

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

НЕИЗВЕСТНЫЕ типы перечислений

Ресурсы, возвращаемые с типом UNKNOWN не полностью поддерживаются в данной версии API. Эти ресурсы могли быть созданы через другие интерфейсы, например, через пользовательский интерфейс Google Ads. Вы можете выбирать метрики, если ресурс имеет тип UNKNOWN , но вы не можете изменять ресурс через API. Примером может служить новая кампания или объявление, запущенные в пользовательском интерфейсе, но не поддерживаемые в версии API, к которой вы обращаетесь.

Вот несколько моментов, которые следует учитывать:

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

Сегментация

В ответе будет содержаться одна GoogleAdsRow для каждой из следующих комбинаций:

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

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

• campaign
• segments.ad_network_type
• segments.date

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

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

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