ryandexdirect
Load Data From 'Yandex Direct'

Package index
Search the ryandexdirect package
Vignettes
Functions
68
Source code
39
Man pages
30
Home
/
CRAN
/
ryandexdirect
/
Загрузка статистики из рекламного аккаунта Яндекс Директ"

Загрузка статистики из рекламного аккаунта Яндекс Директ"
In ryandexdirect: Load Data From 'Yandex Direct' 

knitr::opts_chunk$set(
  eval = FALSE,
  collapse = TRUE,
  comment = "#>"
)

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

library(ryandexdirect)

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

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

Тип отчета

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

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

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

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

library(magrittr)
table_report_types <- data.frame(reptype = c("ACCOUNT_PERFORMANCE_REPORT", 
                                             "CAMPAIGN_PERFORMANCE_REPORT", 
                                             "ADGROUP_PERFORMANCE_REPORT",
                                             "AD_PERFORMANCE_REPORT",
                                             "CRITERIA_PERFORMANCE_REPORT",
                                             "CUSTOM_REPORT",
                                             "REACH_AND_FREQUENCY_PERFORMANCE_REPORT",
                                             "SEARCH_QUERY_PERFORMANCE_REPORT"), 
                                 descr    = c("Статистика по аккаунту рекламодателя",
                                              "Статистика по кампаниям",
                                              "Статистика по группам объявлений",
                                              "Статистика по объявлениям",
                                              "Статистика по условиям показа",
                                              "Статистика с произвольными группировками",
                                              "Статистика по медийным кампаниям. Отчет содержит только данные по кампаниям с типом «Медийная кампания», кампании остальных типов игнорируются",
                                              "Статистика по поисковым запросам"),
                                 grouping = c("–", 
                                              "CampaignId", 
                                              "AdGroupId",
                                              "AdId",
                                              "AdGroupId, CriteriaId, CriteriaType",
                                              "–",
                                              "В запросе на формирование отчета необходимо указать в поле FieldNames значение CampaignId", 
                                              "AdGroupId, Query"))

names(table_report_types) <- c("Тип отчёта", "Описание", "Добавляется группировка")
table_report_types <- kableExtra::kable(table_report_types)
kableExtra::kable_styling(table_report_types, bootstrap_options = c("striped", "hover"))

Во всех типах отчетов применяется единичная атрибуция (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 показов.

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

library(magrittr)
table_report_types <- data.frame(field = c("AdNetworkType, CampaignId, CampaignType", 
                                             "AdFormat, AdGroupId, AdId, Age, AudienceTargetId, CarrierType, ClickType, CriteriaType, CriterionType, Device, DynamicTextAdTargetId, ExternalNetworkName, Gender, LocationOfPresenceId, MatchType, MobilePlatform, Placement, RlAdjustmentId, Slot, SmartBannerFilterId, TargetingLocationId", 
                                             "Clicks, Conversions, ImpressionReach, Impressions",
                                             "AvgClickPosition, AvgCpc, AvgCpm, AvgImpressionFrequency, AvgImpressionPosition, AvgPageviews, AvgTrafficVolume, BounceRate, ConversionRate, Cost, CostPerConversion, Ctr, GoalsRoi, ImpressionShare, Profit, Revenue, WeightedCtr, WeightedImpressions, ",
                                             "Keyword, MatchedKeyword, Query"), 
                                 operators    = c("EQUALS, IN",
                                              "EQUALS, IN, NOT_EQUALS, NOT_IN",
                                              "EQUALS, IN, GREATER_THAN, LESS_THAN",
                                              "GREATER_THAN, LESS_THAN",
                                              "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"))

names(table_report_types) <- c("Имя поля", "Доступные операторы")
table_report_types <- kableExtra::kable(table_report_types)
kableExtra::kable_styling(table_report_types, bootstrap_options = c("striped", "hover"))

Все денежные значения в фильтрах следует указывать в виде целых чисел: сумм в валюте, умноженных на 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").



Try the ryandexdirect package in your browser

Any scripts or data that you put into this service are public.

ryandexdirect documentation built on March 31, 2023, 5:35 p.m.

R Package Documentation

rdrr.io home R language documentation Run R code online

Browse R Packages

CRAN packages Bioconductor packages R-Forge packages GitHub packages

We want your feedback!

Note that we can't provide technical support on individual packages. You should contact the package authors for that.
GitHub issue tracker
ian@mutexlabs.com
Personal blog

 
Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.

Close