Основные сведения об отчетах

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

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

Полный список типов отчетов, доступных в AdWords API, см. здесь.

Обзор

Вот как создать отчет через API:

  1. Создайте определение отчета. Оно представляет собой фрагмент кода в формате XML или AWQL, определяющий параметры отчета, включая его название, типы информации, формат скачивания и т. д.
  2. Оформите определение отчета в виде HTTP-запроса POST и передайте его на сервер AdWords.

Далее эти действия описаны более подробно.

Как создать определение отчета

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

Определения отчетов можно создавать на XML или AWQL (языке запросов AdWords).

The sections below cover XML–based report definitions. Если вы предпочитаете AWQL, ознакомьтесь с разделом, посвященным отчетности, в руководстве по AWQL.

Ниже приведен пример определения отчета в формате XML. Далее представлена таблица, в которой описывается каждый элемент определения отчета.

XML

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
  <selector>
<fields>CampaignId</fields>
<fields>AdGroupId</fields>
<fields>Impressions</fields>
<fields>Clicks</fields>
<fields>Cost</fields>
<predicates>
  <field>AdGroupStatus</field>
  <operator>IN</operator>
  <values>ENABLED</values>
  <values>PAUSED</values>
</predicates>
  </selector>
  <reportName>Custom Adgroup Performance Report</reportName>
  <reportType>ADGROUP_PERFORMANCE_REPORT</reportType>
  <dateRangeType>LAST_7_DAYS</dateRangeType>
  <downloadFormat>CSV</downloadFormat>
</reportDefinition>

AWQL

SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost
FROM ADGROUP_PERFORMANCE_REPORT
WHERE AdGroupStatus IN [ENABLED, PAUSED]
DURING LAST_7_DAYS
Элемент определения отчета Описание
<reportDefinition> Заголовок определения отчета. Используйте тот же URL, который отображается в запросе, и убедитесь, что указана правильная версия API.
<selector> Раздел <selector> содержит список полей (fields) с элементами, которые нужно выбрать и включить в отчет. Подробнее о возможных значениях читайте на странице Типы отчетов. Обратите внимание, что список доступных полей зависит от значения поля reportType.

Список доступных полей можно также получить программным путем, используя метод ReportDefinitionService.getReportFields().

<predicates> Предикаты соответствуют фильтрам в пользовательском интерфейсе AdWords. Они включают поле отчета, операторы и значения. Предикаты обрабатываются как инклюзивные условия (AND).
<reportType> Тип запрашиваемого отчета. Подробнее читайте на странице Типы отчетов.
<dateRangeType> Диапазон дат, который должен охватывать отчет. Подробнее читайте в разделе Диапазоны дат ниже.
<downloadFormat> Формат, в котором нужно скачать отчет. Подробнее читайте в разделе Поддерживаемые форматы скачивания ниже.

Определение схемы XML

Определение схемы XML (XSD), описывающее структуру reportDefinition, можно найти по следующему адресу:

https://adwords.google.com/api/adwords/reportdownload/v201609/reportDefinition.xsd

Поддерживаются оба варианта Content-Type: application/x-www-form-urlencoded и multipart/form-data. В первом случае для XML необходимо использовать кодировку URL.

Диапазоны дат

Чтобы задать диапазон дат для отчета, используйте ReportDefinition.DateRangeType из XSD определения отчета.

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

Для каждого ReportDefinition.DateRangeType, кроме CUSTOM_DATE, обязательным является лишь dateRangeType.

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
    ...
  <dateRangeType>LAST_7_DAYS</dateRangeType>
</reportDefinition>

Произвольные диапазоны дат

Чтобы задать произвольный диапазон дат, выполните следующие действия:

  1. Укажите CUSTOM_DATE в качестве dateRangeType.
  2. Укажите dateRange с минимальным (min) и максимальным (max) значениями в формате YYYYMMDD в разделе selector.

XML

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
  <selector>
...
<dateRange>
  <min>20150201</min>
  <max>20150301</max>
</dateRange>
  </selector>
  <dateRangeType>CUSTOM_DATE</dateRangeType>
</reportDefinition>

AWQL

...
DURING 20150201,20150301

Актуальность данных

Часть статистики в ваших отчетах рассчитывается непрерывно, тогда как другие значения определяются раз в день. Это один из аспектов обновления данных в AdWords. Чтобы использовать отчеты с максимальной пользой, ознакомьтесь со статьей Актуальность данных.

