Прочтите разделы ниже, чтобы узнать, как создавать отчеты о поиске в 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
Сделать запрос
Чтобы отправить запрос, вам необходимо передать 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
Поле 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
, где приведен список доступных полей сегментов, которые вы можете использовать.
Несколько сегментов
Вы можете указать несколько сегментов в предложении 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 | Предыдущая 5-дневная рабочая неделя (с понедельника по пятницу). |
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.