Язык запросов 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 будет представлять собой кортеж из кампании и 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 .

Передовые методы

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

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

При запросе к определенному ресурсу вы можете немедленно получить возвращенные результаты в виде объектов, изменить их и отправить обратно в метод `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 .

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