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

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

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

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

Положения

Видео : совместимость полей GAQL

ВЫБИРАТЬ

Предложение 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

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

  • Запрос полей, которые нельзя выбрать. Эти поля будут иметь атрибут метаданных Selectable , помеченный как false .
  • Выбор атрибутов повторяющихся полей. Атрибут метаданных isRepeated для этих полей будет помечен как true .
  • Выбор полей, недоступных для данного ресурса в предложении FROM . Атрибуты некоторых ресурсов нельзя выбирать вместе, также для ресурса в предложении FROM будет доступно только подмножество всех метрик и сегментов.
  • Выбор сегментов или показателей, несовместимых друг с другом. Подробнее об этом смотрите в разделе сегментация .

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

ОТ

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

Хотя в предложении 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 можно указать одно или несколько условий с помощью AND для их разделения. Каждое условие должно соответствовать шаблону field_name Operator value . Предложение 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

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

При фильтрации важно учитывать чувствительность вашего оператора к регистру. Дополнительную информацию см. в разделе Чувствительность к регистру .

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

ЗАКАЗАТЬ ПО

Предложение 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 .

omit_unselected_resource_names примеры
SELECT
  campaign.name,
  customer.id
FROM campaign
Returned resources:
campaign.resource_name
customer.resource_name
omit_unselected_resource_names по умолчанию имеет значение false , поэтому возвращаются все поля resources_name.
SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true
Returned resources:
Никто.
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
Returned resource:
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'
Назад
Грамматика запроса
Далее
Диапазоны дат