Загрузка статистики из рекламного аккаунта Яндекс Директ

Alexey Seleznev

2023-03-17

Для начала работы с пакетом предварительно его требуется подключить.

library(ryandexdirect)

Для загрузки статистики =в пакете ryandexdirect предназначена функция yadirGetReport. Данная функция взаимодействует с API ‘Сервис Reports’, подробно о нём можно узнав в офйициальной документации, в текущей виньетке так же используется материал официальной спавки по работе с API сервиса ‘Reports’.

Аргументы функции yadirGetReports

Тип отчета

В параметре ReportType укажите тип отчета. Тип отчета влияет на набор доступных полей и группировку данных.

Например, если выбран тип отчета SEARCH_QUERY_PERFORMANCE_REPORT, то данные в отчете будут сгруппированы по идентификатору группы AdGroupId и поисковому запросу Query. Обратите внимание, что добавление группировок данных не приводит к автоматическому добавлению соответствующих полей в отчет: отчет содержит только поля, явным образом перечисленные в параметре FieldNames.

Наиболее общий тип отчета — CUSTOM_REPORT. Он не добавляет никаких дополнительных группировок.

Типы отчетов представлены в таблице.

Тип отчёта Описание Добавляется группировка
ACCOUNT_PERFORMANCE_REPORT Статистика по аккаунту рекламодателя –
CAMPAIGN_PERFORMANCE_REPORT Статистика по кампаниям CampaignId
ADGROUP_PERFORMANCE_REPORT Статистика по группам объявлений AdGroupId
AD_PERFORMANCE_REPORT Статистика по объявлениям AdId
CRITERIA_PERFORMANCE_REPORT Статистика по условиям показа AdGroupId, CriteriaId, CriteriaType
CUSTOM_REPORT Статистика с произвольными группировками –
REACH_AND_FREQUENCY_PERFORMANCE_REPORT Статистика по медийным кампаниям. Отчет содержит только данные по кампаниям с типом «Медийная кампания», кампании остальных типов игнорируются В запросе на формирование отчета необходимо указать в поле FieldNames значение CampaignId
SEARCH_QUERY_PERFORMANCE_REPORT Статистика по поисковым запросам AdGroupId, Query

Во всех типах отчетов применяется единичная атрибуция (single attribution): каждый показ и клик относится только к одному условию показа, региону, возрасту пользователя и т.д.

Период отчёта

Последняя рабочая неделя

Поля отчёта

Полный список допустимых полей можно найти в официальной документации.

Поля указываются в следующих параметрах отчета:

Наборы допустимых полей в этих параметрах различаются. Например, поле CampaignName может быть добавлено как столбец в отчете, но не может использоваться для фильтрации данных, а поле Keyword — наоборот, используется только для фильтрации данных и в отчете не выводится.

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

Каждое поле в зависимости от выбранного типа отчёта может иметь свой тип:

Например, поле CampaignId для типа отчета CUSTOM_REPORT является сегментом: если его добавить в отчет, данные будут сгруппированы по кампаниям. А для типа отчета ADGROUP_PERFORMANCE_REPORT поле CampaignId является атрибутом: данные уже сгруппированы по AdGroupId, а идентификатор кампании является для каждой группы фиксированным значением.

Фильтрация данных

Для фильтрации данных в отчете используйте аргумент FilterList. Каждый фильтр представляет собой критерий отбора данных. Фильтры объединяются по условию AND: в отчет попадают данные, для которых выполнены все фильтры. Фильтр состоит из трех параметров:

Например, чтобы отобрать в отчет строки, в которых количество целевых визитов больше 10, используйте фильтр FilterList = "Conversions GREATER_THAN 10". Для применения нескольких фильтров перечислите их выражения в векторе, например FilterList = c("Clicks GREATER_THAN 99","Impressions LESS_THAN 1000") оставит строки в которых более 99 кликов и менее 1000 показов.

Соответствие полей и операторов представлено в таблице.

Имя поля Доступные операторы
AdNetworkType, CampaignId, CampaignType EQUALS, IN
AdFormat, AdGroupId, AdId, Age, AudienceTargetId, CarrierType, ClickType, CriteriaType, CriterionType, Device, DynamicTextAdTargetId, ExternalNetworkName, Gender, LocationOfPresenceId, MatchType, MobilePlatform, Placement, RlAdjustmentId, Slot, SmartBannerFilterId, TargetingLocationId EQUALS, IN, NOT_EQUALS, NOT_IN
Clicks, Conversions, ImpressionReach, Impressions EQUALS, IN, GREATER_THAN, LESS_THAN
AvgClickPosition, AvgCpc, AvgCpm, AvgImpressionFrequency, AvgImpressionPosition, AvgPageviews, AvgTrafficVolume, BounceRate, ConversionRate, Cost, CostPerConversion, Ctr, GoalsRoi, ImpressionShare, Profit, Revenue, WeightedCtr, WeightedImpressions, GREATER_THAN, LESS_THAN
Keyword, MatchedKeyword, Query EQUALS, IN, NOT_EQUALS, NOT_IN, STARTS_WITH_IGNORE_CASE, STARTS_WITH_ANY_IGNORE_CASE, DOES_NOT_START_WITH_IGNORE_CASE, DOES_NOT_START_WITH_ALL_IGNORE_CASE

Все денежные значения в фильтрах следует указывать в виде целых чисел: сумм в валюте, умноженных на 1 000 000.

Цели

Вы можете запрашивать количество достижений каждой отдельно взятой цели с помощью аргумента Goals.

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

Если параметр указан, то в отчете вместо полей ConversionRate, Conversions, CostPerConversion, GoalsRoi и Revenue с агрегированными данными по всем целям будут выведены аналогичные поля с именами вида <поле><модель_атрибуции> и данными по каждой цели в отдельности.

