Новый API отчетов Search Ads 360 теперь доступен. Присоединяйтесь к группе Google searchads-api-announcements , чтобы быть в курсе предстоящих улучшений и выпусков.

Эта страница переведена с помощью Cloud Translation API.

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

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

Поисковая служба

API для создания отчетов в Search Ads 360 предоставляет специальную услугу для поиска и формирования отчетов.

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

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

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

Отправить запрос

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

Запрос представляет собой 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 , используйте раскрывающийся список «Да/Нет», чтобы отфильтровать недоступные метрики.

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

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

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

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

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

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

Сегментация

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

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

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

Результаты, возвращаемые функцией SearchAds360Service.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"
      }
    },
    ...
  ]
}

Список доступных полей сегментов можно найти в разделе 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 этого ресурса.

В этом примере запроса автоматически возвращается значение 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'

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

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

Заранее определенные даты
`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`	Семидневный период, начинающийся с предыдущего воскресенья.
`LAST_WEEK_MON_SUN`	Семидневный период, начинающийся с предыдущего понедельника.

Пример:

WHERE segments.date DURING LAST_30_DAYS

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

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

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

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

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

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