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

Язык запросов Google Рекламы может запрашивать API Google Рекламы для

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

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

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

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

Ниже приведен базовый запрос атрибутов ресурса кампании, показывающий, как вернуть идентификатор, имя и статус кампании:

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 представляет кортеж кампании и Segment даты. Важно отметить, что при сегментировании выбранные метрики разбиваются, группируясь по каждому сегменту в предложении SELECT.

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

В запросе к данному ресурсу вы можете присоединиться к другим связанным ресурсам, если они доступны. Эти связанные ресурсы известны как «приписанные ресурсы». Вы можете присоединиться к ресурсам с атрибутами неявно, выбрав атрибут в своем запросе.

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

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

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

Мутация на основе результатов запроса

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

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

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

Запросы, отправленные в 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 в GoogleAdsService . В папке основных операций есть такие примеры, как GetCampaigns , GetKeywords и SearchForGoogleAdsFields . В папке отчетов есть пример GetKeywordStats .