Структура запроса

Запросы полей ресурсов, сегментов и показателей можно отправлять в метод GoogleAdsService Search или SearchStream. Чтобы составить запрос на языке запросов Google Рекламы, используйте грамматику языка. Общие сведения о языке запросов Google Рекламы можно найти в этой статье. Запрос состоит из нескольких частей:

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT
  • PARAMETERS

Предложения содержат названия полей, названия ресурсов, операторы, условия и правила сортировки, которые помогают выбрать нужные данные. Объединив их в один запрос, вы можете отправить его в Google Ads API.

Предложения

В следующих разделах описываются назначение и синтаксис каждого предложения языка запросов Google Рекламы.

ВЫБРАТЬ

Предложение SELECT указывает набор полей, которые нужно получить в запросе. SELECT принимает список полей ресурсов, полей сегментов и показателей, разделенных запятыми, и возвращает значения в ответе. Предложение SELECT является обязательным в запросе.

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

SELECT
  campaign.id,
  campaign.name
FROM campaign

В одном запросе можно указать поля разных типов, например:

SELECT
  campaign.id,
  campaign.name,
  bidding_strategy.id,
  bidding_strategy.name,
  segments.device,
  segments.date,
  metrics.impressions,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  • Основные поля ресурса
    • campaign.id
    • campaign.name
  • Поля атрибутированных ресурсов
    • bidding_strategy.id
    • bidding_strategy.name
  • Поля сегментов
    • segments.device
    • segments.date
  • Показатели
    • metrics.impressions
    • metrics.clicks
  • Запрос полей, которые нельзя выбрать. У этих полей атрибут метаданных selectable отмечен как false.
  • Выбор атрибутов повторяющихся полей. У этих полей атрибут метаданных is_repeated отмечен как true.
  • Выбор полей, недоступных для указанного ресурса в пункте FROM. Атрибуты некоторых ресурсов нельзя выбирать вместе, а для ресурса в предложении FROM доступна только часть всех показателей и сегментов.
  • Выбирать несовместимые сегменты или показатели. Подробнее…

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

СО

Предложение FROM указывает основной ресурс, который нужно вернуть. Ресурс в условии FROM определяет, какие поля можно использовать во всех остальных условиях заданного запроса. В предложении FROM можно указать только один ресурс. Предложение FROM обязательно в запросе к методу GoogleAdsService Search или SearchStream. Однако при использовании GoogleAdsFieldService не следует указывать условие FROM.

В предложении FROM для определенного запроса может существовать только один ресурс, но поля из связанных ресурсов также могут быть доступны. Эти ресурсы неявно связаны с ресурсом в предложении FROM, поэтому, чтобы получить их значения, достаточно добавить их атрибуты в предложение SELECT. Не все ресурсы имеют приписанные ресурсы. В примере ниже показано, как запросить идентификаторы группы объявлений и кампании:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Поле resource_name основного ресурса возвращается всегда. В примере ниже поле ad_group.resource_name включено в ответ, хотя оно не было явно выбрано в запросе:

SELECT ad_group.id
FROM ad_group

То же самое относится к ресурсам с атрибуцией, если выбрано хотя бы одно поле. Например, campaign.resource_name включается в ответ на следующий запрос:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

Предложение WHERE задает условия, которые применяются при фильтрации данных для запроса. При использовании оператора WHERE укажите одно или несколько условий, разделенных оператором AND. Условия обычно следуют шаблону field_name Operator value (или используют BETWEEN value AND value, IS NULL или IS NOT NULL). Предложение WHERE в запросе необязательно.

В следующем примере используется WHERE для возврата показателей за определенный период времени:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Чтобы отфильтровать данные, можно комбинировать несколько условий. В этом примере запрашивается количество кликов для всех кампаний с показами на мобильных устройствах за последние 30 дней:

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = 'MOBILE'
  AND segments.date DURING LAST_30_DAYS

Сегменты в предложении WHERE также должны быть в предложении SELECT, за исключением следующих сегментов дат, которые называются базовыми сегментами дат:

  • segments.date
  • segments.week
  • segments.month
  • segments.quarter
  • segments.year

В следующем запросе выбран элемент segments.date. Поскольку этот сегмент является базовым сегментом дат, в предложении WHERE необходимо указать конечный диапазон дат, состоящий из базовых сегментов дат:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Все сегменты, которые соответствуют предыдущему условию: segments.date, segments.week, segments.month, segments.quarter и segments.year. Если выбран хотя бы один из этих сегментов, то по крайней мере один из них должен использоваться в условии WHERE.

Подробнее о диапазонах дат…

При фильтрации учитывайте регистр оператора. Подробнее об учете регистра…

Полный список операторов приведен в грамматике языка.

ORDER BY

Предложение ORDER BY определяет порядок, в котором возвращаются результаты. Это позволяет упорядочить данные в порядке возрастания или убывания на основе имени поля. Каждый порядок сортировки указывается как field_name, за которым следует ASC или DESC. Если не указано ни ASC, ни DESC, по умолчанию используется ASC. Оператор ORDER BY в запросе необязателен.

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

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

В предложении ORDER BY можно указать несколько полей, перечислив их через запятую. Сортировка выполняется в той же последовательности, которая указана в запросе. Например, в этом запросе, в котором выбраны данные о группах объявлений, результаты отсортированы в следующем порядке: по возрастанию по названию кампании, по убыванию по количеству показов, по убыванию по количеству кликов:

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

ОГРАНИЧЕНИЕ (LIMIT)

Предложение LIMIT позволяет указать количество возвращаемых результатов. Это удобно, если вам нужна только часть результатов.

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

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

ПАРАМЕТРЫ

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

Поддерживаются следующие метапараметры:

include_drafts

Задайте для параметра include_drafts значение true, чтобы возвращать объекты черновиков. Значение по умолчанию – false.

Например, следующий запрос возвращает как проекты кампаний, так и обычные кампании:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts = true

omit_unselected_resource_names

Установите для параметра omit_unselected_resource_names значение true, чтобы в ответе не указывалось название ресурса каждого типа, если оно не было явно запрошено в предложении SELECT. Значение по умолчанию – false.

Запрос Возвращенные ресурсы 
SELECT
  campaign.name,
  customer.id
FROM campaign
  • campaign.resource_name
  • customer.resource_name

Значение по умолчанию для omit_unselected_resource_names – false, поэтому возвращаются все поля resource_name.

 
SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Нет

Для параметра omit_unselected_resource_names задано значение true, а параметры campaign.resource_name и customer.resource_name не включены в условие SELECT.

 
SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
  • campaign.resource_name

omit_unselected_resource_names указан как true, а campaign.resource_name запрашивается как часть предложения SELECT.

Дополнительные правила в отношении языка

Помимо примеров для каждой конструкции, язык запросов Google Рекламы поддерживает следующие действия:

  • Основное поле ресурса не требуется в предложении SELECT для запроса. Например, вы можете использовать одно или несколько полей основного ресурса, чтобы фильтровать данные, не выбирая их:

    SELECT campaign.id
FROM ad_group
WHERE ad_group.status = 'PAUSED'

  • Показатели можно выбирать для определенного ресурса. Другие поля из ресурса в запросе не требуются.

    SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM campaign

  • Поля сегментации можно выбирать без сопутствующих полей ресурсов или показателей:

    SELECT segments.device FROM campaign

  • Поле resource_name (например, campaign.resource_name) можно использовать для фильтрации или упорядочивания данных:

    SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'
Назад
Грамматика запросов
Далее
Диапазоны дат