Язык запросов Google Рекламы

Совет. Используйте интерактивный конструктор запросов, чтобы создавать и проверять запросы GAQL.

Основные термины

Ресурс

Объект в Google Рекламе, например campaign или ad_group.

Сегмент

Параметр, используемый для группировки данных, например segments.date или segments.device. Если сегменты включены в предложение SELECT вместе с показателями, показатели разбиваются по сегментам.

Показатель

Показатель эффективности, например metrics.impressions или metrics.clicks.

Ресурс с атрибуцией

Ресурс, который неявно связан с основным ресурсом в пункте FROM, что позволяет выбирать его атрибуты вместе с атрибутами основного ресурса.

Запрос информации о ресурсе или метаданных

С помощью языка запросов Google Ads Query Language можно запрашивать у Google Ads API следующие типы информации:

• Ресурсы и связанные с ними атрибуты, сегменты и показатели, использующие GoogleAdsService Search или SearchStream. Результатом запроса GoogleAdsService является список экземпляров GoogleAdsRow, каждый из которых GoogleAdsRow представляет ресурс.

  Если запрашиваются какие-либо атрибуты или показатели, то строка также включает эти поля. Если запрашиваются какие-либо сегменты, то в ответе также отображается дополнительная строка для каждого кортежа сегмент-ресурс.

• Метаданные о доступных полях и ресурсах в GoogleAdsFieldService. Этот сервис предоставляет каталог полей, которые можно запрашивать, с информацией об их совместимости и типе.

  Результатом запроса GoogleAdsFieldService является список экземпляров GoogleAdsField, каждый GoogleAdsField из которых содержит сведения о запрошенном поле.

Подробнее о структуре запросов и грамматике языка запросов Google Рекламы…

Запрос атрибутов ресурса

Ниже приведен пример простого запроса атрибутов ресурса кампании, который возвращает идентификатор, название и статус кампании.

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

Этот запрос упорядочивает данные по идентификатору кампании. Каждый полученный результат GoogleAdsRow представляет собой объект campaign, заполненный выбранными полями, включая resource_name кампании.

Чтобы узнать, какие ещё поля доступны для запросов кампаний, ознакомьтесь со справочной документацией по Campaign.

Запрос показателей

Помимо выбранных атрибутов для определенного ресурса, вы также можете запрашивать связанные показатели:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

Этот запрос позволяет отфильтровать кампании со статусом PAUSED и количеством показов более 1000, а также упорядочить их по идентификатору. Каждый полученный объект GoogleAdsRow будет содержать поле metrics, заполненное выбранными показателями.

Список показателей, по которым можно выполнять запросы, приведен в документации по Metrics.

Запрос сегментов

Помимо выбранных атрибутов для определенного ресурса, вы также можете запрашивать связанные сегменты:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date DURING LAST_30_DAYS
ORDER BY campaign.id

Как и в случае с запросом показателей, этот запрос фильтрует только кампании со статусом PAUSED и количеством показов более 1000. Однако этот запрос сегментирует данные по дате. В результате каждый элемент GoogleAdsRow представляет собой кортеж из кампании и сегмента даты. Сегментирование разделяет выбранные показатели, группируя их по каждому сегменту в пункте SELECT.

Список сегментов, по которым можно выполнять запросы, приведен в документации по Segments.

Запрос атрибутов связанного ресурса

В запросе к определенному ресурсу можно объединить данные из других связанных ресурсов, если они доступны. Такие связанные ресурсы называются "атрибутированными ресурсами". Вы можете неявно объединять ресурсы с атрибутами, выбирая атрибут в запросе.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

Этот запрос не только выбирает атрибуты кампании, но и извлекает связанные атрибуты из каждой выбранной кампании. Каждый полученный объект GoogleAdsRow представляет собой объект campaign, заполненный выбранными атрибутами кампании, а также выбранным атрибутом стратегии назначения ставок bidding_strategy.name.

Чтобы узнать, какие ресурсы атрибуции доступны для запросов кампании, ознакомьтесь со справочной документацией по Campaign.

Рекомендации

• Чтобы избежать задержек и тайм-аутов, выбирайте только нужные поля.
• Используйте LIMIT во время разработки и тестирования, чтобы избежать обработки больших наборов результатов.
• Применяйте фильтры в условии WHERE, чтобы уменьшить объем передаваемых данных и размер ответа.
• Прежде чем создавать сложные запросы, проверьте совместимость полей и типы данных с помощью GoogleAdsFieldService.
• Помните, что некоторые поля, особенно те, которые содержат большие объемы данных или сложные вычисления, могут увеличить стоимость запроса.

Изменение на основе результатов запроса

При запросе определенного ресурса вы можете сразу же взять возвращенные результаты в качестве объектов, изменить их и отправить обратно в метод mutate в сервисе этого ресурса. Вот пример рабочего процесса:

1. Выполните запрос для всех кампаний PAUSED, у которых количество показов больше 1000.
2. Получите объект Campaign из поля campaign каждого объекта GoogleAdsRow в ответе.
3. Измените статус каждой кампании с PAUSED на ENABLED.
4. Вызовите CampaignService.MutateCampaigns с измененными кампаниями и соответствующим FieldMask, чтобы обновить их.

