Эта страница переведена с помощью Cloud Translation API.

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

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

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

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 в службе этого ресурса. Ниже приведен пример рабочего процесса:

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

Грамматика запроса