Создавайте отчеты о поиске в Search Ads 360 Reporting API.

Прочтите разделы ниже, чтобы узнать, как создавать отчеты о поиске в Search Ads 360 Reporting API.

Служба поиска

API отчетов Search Ads 360 предоставляет специальный сервис для поиска и составления отчетов.

SearchAds360Service — это унифицированная служба поиска объектов и создания отчетов, которая предоставляет два метода поиска: SearchStream и Search . Поисковые запросы передаются в строке запроса, написанной на языке запросов Search Ads 360 . Вы можете определить запросы для:

• Извлечение определенных атрибутов объектов.
• Получите показатели производительности для объектов на основе диапазона дат.
• Упорядочивайте объекты по их атрибутам.
• Фильтруйте результаты, используя условия, определяющие, какие объекты возвращать.
• Ограничьте количество возвращаемых объектов.

Оба метода поиска возвращают все строки, соответствующие вашему запросу. Например, когда вы получаете campaign.id , campaign.name и metrics.clicks , API возвращает SearchAds360Row , содержащий объект кампании с установленными полями id и name , а также объект metrics с набором полей clicks .

Методы поиска

SearchStream

Отправляет один запрос и инициирует постоянное соединение с API отчетов Search Ads 360 независимо от размера отчета.

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

Search

Отправляет несколько запросов с разбивкой на страницы для загрузки всего отчета.

SearchStream обычно обеспечивает более высокую производительность, поскольку исключает время прохождения по сети, необходимое для запроса отдельных страниц. Мы рекомендуем использовать SearchStream для всех отчетов, содержащих более 10 000 строк. Для отчетов меньшего размера (<10 000 строк) между этими методами нет существенной разницы в производительности.

Используемый вами метод не влияет на квоты и ограничения API: один запрос или отчет считается за одну операцию независимо от того, являются ли результаты страничными или потоковыми.

Пример поискового запроса

В этом примере запроса возвращаются данные об эффективности аккаунта за последние 30 дней по кампаниям, сегментированные по устройствам:

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Примечание. Язык запросов Search Ads 360 предоставляет подробную информацию о том, как использовать каждое предложение поискового запроса.

Обратиться с просьбой

Чтобы отправить запрос, вам необходимо передать customer_id и строку query в интерфейс SearchAds360Service.SearchStream или SearchAds360Service.Search .

Примечание. В приведенных ниже примерах показан базовый запрос HTTP/JSON. Это используется для демонстрации концепций. Мы рекомендуем вам использовать наши клиентские библиотеки , основанные на gRPC, для отправки запросов в вашем собственном приложении.

Запрос состоит из HTTP POST к серверу API отчетов Search Ads 360 по одному из следующих URL-адресов:

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

Вот полный пример определения отчета для searchStream , заключенного в запрос HTTP POST :

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

Обработать ответ

SearchAds360Service возвращает список объектов SearchAds360Row .

Каждая SearchAds360Row представляет объект, возвращаемый запросом. Каждый объект состоит из набора атрибутов, которые заполняются на основе полей, запрошенных в предложении SELECT запроса. Атрибуты, не включенные в предложение SELECT , не заполняются в объектах ответа.

Например, приведенный ниже запрос заполняет каждый объект SearchAds360Row только campaign.id , campaign.name и campaign.status . Другие атрибуты, такие как campaign.engine_id или campaign.bidding_strategy_type , опущены.

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

Справочная документация

Раздел «Справочник» содержит всю информацию, необходимую для правильного использования каждого артефакта. Для каждого ресурса существует одна страница, например ad_group и campaign . На страницах segments и metrics перечислены все доступные поля сегментов и показателей.

Некоторые ресурсы, сегменты и показатели несовместимы и не могут использоваться вместе, тогда как другие полностью совместимы и дополняют друг друга. Каждая страница ресурса включает следующую информацию (если она доступна и уместна) и многое другое:

Приписанные ресурсы

Для некоторых ресурсов у вас может быть возможность неявно присоединиться к связанным ресурсам, выбрав их поля вместе с полями ресурса в предложении FROM . Например, ресурс campaign является атрибутом ресурса ad_group . Это означает, что вы можете включать такие поля, как campaign.id и campaign.bidding_strategy_type в свой запрос при использовании ad_group в предложении FROM .

