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

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

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'
Назад
Грамматика запросов
Далее
Диапазоны дат