Подготовка запроса

Создав определение отчета, можно перейти к подготовке HTTP-запроса POST.

Вы можете использовать обычные HTTP-запросы с синхронными обращениями непосредственно к серверу AdWords. Этот метод связан с меньшими затратами вычислительных ресурсов, поэтому он больше подходит для крупных отчетов, особенно при использовании нескольких потоков (мы рекомендуем начинать с 10). HTTP-запрос является синхронным, поскольку вызов эффективно блокируется до тех пор, пока не будут готовы данные отчета.

Скорее всего, предельно допустимое количество запросов в секунду (RateExceededError) будет достигнуто до превышения числа открытых подключений, разрешенных на сервере. Запросы отчетов не засчитываются в ежедневную квоту операций, однако существует предельное число скачиваний отчетов в день.

Если используется определение отчета в формате XML, его следует назначить параметру __rdxml в теле запроса POST.

Заголовки запроса

При скачивании отчетов следует использовать обычные значения HTTP-заголовков.

Заголовок HTTP Описание
Authorization: Bearer OAUTH2_ACCESS_TOKEN Авторизация для скачивания отчета. Следует указывать тот же accessToken, который используется для заголовка SOAP-запроса.
developerToken: DEVELOPER_TOKEN Ваш идентификатор разработчика, содержащий уникальную строку, например 1a2B3c4D5e_-6v7w8x9y0z.
clientCustomerId: CLIENT_CUSTOMER_ID Идентификатор клиента в клиентском аккаунте.

Ниже приведены необязательные HTTP-заголовки, с помощью которых можно контролировать включение в отчет строки заголовка или итоговых значений.

Необязательный HTTP-заголовок Описание
skipReportHeader: true|false При значении true строка заголовка с названием отчета и диапазоном дат не включается. Если значение не задано или равно false, отчет будет содержать строку заголовка.
skipColumnHeader: true|false При значении true строка заголовка с названиями полей не включается. Если значение не задано или равно false, отчет будет содержать названия полей.
skipReportSummary: true|false При значении true строка итоговых значений не включается. Если значение не задано или равно false, отчет будет содержать строку итоговых значений.
useRawEnumValues: true|false При значении true будет возвращено значение в формате enum, например IMAGE_AD вместо Image ad. Если задано значение false либо заголовок не указан, будет возвращено отображаемое значение.
includeZeroImpressions: true|false При значении true в отчет включаются строки, где во всех заполненных полях показателей стоит ноль, при условии что запрашиваемые поля и предикаты поддерживают нулевое количество показов. Если задано значение false, таких строк не будет. Следовательно, даже если этому заголовку соответствует значение false и показатель Impressions в строке равен 0, но какие-либо из заданных полей показателей имеют ненулевые значения, строка возвращается. О том, что произойдет, если этот заголовок отсутствует, читайте в статье Отчеты с нолем показов.

URL HTTP-запроса

Запрос содержит HTTP-метод POST и обращается к серверу AdWords по следующему URL:

https://adwords.google.com/api/adwords/reportdownload/v201609

Полный пример

Ниже приведен полный пример определения отчета, оформленного в виде HTTP-запроса POST.

XML

POST /api/adwords/reportdownload/v201609 HTTP/1.1
Host: adwords.google.com
User-Agent: curl, gzip
Accept: /
Accept-Encoding: gzip
Authorization: Bearer [Enter OAuth 2.0 access token here]
developerToken: [Enter developerToken here]
clientCustomerId: [Enter clientCustomerID here]
Content-Length: 784
Expect: 100-continue
Content-Type: multipart/form-data; boundary=------------------------12d01fae60c7b559

Parameters:
__rdxml: &lt;?xml version="1.0" encoding="UTF-8"?&gt;
<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
  <selector>
    <fields>CampaignId</fields>
    <fields>AdGroupId</fields>
    <fields>Impressions</fields>
    <fields>Clicks</fields>
    <fields>Cost</fields>
    <predicates>
      <field>AdGroupStatus</field>
      <operator>IN</operator>
      <values>ENABLED</values>
      <values>PAUSED</values>
    </predicates>
  </selector>
  <reportName>Custom Adgroup Performance Report</reportName>
  <reportType>ADGROUP_PERFORMANCE_REPORT</reportType>
  <dateRangeType>LAST_7_DAYS</dateRangeType>
  <downloadFormat>CSV</downloadFormat>