В разделе «Атрибутивные ресурсы» перечислены доступные атрибутированные ресурсы. Не всем ресурсам присвоены ресурсы.

Столбец полей ресурсов

Все поля ресурса включены в столбец Поля ресурса . Каждое поле ресурса содержит ссылку на более подробную информацию о поле, включая его описание, категорию, тип данных, URL-адрес типа, а также фильтруемые, выбираемые, сортируемые и повторяющиеся настройки.

Столбец «Сегменты»

Не все поля сегментов можно выбрать для данного ресурса.

В столбце «Сегменты» перечислены поля segments , которые можно использовать в том же предложении SELECT , что и поля ресурса. Каждое поле содержит ссылку на полную информацию о поле, включая его описание, категорию, тип данных, URL-адрес типа, а также фильтруемые, выбираемые, сортируемые и повторяющиеся настройки. Если вы используете ресурс в предложении FROM , вы можете использовать раскрывающийся список «Да/Нет» , чтобы отфильтровать недоступные сегменты.

Столбец показателей

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

В столбце «Метрики» перечислены поля metrics , которые можно использовать в том же предложении SELECT , что и поля ресурса. Каждое поле содержит ссылку на полную информацию о поле, включая его описание, категорию, тип данных, URL-адрес типа, а также фильтруемые, выбираемые, сортируемые и повторяющиеся настройки. Если вы используете ресурс в предложении FROM , используйте раскрывающийся список «Да/Нет» , чтобы отфильтровать недоступные метрики.

Примечание. При получении показателей, связанных с валютой (например, Cost_micros), для определенной даты или диапазона дат обязательно включите сегменты.дата в предложение SELECT.

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

Некоторые ресурсы имеют поля ресурсов сегментирования, которые вы можете выбрать, когда ресурс находится в предложении FROM . Например, если вы выберете поле ресурса campaign , например campaign.name , при использовании campaign_budget в предложении FROM автоматически будет возвращено и сегментировано значение campaign.resource_name , поскольку campaign является сегментирующим ресурсом campaign_budget .

В разделе Ресурсы сегментации перечислены доступные ресурсы сегментации. Не все ресурсы имеют ресурсы сегментации.

Выбирается с помощью

Некоторые поля segments несовместимы с другими ресурсами, сегментами и показателями.

Страница segments содержит поле «Выбираемый с возможностью расширения для каждого segments », в котором перечислены все совместимые поля ресурсов, поля metrics и другие поля segments , которые вы можете включить в предложение SELECT .

Примечание. Чтобы узнать, как использовать каждое предложение запроса, ознакомьтесь с языком запросов Search Ads 360 .

Сегментация

Вы можете сегментировать результаты поиска, добавив segments. FIELD_NAME Поле segments. FIELD_NAME в предложение SELECT вашего запроса.

Например, segments.device в запросе ниже дает отчет со строкой impressions каждого устройства для ресурса, указанного в предложении FROM .

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

Результаты, возвращаемые SearchAds360Service.SearchStream , выглядят примерно так:

{
  "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"
      }
    },
    ...
  ]
}

См. segments , где приведен список доступных полей сегментов, которые вы можете использовать.

Несколько сегментов

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

Вы можете указать несколько сегментов в предложении SELECT вашего запроса. Ответ содержит один объект SearchAds360Row для каждой комбинации экземпляра основного ресурса, указанного в предложении FROM , и значения каждого выбранного поля segment .

Например, следующий запрос вернет одну строку для каждой комбинации campaign , segments.ad_network_type и segments.date .

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

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

Результатом запроса в следующем примере является одна строка для каждой кампании, а не одна строка для каждого отдельного значения поля campaign.status .

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

Неявная сегментация

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

Примечание. Поле resource_name ресурса в предложении FROM всегда возвращается, даже если оно не указано в предложении SELECT . См. поле resource_name для получения дополнительной информации.

Этот пример запроса автоматически возвращает 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"
      }
    }
  ]
}

Сегменты основных дат

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

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

