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

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

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

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

Пункты

Видео: Совместимость с полями 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 для данного запроса может присутствовать только один ресурс, поля из атрибутированных ресурсов также могут быть доступны. Эти ресурсы неявно объединены с ресурсом в предложении 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

Все сегменты, удовлетворяющие вышеуказанному условию: segments.date , segments.week , segments.month , segments.quarter и segments.year . Если выбран какой-либо из этих сегментов, хотя бы один из них должен быть использован в предложении 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 в true , чтобы разрешить возврат черновиков сущностей. Значение по умолчанию — false .

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

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

пропустить невыбранные_имена_ресурсов

Установите для 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 , поэтому возвращаются все поля resource_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 Ads имеет следующие варианты поведения, которые можно использовать:

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