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

Запросы к полям ресурсов, сегментов и метрик можно отправлять в методы GoogleAdsService Search или SearchStream . Для построения запроса на языке запросов Google Ads необходимо использовать соответствующую грамматику . Общий обзор языка запросов Google Ads см. в разделе «Обзор языка запросов 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
  • Запросы к полям, которые нельзя выбрать. Атрибут метаданных Selectable для этих полей будут помечен как false .
  • Выбор атрибутов повторяющихся полей. Атрибут метаданных isRepeated для этих полей будет помечен как true .
  • Выбор полей, недоступных для данного ресурса в предложении FROM . Атрибуты некоторых ресурсов нельзя выбрать одновременно, кроме того, для ресурса в предложении FROM будет доступно только подмножество всех метрик и сегментов.
  • Выбор сегментов или показателей, несовместимых друг с другом. Дополнительную информацию об этом см. в разделе «Сегментация» .

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

ОТ

Предложение FROM указывает основной ресурс, который будет возвращен. Ресурс в предложении FROM определяет, какие поля могут быть использованы во всех остальных предложениях для данного запроса. В предложении FROM может быть указан только один ресурс. Предложение FROM обязательно в запросе к методам GoogleAdsService Search или SearchStream . Однако предложение FROM не следует указывать при использовании 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

Все сегменты, удовлетворяющие вышеуказанному условию, это: 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

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