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

Ключевые термины

Ресурс
Объект в Google Ads, например, campaign или ad_group .
Сегмент
Измерение, используемое для группировки данных, например, segments.date или segments.device . Когда сегменты включаются в предложение SELECT вместе с метриками, метрики разделяются по сегментам.
Метрика
Показатель эффективности, например, metrics.impressions или metrics.clicks .
Приписываемый ресурс
Ресурс, который неявно связан с основным ресурсом в предложении FROM , что позволяет выбирать его атрибуты наряду с атрибутами основного ресурса.

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

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

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

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

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

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

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

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

Вот пример простого запроса для получения атрибутов ресурса кампании, иллюстрирующий, как вернуть идентификатор, название и статус кампании:

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 показами, сортируя по ID кампании. В каждой полученной строке 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 .

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

Запросы, отправляемые в 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 ).

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

Различия, специфичные для каждой версии

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

  • Ресурсы целей жизненного цикла: В версии 25 и более поздних версиях все цели жизненного цикла (привлечение новых клиентов, удержание клиентов и удержание лояльных клиентов) запрашиваются из объединенных ресурсов goal и campaign_goal_config , заменяя customer_lifecycle_goal и campaign_lifecycle_goal (которые использовались для целей привлечения новых клиентов в версии 24 и более ранних версиях, наряду с goal и campaign_goal_config для целей удержания клиентов).
  • Показатели представления конечного URL-адреса расширения: В версиях 25 и выше запрос final_url_expansion_asset_view возвращает все выбираемые показатели для представления. В версиях 24 и более ранних ответах содержатся только metrics.conversions и metrics.conversions_value для кампаний Performance Max и metrics.impressions для поисковых кампаний.
  • Отчеты по товарам для рекламных кампаний в приложениях: В версии 24 и более поздних версиях ресурс shopping_product возвращает строки с товарами для рекламных кампаний в приложениях в дополнение к кампаниям в приложениях, Performance Max, Demand Gen и Video (в версии 23 рекламные кампании в приложениях исключены из результатов shopping_product ).
  • Ресурсы, сегменты и метрики, специфичные для каждой версии:
    • В версиях 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 и более ранних).
    • В версиях 24 и более поздних: включает ресурс 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 (которые можно выбрать только в версии 23).
  • Код ошибки при детальном поиске дат: Запросы, сегментирующие по segments.date , segments.week или segments.hour (или фильтрующие по диапазону дат за пределами 37-месячного периода), возвращают DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED в версиях 24 и выше (или DateRangeError.UNKNOWN в версии 23). Подробнее см. раздел « Диапазоны дат» .

Примеры кода

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

Далее
Грамматика запроса