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

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

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

  • Ресурсы и связанные с ними атрибуты, сегменты и метрики с использованием поиска GoogleAdsService или 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. 1. Получить объект Campaign из поля campaign каждой строки GoogleAdsRow в ответе. 1. Измените статус каждой кампании с PAUSED на ENABLED . 1. Вызвать 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 .

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