Примечание. При обновлении ресурсов, полученных из запроса, укажите FieldMask (или используйте встроенную утилиту маски полей клиентской библиотеки), чтобы обновлялись только измененные поля. Это позволит избежать ошибок READ_ONLY_FIELD или IMMUTABLE_FIELD, а также непреднамеренной перезаписи других атрибутов.

Метаданные поля

Запросы, отправленные в GoogleAdsFieldService, предназначены для получения метаданных полей. Эта информация поможет вам понять, как использовать поля в запросе. Поскольку данные доступны через API и он предоставляет метаданные, необходимые для проверки или создания запроса, разработчики могут делать это программно. Вот типичный запрос метаданных:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

В этом запросе вы можете заменить <INSERT_RESOURCE_OR_FIELD> ресурсом (например, customer или campaign) или полем (например, campaign.id, metrics.impressions или ad_group.id).

Важно! Обратите внимание, что в этом запросе нет предложения FROM.

Список полей, по которым можно выполнять запросы, приведен в документации по GoogleAdsField.

Различия между версиями

Синтаксис, предложения и операторы языка запросов Google Ads API одинаковы во всех поддерживаемых версиях Google Ads API (v23, v24, v25 и v26), но каталог ресурсов, сегментов, показателей и принципов работы отчетов, доступных для запросов, зависит от основной версии. Отправьте запрос к конечной точке GoogleAdsFieldService целевой версии API, чтобы проверить поля и правила совместимости для этой версии:

• Представление объектов дополнения конечного URL:
  • Поддержка торговых кампаний (версия 26 и более поздние). final_url_expansion_asset_view поддерживает торговые кампании (campaign.advertising_channel_type = 'SHOPPING') в дополнение к кампаниям с максимальной эффективностью и поисковым кампаниям. В торговых кампаниях можно выбирать и фильтровать поля ad_group, но нельзя выбирать поля asset_group.
  • Выбираемые показатели (v25 и более поздние версии). Запрос final_url_expansion_asset_view возвращает все выбираемые показатели для представления. В версии 24 и более ранних версиях ответы содержат только metrics.conversions и metrics.conversions_value для кампаний с максимальной эффективностью и metrics.impressions для поисковых кампаний.
• Ресурсы целей по жизненному циклу. В версии 25 и более поздних все цели по жизненному циклу (привлечение новых клиентов, удержание клиентов и удержание участников программы лояльности) запрашиваются из унифицированных ресурсов goal и campaign_goal_config, которые заменяют customer_lifecycle_goal и campaign_lifecycle_goal (использовавшиеся для целей привлечения новых клиентов в версии 24 и более ранних, наряду с goal и campaign_goal_config для целей удержания клиентов).
• Отчеты о товарах в кампаниях для приложений. В версии 24 и более поздних ресурс shopping_product возвращает строки товаров для кампаний для приложений, а также торговых кампаний, кампаний с максимальной эффективностью, кампаний для создания спроса и видеокампаний (в версии 23 кампании для приложений исключены из результатов shopping_product).
• Ресурсы, сегменты и показатели, относящиеся к определенной версии:
  • Версия 26 и более поздние. Включает ресурс search_lift_keyword_bundle, campaign.lift_measurement_config, local_services_lead.campaign, segments.search_lift_keyword_bundle, segments.search_property и показатели Search Lift (например, metrics.relative_search_lift, metrics.normalized_incremental_searches, metrics.search_lift_cost_micros и metrics.search_lift_impressions).
  • Версия 25 и более поздние. Включает ресурсы для измерения роста (например, lift_measurement_config), сегменты, такие как segments.ad_sub_format_type и segments.loyalty_membership, и показатели взаимодействия на YouTube (metrics.youtube_likes, metrics.youtube_comments и metrics.youtube_shares). Удален ресурс local_services_lead.contact_details.email (который можно выбрать в версии 24 и более ранних).
  • v24 и более поздние версии. Включает ресурс cart_data_sales_view, segments.conversion_attribution_event_type в shopping_performance_view, segments.mobile_device_platform и segments.ad_network_type в performance_max_placement_view. Удаляет campaign.video_brand_safety_suitability (заменяется на customer.video_brand_safety_suitability), segments.ad_sub_network_type в campaign_budget и segments.click_type в ad_group_asset, campaign_asset и customer_asset (которые можно выбрать только в v23).
• Код ошибки при запросе подробных данных за период учета, превышающий 37 месяцев. Запросы, в которых сегментирование выполняется по полям segments.date, segments.week или segments.hour (или фильтрация выполняется по диапазону дат меньше месяца) за период, превышающий 37 месяцев, возвращают ошибку DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED в версии 24 и более поздних (или DateRangeError.UNKNOWN в версии 23). Подробнее о диапазонах дат…

Примеры кода

В клиентских библиотеках есть примеры использования языка запросов Google Рекламы в GoogleAdsService. В папке basic operations (основные операции) есть примеры GetCampaigns, GetKeywords и SearchForGoogleAdsFields.