</reportDefinition>

AWQL

POST /api/adwords/reportdownload/v201609 HTTP/1.1
Host: adwords.google.com
User-Agent: curl, gzip
Accept: */*
Accept-Encoding: gzip
Authorization: Bearer [Enter OAuth 2.0 access token here]
developerToken: [Enter developerToken here]
clientCustomerId: [Enter clientCustomerID here]
Content-Length: 182
Expect: 100-continue
Content-Type: multipart/form-data; boundary=------------------------12d01fae60c7b559
 
Parameters:
__fmt: CSV
__rdquery: SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost \
FROM ADGROUP_PERFORMANCE_REPORT \
WHERE AdGroupStatus IN [ENABLED, PAUSED] DURING LAST_7_DAYS

Коды ответа

При успешном запросе отчета сервер возвращает код ответа 200.

Код ответа 400 указывает на ошибку API: проверьте правильность XML-кода в определении отчета.

Код ответа 500 обычно означает временные проблемы с сервером. В этом случае попробуйте повторно отправить запрос через некоторое время.

Отчеты по нескольким аккаунтам

Запрос отчета может включать данные только по одному аккаунту AdWords. Если вам нужна информация по нескольким аккаунтам, отправьте отдельные запросы для каждого из них, задав значение заголовка clientCustomerId (см. выше).

Превышение времени ожидания

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

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

Поддерживаемые форматы скачивания

Формат Описание
CSVFOREXCEL Формат Unicode с соответствующей отметкой порядка байтов для Excel. Разделитель по умолчанию для Unicode в Excel – символ табуляции. Если используется запятая, все данные из строки будут выделены в отдельный столбец (по умолчанию).
CSV Формат вывода CSV (значения, разделенные запятыми).
TSV Формат вывода TSV (значения, разделенные табуляцией).
XML Формат вывода XML.
GZIPPED_CSV Формат вывода в виде GZIP-архива CSV (значения, разделенные запятыми).
GZIPPED_XML Формат вывода в виде GZIP-архива XML.

Как правильно выбрать отчет

Из-за большого выбора отчетов, доступных в AdWords API, может быть нелегко решить, какой из них нужен именно в вашем случае.

Воспользуйтесь приведенной ниже таблицей, чтобы выбрать самый подходящий отчет, а затем прочитайте о нем подробнее на странице Типы отчетов.

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

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

В интерфейсе AdWords для управления сегментами данных существует отдельное меню. Чтобы решить аналогичные задачи с помощью API, достаточно добавить в отчет нужное поле. Например, если вы добавите поле AdNetworkType1 в отчет по эффективности групп объявлений, в нем будут представлены строки с показателями (клики, показы, переходы и т. д.) по каждой группе объявлений в той или иной рекламной сети. В интерфейсе можно одновременно просматривать только один сегмент данных, тогда как API позволяет включать в отчет сразу несколько сегментов. Однако помните, что при добавлении в отчет новых сегментов количество строк в нем может расти в геометрической прогрессии.

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

При сегментировании учитываются уникальные ключи отчетов. Например, отчет по эффективности ключевых слов неявным образом сегментируется по Id и AdGroupId, хотя они и не указаны в полях селектора, поскольку ключевое слово идентифицируется как по Id, так и по AdGroupId.

Keyword,MatchType,Impressions
Keyword1,Exact,3
Keyword2,Exact,10
Keyword3,Exact,5
Keyword4,Broad,4

Единичная и множественная атрибуция

Критерии, имеющие отношение к показу в контекстно-медийной сети, можно учитывать с помощью единичной или множественной атрибуции.

Единичная атрибуция

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

Каждый показ учитывается только один раз (по одному критерию). Значения, полученные в результате сложения всех критериев, соответствуют строкам "Итого" в нескольких отчетах об атрибуции.

Эта модель работает для отчетов по эффективности критериев и ключевых слов.

Пример отчета

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

Keyword / Placement,Impressions
www.example.com,2
www.example.ca,2
www.example.net,2
Computers & Electronics,2
Sports,2

Множественная атрибуция

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

Например, в отчете по эффективности гендерных групп все показы суммируются по полу, в отчете по эффективности возрастных групп – по возрасту, и так далее. Эта же модель используется в отчетах по эффективности тем и мест размещения.

В отличие от отчетов с единичной атрибуцией, отчеты с множественной атрибуцией НЕЛЬЗЯ объединять: это приведет к двойному учету показов и кликов.

Пример

Topic,Impressions
Computers & Electronics,6
Sports,4

Placement,Impressions
www.example.com,4
www.example.ca,3
www.example.net,3

Если вы используете таргетинг только на тематику сайтов и места размещения, в отчете по темам в КМС у каждой темы, инициирующей показы, будет отдельная строка. Точно так же в отчете по эффективности мест размещения каждому показу будет соответствовать своя строка. В этих отчетах учитываются одни и те же показы, потому что с каждым из них связывается одна тема и одно место размещения.

KeywordId=3000000

В отчетах с единичной атрибуцией вместо фактических ключевых слов, инициировавших показы в контекстно-медийной сети, будет указано специальное ключевое слово Content с идентификатором 3000000.

Пример
Keyword ID,Impressions
23458623485,2
23655322314,2
23953456345,2
3000000,4

Если объявления показываются только в КМС, а таргетинг настроен на ключевые слова и места размещения, в отчет по эффективности рекламы будут добавлены строки по каждому объявлению, связанному с инициирующим критерием для мест размещения, а также одна строка с объявлением и идентификатором 3000000. В ней будут учитываться все ключевые слова в КМС, вызвавшие показ объявления. Обратите внимание, что в отчете с единичной атрибуцией выбирается ключевое слово, а не место размещения.

KeywordId=3000004

Идентификатор критерия 3000004 использовался для функции, которая уже удалена из AdWords.

KeywordId=3000006

Идентификатор критерия 3000006 указывает на статистику, связанную с Оптимизатором кампаний в КМС.

Формат различных полей

Для каждого поля в отчетах установлен свой тип (Type), однако значения в полях могут возвращаться в другом формате. Всегда проверяйте столбец Notes (Примечания): он часто содержит дополнительную информацию об ожидаемом формате значений. Например, в столбце Notes для ConversionRate может быть указано: Percentage returned as "x.xx%" (Проценты отображаются в формате "x.xx%").

Поля Money в отчетах

Значения в полях Money отображаются в микроединицах, но могут иметь префикс auto. Например, 1,23 руб. в отчете будет выглядеть как 1230000 (1,23 x 1 000 000). Микроединицы всегда рассчитываются на основании местной валюты аккаунта.

При фильтрации по полям Money значения должны быть выражены микроединицами. Например, код WHERE AverageCpc > 1000000 сформирует отчет со строками, в которых AverageCpc больше одной единицы валюты аккаунта, например рубля.

Показатель качества в отчетах

Показатель качества в отчетах по эффективности ключевых слов и критериев представлен в виде значения от 1 до 10 (чем больше, тем выше эффективность).

В более ранних версиях для ключевых слов с недостаточным количеством показов или кликов возвращалось значение 6. Это могут быть, например, новые ключевые слова или старые, но долго бывшие неактивными. Для удаленных ключевых слов и ключевых слов в КМС, показатель качества которых не удалось установить, возвращалось значение 0. Начиная с версии 201607 для недоступных показателей используются два дефиса: --. Кроме того, был добавлен новый столбец HasQualityScore, чтобы вы могли сразу отфильтровать ключевые слова без показателя качества. Вот пример запроса AWQL, который выбирает только ключевые слова с действительным показателем качества:

SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, QualityScore FROM
    CRITERIA_PERFORMANCE_REPORT WHERE Status IN [ENABLED, PAUSED] and
    HasQualityScore='TRUE'

Два дефиса

Два дефиса означают, что для ячейки нет значения.

Списки и карты

Элементы списка форматируются с использованием JSON. Например, значение Scheduling из отчета PLACEHOLDER_FEED_ITEM_REPORT будет состоять из массива строк:

["Monday, 6:00PM - 9:00PM","Tuesday, 6:00PM - 9:00PM","Wednesday,6:00PM - 9:00PM",
"Thursday, 6:00PM - 9:00PM","Friday, 6:00PM - 9:00PM"]

Для карт (например, UrlCustomParameters) используется тот же формат:

{"param0":"value0","param1":"value1"}

Оставить отзыв о...

Текущей странице
Нужна помощь? Обратитесь в службу поддержки.