Сегментирование

Сегментация доступна в интерфейсе Google Рекламы в виде отдельного меню. Чтобы сегментировать данные в Google Ads API, добавьте в запрос нужное поле. Например, вы добавляете в запрос segments.device. В результате вы получите отчет, в котором для каждого сочетания устройства и ресурса, указанного в предложении FROM, будет создана отдельная строка. Статистические значения (показы, клики, конверсии и т. д.) будут распределены между этими строками.

В интерфейсе Google Рекламы можно использовать только один сегмент за раз, но с помощью API вы можете указать несколько сегментов в одном запросе.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

Результаты отправки этого запроса в GoogleAdsService.SearchStream похожи на эту строку JSON:

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    }
  ]
}

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

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

Неявное сегментирование

Каждый отчет изначально сегментируется по ресурсу, указанному в пункте FROM. Поле resource_name ресурса в условии FROM возвращается, и показатели сегментируются по нему, даже если поле resource_name не включено в запрос явным образом. Например, если вы укажете ad_group в качестве ресурса в предложении FROM, то автоматически будет возвращено поле ad_group.resource_name, а показатели будут неявно сегментированы по нему на уровне ad_group.

Для этого запроса:

SELECT metrics.impressions
FROM ad_group

Вы получите строку JSON, которая выглядит следующим образом:

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

Поле resource_name ресурса adGroup возвращается всегда, поскольку ad_group указан в качестве ресурса в предложении FROM.

search_term_view

Ресурс search_term_view также неявно сегментируется по группе объявлений, а не только по поисковому запросу, что отражено в структуре его названия, которое также включает группу объявлений. Поэтому в результатах могут появляться строки, которые кажутся дубликатами, с одинаковыми поисковыми запросами, если эти строки относятся к разным группам объявлений:

{
  "results":[
    {
      "searchTermView":{
        "resourceName":"customers/1234567890/searchTermViews/111111111~2222222222~Z29vZ2xlIHBob3RvcyBpb3M",
        "searchTerm":"google photos"
      },
      "metrics":{
        "impressions":"3"
      },
      "segments":{
        "date":"2024-06-15"
      }
    },
    {
      "searchTermView":{
        "resourceName":"customers/1234567890/searchTermViews/111111111~33333333333~Z29vZ2xlIHBob3RvcyBpb3M",
        "searchTerm":"google photos"
      },
      "metrics":{
        "impressions":"2"
      },
      "segments":{
        "date":"2024-06-15"
      }
    }
  ]
}

Хотя два возвращенных объекта в этом примере кажутся дубликатами, названия их ресурсов на самом деле различаются, особенно в части идентификатора группы объявлений. Это означает, что поисковый запрос "google photos" относится к двум группам объявлений (идентификаторы 2222222222 и 33333333333) в одну и ту же дату (2024-06-15). Таким образом, API сработал правильно и не вернул повторяющиеся объекты.

Важно! Технически ресурс search_term_view также неявно сегментируется по кампаниям. Однако группа объявлений всегда должна принадлежать кампании, поэтому для дедупликации строк данных достаточно использовать только группу объявлений, поскольку она является наиболее детализированной единицей.

Поля сегментов, доступные для выбора

Не все поля сегментов можно выбрать для определенного ресурса в пункте FROM. Предположим, вы продолжаете запрашивать данные из ресурса ad_group. Чтобы поле сегмента можно было выбрать из ресурса ad_group, оно должно быть в списке Segments для ad_group. Список Segments – это желтая часть таблицы доступных полей на странице метаданных ресурса ad_group.

Примечание. Доступность сегментов для определенных ресурсов может зависеть от версии API. Чтобы проверить совместимость для целевой версии (v23, v24, v25 или v26), используйте селектор версий в справочнике по сервису Field в Google Ads API. Например, в версии 24 и более поздних segments.click_type нельзя выбрать вместе с ad_group_asset, campaign_asset или customer_asset, а segments.ad_sub_network_type – вместе с campaign_budget (эти комбинации поддерживаются только в версии 23).

Ресурсы сегментов

При выборе некоторых ресурсов у вас может быть возможность неявно объединить связанные ресурсы, выбрав их поля вместе с полями ресурса в предложении FROM. Эту информацию по теме можно найти в списке Attributed Resources на странице метаданных пункта FROM. В случае с ресурсом ad_group вы увидите, что можно также выбрать поля из ресурса campaign. Поле resource_name любого ресурса Attributed Resources, у которого есть хотя бы одно поле в условии SELECT, возвращается автоматически, даже если поле resource_name не указано в запросе явным образом.

Как и в случае с полями Attributed Resource, вы также можете выбрать поля Segmenting Resource. Если у ресурса на странице метаданных есть список Segmenting Resources, то при выборе полей из одного из перечисленных ресурсов запрос будет дополнительно сегментирован по возвращенному resource_name этого Segmenting Resource. Например, ресурс campaign указан как Segmenting Resource для ресурса campaign_budget. Если выбрать любое поле кампании, например campaign.name, из ресурса campaign_budget, будет возвращено не только поле campaign.name, но и поле campaign.resource_name, по которому будет выполнена сегментация.

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

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