Модели атрибуции

Модель атрибуции — это правило, какой переход считать источником визита:

Модели атрибуции, используемые при расчете данных по целям Яндекс.Метрики. Аргумент AttributionModels можно указать, только если указан параметр Goals. Если параметр Goals указан, а параметр AttributionModels — нет, по умолчанию используется значение LSC.

Если указано несколько моделей атрибуции, данные будут выведены по каждой модели в отдельности.

FetchBy разбивка запросов по времени

В сервисе ‘API Reports’ есть недокументированное ограничение на максимальное количество строк которое можно получить в ответе. По умолчанию оно равняется 1 000 000 строк. В большинстве случаев это незначительное ограничение, но при загрузке отчётов из больших аккаунтов с глубокой детализацией, за длительный период скорее всего вы столкнётесь с этой проблемой, и даже её не заметите.

Функция yadirGetReports столкнувшись с этим ограничением выведет уведомление 'You have reached the limits of Yandex.Direct API. Try to use "FetchBy" parameter with DateRangeType = "CUSTOM_DATE", "DateFrom" and "DateTo". If you are already using it, try to choose a smaller value.'.

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

Возможные значения: “DAY”, “WEEK”, “MONTH”, “QUARTER”, “YEAR”

Загрузка в таком случае потребует большего времени но вернёт полные данные.

Помимо уведомления, таблица которую вы получите в рзельтате работы функции yadirGetReports будет иметь атрибут limit_reached. В данном атрибуте хранится список логинов тех аккаунтов по котором был достигнул лимит при загрузке данных. Получить этот список можно с помощью attr(data, "limit_reached"), в том случае если объект с полученной статистикой имеет имя data, в другом случае attr(имя_полученного_объекта, "limit_reached").

Наиболее правильный вариант использования этого функцияала заключается в следующем:

  1. Создаём результирующий дата фрейм.
  2. Внутри цикла while запускает сбор статистики из любого колличества аккаунтов. Первый раз без разбивки запроса на временные интервалы.
  3. После загрузки данных проверяется атрибут limit_reached, на наличие аккаунтов достигших лимита.
  4. Из полученной таблицы со статистикой по всем аккаунтам исключаются данные по аккаунтам достигшим лимита.
  5. В результирующий фрем дописываются данные по аккаунтам НЕ достигшим лимита.
  6. Включаем следующий уровень временной разбивки, рекомедуемая последовательность: МЕСЯЦ -> НЕДЕЛЯ -> ДЕНЬ.
  7. Переходим на следующую итерации, запуская сбор статистики из аккаунтов которые без разбивки запроса достигли лимита.

Данный цикл должен работать до тех пор пока не будет выполненно одно из следующих условий:

  1. Мы получим данные в которых ни один аккаунт не достигнет лимита, и атрибут limit_reached будет пустым.
  2. При запуске сбора данных с подневной разбивкой отчёта всё равно будут аккаунты достигшие лимита.

Ниже приведён пример кода реализующего описанный выше механизм.

library(ryandexdirect)

# создаём результирующий фрейм
res   <- data.frame()

# список логинов
log_list <- c("login1", "login2","login3", "login4")

# проверка лиситов
# отмечаем что это первый запуск
check <- "first"

# создаём последовательность уровней временной разбивки запросов
fetching_seq <- c("OFF", "MONTH", "WEEK", "DAY")

# счётчик последовательностей разбивки
fetch_id <- 1

# запускаем цикл загрузки данных с проверкой лимитов
while ( ! is.null( log_list ) ) {
  
  # определяем уровень разбивки запроса
  if ( fetching_seq[fetch_id] == "OFF" ) fetching <- NULL else fetching <- fetching_seq[fetch_id]
  
  # запускаем сбор данных
  data <- yadirGetReport(DateRangeType = "CUSTOM_DATE", 
                         DateFrom      = "2018-06-01", 
                         DateTo        = "2019-05-31", 
                         FieldNames    = c("Date","CampaignName","Impressions","Clicks"),
                         Login         = log_list,
                         FetchBy       = fetching)
  
  # если загрузка была по одному аккаунту добавляем его логин
  if ( length(log_list) == 1 ) {
    data$Login <- log_list
  }
  
  # проверяем список аккаунтов достигших лимита
  log_list <- attr(data, "limit_reached")
  
  # выводим список аккаунтов достигших лимита
  print(log_list)
  
  # если есть аккаунты достигшие лимита
  if ( length(log_list) > 0 ) {
    # очищаем от них общую таблицу
    data <- data[ ! data$Login %in% log_list, ]
    # переключаем уровень разбивки на более мелкий
    fetch_id <- fetch_id + 1
  } 
  
  # дописываем в результирующий фрейм данные
  # по тем аккаунтам которые не упёрлись в лимит
  if ( nrow(data) > 0 ) {
    res <- dplyr::bind_rows(res, data)
  }
  
  # проверяем модно ли разбить запрос на более мелкие части
  if ( fetch_id > length(fetching_seq) && length(log_list) > 0 ) {
    message("Запрос невозможно разбить на меньшие части")
    message("Аккаунты которые достигли лимита при загрузке данных по дням: ", paste(log_list, collapse = ", "))
    limits_login <- log_list
    break
  }
}

Аргументы доступа к API Login, AgencyAccount, Token, TokenPath

Все перечисленные в заголовке аргументы используются для авторизации в API, хранении и использовании учётных данных. Более подробно о них можно узнать из виньетке посвящённой процессу авторизации, с помощью vignette("yandex-direct-auth", package = "ryandexdirect").