Этот пример запроса возвращает показатели clicks кампании за последние 30 дней.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Поля сегментов базовой даты являются исключением из общего правила, согласно которому вы не можете использовать поле сегментов в предложении WHERE , если вы также не включите это поле в предложение SELECT . Дополнительную информацию см. в разделе Запрещенная фильтрация .

Правила сегмента основных дат:

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

  Этот пример запроса возвращает показатели clicks по названию кампании в течение диапазона дат. Обратите внимание, что segments.date не включен в предложение SELECT .

  SELECT
      campaign.name,
      metrics.clicks
  FROM campaign
  WHERE segments.date > '2022-02-01'
    AND segments.date < '2022-03-01'
  

• Если вы включаете основное поле даты в предложение SELECT , вы должны указать конечную дату или диапазон дат в предложении WHERE . Поля, указанные в предложениях SELECT и WHERE , не обязательно должны совпадать.

  Этот пример запроса возвращает показатели clicks по названию кампании, сегментированные по месяцам, для всех дней в диапазоне дат.

  SELECT
    campaign.name,
    metrics.clicks,
    segments.month
  FROM campaign
  WHERE segments.date > '2022-02-01'
    AND segments.date < '2022-03-01'
  

Даты ISO 8601

Вы можете использовать формат YYYY-MM-DD (ISO 8601) для указания дат и диапазонов дат, например:

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

Для основных сегментов дат, для которых требуется период времени ( segments.week , segments.month , segments.quarter ), вы можете использовать оператор = с первым днем ​​периода времени, например:

WHERE segments.month = '2022-06-01'

Примечание. Если вы укажете дату, которая не является первым днем ​​периода, вы получите ошибку MISALIGNED_DATE_FOR_FILTER .

Предопределенные даты

Вы также можете использовать следующие предопределенные даты и диапазоны дат:

Предопределенные даты
TODAY	Только сегодня.
YESTERDAY	Только вчера.
LAST_7_DAYS	Предыдущие 7 дней, не считая сегодняшнего.
LAST_BUSINESS_WEEK	Предыдущая пятидневная рабочая неделя (с понедельника по пятницу).
THIS_MONTH	Все дни текущего месяца.
LAST_MONTH	Все дни предыдущего месяца.
LAST_14_DAYS	Предыдущие 14 дней, исключая сегодняшний день.
LAST_30_DAYS	Предыдущие 30 дней, исключая сегодняшний день.
THIS_WEEK_SUN_TODAY	Период между предыдущим воскресеньем и текущим днем.
THIS_WEEK_MON_TODAY	Период между предыдущим понедельником и текущим днем.
LAST_WEEK_SUN_SAT	7-дневный период, начиная с предыдущего воскресенья.
LAST_WEEK_MON_SUN	7-дневный период, начиная с предыдущего понедельника.

Пример:

WHERE segments.date DURING LAST_30_DAYS

Нулевые показатели

При выполнении запроса вы можете встретить метрики со значением 0 для некоторых сущностей. Узнайте, как обрабатывать нулевые показатели в ваших запросах .

НЕИЗВЕСТНЫЕ типы перечислений

Если ресурс возвращается с типом данных перечисления UNKNOWN , это означает, что этот тип не полностью поддерживается в версии API. Эти ресурсы могли быть созданы через другие интерфейсы. Например, новая кампания или объявление появилось в пользовательском интерфейсе Search Ads 360, но еще не поддерживается в запрашиваемой версии API.

Вы по-прежнему можете выбирать метрики, если ресурс имеет тип UNKNOWN , но вам необходимо учитывать следующее:

• Ресурс типа UNKNOWN может поддерживаться позже, но он может оставаться UNKNOWN на неопределенный срок.
• Новые объекты типа UNKNOWN могут появиться в любое время. Эти объекты обратно совместимы, поскольку значение перечисления уже доступно. Мы представляем ресурсы с этим изменением по мере их доступности, чтобы вы имели точное представление о своей учетной записи. UNKNOWN ресурс может появиться из-за новой активности в вашей учетной записи через другие интерфейсы или из-за того, что ресурс больше не поддерживается формально.
• UNKNOWN ресурсы могут иметь прикрепленные к ним подробные метрики, которые вы можете запросить.
• UNKNOWN ресурсы обычно полностью видны в пользовательском интерфейсе Search Ads 360.