В случае с ресурсом ad_group доступно более 50 сегментов. Однако список selectable_with для segments.hotel_check_in_date содержит гораздо меньше совместимых сегментов. Это означает, что если вы добавите поле segments.hotel_check_in_date в предложение SELECT, то ограничите доступные сегменты пересечением этих двух списков.

Ограничения для совместных сегментов

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

• Если вы выберете segments.ad_sub_network_type (этот параметр позволяет получить данные по подсетям рекламы на YouTube, таким как In-Stream, Shorts и объявления в фиде), вам также потребуется выбрать segments.ad_network_type.
• В версии 25 и более поздних при выборе параметра segments.ad_sub_format_type (который позволяет разбивать объявления In-Stream без возможности пропуска на YouTube по продолжительности) необходимо также выбрать параметр segments.ad_format_type.

Неявная фильтрация по выбранному сегменту

Когда вы выбираете в запросе определенные поля сегментов, Google Ads API может неявно отфильтровать результаты, чтобы включить только строки, в которых этот сегмент применим и имеет значение.

Влияние segments.keyword.*

Распространенный и важный пример такого поведения – выбор любого поля в segments.keyword (например, segments.keyword.info.text и segments.keyword.ad_group_criterion):

• Исключение трафика, не связанного с ключевыми словами. Если вы включите любое поле segments.keyword.* в предложение SELECT, то в результатах будут только строки, напрямую связанные с критерием группы объявлений по ключевым словам в поисковой сети.
• Затронутые типы кампаний. Данные из типов кампаний или групп объявлений, которые не зависят от ключевых слов для поисковой рекламы, исключаются из результатов. В частности, запрещено следующее:
  • Динамические поисковые объявления. Цели динамической рекламы основаны на контенте сайта, а не на ключевых словах.
  • Торговые кампании. В них вместо ключевых слов используются группы товаров.
  • Кампании с максимальной эффективностью. Хотя объявления из таких кампаний могут показываться в поисковой сети, отчеты по ним обычно не сегментируются по тем же критериям ключевых слов.
• Контекстно-медийная сеть. Поля segments.keyword.* относятся к ключевым словам, используемым в поисковой сети. Они не сегментируются по ключевым словам контекстно-медийной сети или другим методам таргетинга в ней.

Совет. Если вам нужно включить в анализ данные об эффективности динамических поисковых объявлений, торговых кампаний или других источников, не связанных с ключевыми словами для поисковой рекламы, не добавляйте в запрос поля из segments.keyword.*. Сначала проанализируйте данные по всем типам кампаний, а сегментацию по ключевым словам применяйте только при оценке эффективности ключевых слов в поисковой сети.

Правила для сегментов в условии WHERE

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

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

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

Сегменты segments.date, segments.week, segments.month, segments.quarter и segments.year работают следующим образом:

Важно! Подробные сегменты дат (segments.date, segments.week и segments.hour) поддерживают период ретроспективного анализа до 37 месяцев. Если запрос превышает этот диапазон, возвращается ошибка DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED в версии 24 и более поздних (или DateRangeError.UNKNOWN в версии 23). Для более ранних данных используйте segments.month, segments.quarter или segments.year.

• Эти сегменты можно отфильтровать в условии WHERE, не указывая их в условии SELECT.
• Если в условии SELECT есть любой из этих сегментов, то в условии WHERE необходимо указать конечный диапазон дат, состоящий из базовых сегментов дат. Сегменты дат не обязательно должны совпадать с указанными в SELECT.

Примеры

Недопустимый вариант. Поскольку в условии SELECT указано segments.date, в условии WHERE необходимо задать конечный диапазон дат для segments.date, segments.week, segments.month, segments.quarter или segments.year.	SELECT campaign.name, metrics.clicks, segments.date FROM campaign
Допустимый запрос. Возвращает названия кампаний и количество кликов, полученных за указанный диапазон дат. Обратите внимание, что segments.date не обязательно указывать в условии SELECT.	SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date >= '2024-01-01' AND segments.date <= '2024-01-31'
Правильный запрос. Возвращает названия кампаний и клики с сегментированием по дате для всех дней в указанном диапазоне.	SELECT campaign.name, metrics.clicks, segments.date FROM campaign WHERE segments.date >= '2024-01-01' AND segments.date <= '2024-01-31'
Допустимый запрос. Возвращает названия кампаний и клики с сегментацией по месяцам за все дни в указанном диапазоне дат.	SELECT campaign.name, metrics.clicks, segments.month FROM campaign WHERE segments.date >= '2024-01-01' AND segments.date <= '2024-01-31'
Допустимый запрос. Возвращает названия кампаний и клики с сегментированием по кварталам, а затем по месяцам за все месяцы в указанном диапазоне лет.	SELECT campaign.name, metrics.clicks, segments.quarter, segments.month FROM campaign WHERE segments.year >= 2020 AND segments.year <= 2024