После настройки клиентского приложения, как описано в разделе «Мое первое приложение» , вы можете использовать API Search Ads 360 для запроса и скачивания отчетов. Вы можете сделать любой из следующих типов запросов:
- синхронный
Требуется всего один запрос и возвращает отчет в виде ответа в формате JSON. Синхронные запросы:
- Может возвращать только отчеты рекламодателей и системных аккаунтов.
- Заблокируйте своего клиента до тех пор, пока Search Ads 360 не сгенерирует отчет.
Если вы запрашиваете крупные отчеты по рекламодателям или системным аккаунтам, мы рекомендуем асинхронный подход.
- Асинхронный
Требуется отправить первоначальный запрос, в котором указаны данные, которые вы хотите включить в отчет. Затем вы отправляете дополнительные запросы на опрос Search Ads 360. Когда Search Ads 360 завершает создание отчета, вы отправляете запросы на загрузку отчета в виде одного или нескольких файлов. Асинхронные запросы:
- Может возвращать любой тип отчета
- Разбивает очень большие отчеты на несколько файлов.
- Форматирует отчеты как CSV или TSV.
Модель данных: строки и столбцы
Search Ads 360 упорядочивает данные в отчете по строкам и столбцам. Тип запрашиваемого отчета определяет возвращаемые строки . Например, если вы запросите отчет по ключевым словам, каждая строка будет содержать данные об одном ключевом слове. Список всех типов отчетов см. в справочнике по типам отчетов. Вы указываете, какие столбцы вы хотите видеть в отчете, называя каждый столбец в запросе отчета. Список столбцов, которые могут быть возвращены для каждого типа отчета, см. в справочнике по типам отчетов .
Поведение столбца
Поведение столбца зависит от типа данных, содержащихся в столбце (ссылка «Типы отчетов» отображает поведение каждого столбца):
Столбцы атрибутов . Столбец атрибутов содержит данные, которые настраивают или идентифицируют объект в кампании, например название кампании или ставку ключевого слова. API Search Ads 360 всегда возвращает текущее значение столбца атрибута независимо от даты или диапазона дат, указанных в запросе. Например, если вчера вы изменили ставку ключевого слова с 2,00 на 1,50, а затем запросили отчет по данным за прошлый месяц, отчет вернет значение 1,50 для ставки ключевого слова.
Метрические столбцы . Столбец показателей содержит данные об эффективности вашей кампании, например количество кликов по объявлению, количество посещений, зафиксированное тегом Floodlight, или доход. Если вы не укажете диапазон времени в один день, API вернет совокупное значение для столбцов показателей. Например, если вы запросите отчет по данным за прошлый месяц, API вернет общее количество кликов за последний месяц.
Сегментировать столбцы . Столбец сегмента разбивает данные на отдельные строки. Например,
date— это столбец сегмента, который можно указать для многих типов отчетов. Если вы укажете столбецdateв отчете по ключевым словам с диапазоном дат с 1 января 2013 г. по 07 января 2013 г., API вернет семь строк для каждого ключевого слова, каждая из которых соответствует одному дню и отображает показатели для этого дня. См. Сегментированные отчеты .
Валюты
В запросе отчета необходимо указать валюту денежных данных (как атрибутов, таких как dailyBudget , так и таких показателей, как cost ). Вы можете указать одно из следующих:
- Валюта агентства, если область действия отчета ограничена агентством, рекламодателем или учетной записью системы.
- Валюта рекламодателя, если область действия отчета ограничена учетной записью рекламодателя или системы.
- Валюта системного аккаунта, если область действия отчета ограничена системным аккаунтом.
- доллар США
Используйте свойство запроса Reports.request.statisticsCurrency , чтобы указать валюту.
В самом отчете валюта будет указана в свойстве Reports.statisticsCurrencyCode .
Часовой пояс
Показатели Search Ads 360 хранятся в датах без часовых поясов. Эти даты соответствуют часовому поясу системного аккаунта для показателей системы (таких как клики, показы и посещения) и часовому поясу сети Менеджера кампаний для показателей конверсий (таких как действия, транзакции и доход). Если все показатели в отчете относятся к одному и тому же часовому поясу, этот часовой пояс будет возвращен в запросе. В противном случае часовой пояс не будет возвращен. В ваших запросах можно установить Reports.request.verifySingleTimeZone : true , чтобы отклонить отчеты, в которых представлены показатели из более чем одного часового пояса.
Если все метрики, присутствующие в отчете, относятся к одному часовому поясу, этот часовой пояс возвращается в Reports.statisticsTimeZoneReports .