ryandexdirect 3.0.0 — обновлённый R клиент для работы с API Яндекс Директ

Пакет для работы с API Яндекс Директ на языке R, ryandexdirect был значительно доработан:

• Был улучшен процесс авторизации в API
• Приведёны в порядок имена аргументов функций
• Во все функции был добавлен ряд новых аргументов

Эта статья содержит все основные обновления доступные в версии 3.0.0.

В конце статьи приведены примеры кода для загрузки статистики из рекламных аккаунтов Яндекс Директ.

Информация приведённая в текущей статье рассчитана на пользователей, знакомых с более старыми версиями пакета ryandexdirect, и её цель является описать нововведения и доработки принятые в версии 3.0.0, для тех кто ранее не сталкивался с функциями и приёмами работы с данным пакетом рекомендую изначально ознакомится с официальной документацией оп работе с ryandexdirect.

Обновление пакета

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

install.packages("devtools")

devtools::install_github("selesnow/ryandexdirect")

Авторизация и работа с токенами

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

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

В пакет добавлена новая функция для прохождения аутентификации в API yadirAuth, но отдельно вызывать её для получения токена больше не требуется, при любом обращении к API если вы в используемой функции явно не указываете никакой токен, любая функция пакета сначала будет искать файл с сохранёнными учётными данными в рабочей директории, или в папке которую вы укажите в аргументе AgencyAccount, если файл найден то учётные данные будут загружены из него, если файл не был найден то будет открыт браузер и вам потребуется разрешить приложению ryandexdirect доступ к своему рекламному аккауну, далее будет сформирован код авторизации, который вам необходимо вставить в R консоль в ответ на запрос «Enter authorize code:«, после чего функция сама сохранит учётные данные в файл с именем login.yadirAuth.RData, где вместо login будет подставлен логин аккаунта к которому вы предоставили доступ, это необходимо для сохранения токенов полученных для разных аккаунтов. При следующих обращениях, все функции пакета будут запрашивать токен из сохранённого файла.

Обновление токена

При каждом обращении к API проверяется количество дней до того как используемый токен станет просроченным, если остаётся менее 30 дней токен автоматически будет обновлён, и файл с учётными данными перезаписан.

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

• Login — имя пользователя или электронный адрес на Яндексе, с которого есть доступ к нужному вам рекламному аккаунту
• NewUser — логическое выражаение TRUE или FALSE, признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса. Параметр полезен, например, если вы хотите переключиться на другой аккаунт. По умолчанию установлено значение FALSE.
• TokenPath — путь к папке, в которой будут сохраняться учётные данные, по умолчанию это рабочая директория, но можно указывать любой путь, как абсолютный например «C:/my_r_files/tokens», так и относительны «tokens», при использовании относительного пути в рабочей директории будет создана папка с установленным вами названием, и в неё будут сохраняться файлы с расширением .RData в которых хранящие учётные данные.

Ещё раз обращаю внимание на то, что хоть вы в любой момент при желании можете пройти аутентификацию в API Яндекс Директ с помощью функции yadirAuth, но это действие не является обязательным, т.к. при использовании любой функции пакета будет запущен поиск файла с учётными данными, и если файл не будет найден, то автоматически будет запущен процесс авторизации и запроса токена.

Новые аргументы во всех функциях

Во все функции пакета были добавлены следующие аргументы:

• Login / Logins — Логин или вектор содержащий логины клиентов агентского аккаунта, в этот аргумент необходимо указывать логин в случае если вы запрашиваете данные из обычного рекламного аккаунта Яндекс Директ, или же логин клиентского аккаунта привязаного к вашему агентскому аккаунту, в таком случае в рабочей директории будет создан отдельный файл под каждый рекламный аккаунт, в котором будут хранится нужные для работы учётные данные.
• Token — С версии 3.0.0 этот аргумент больше не является обязательным, вы по прежнему можете передавать в него токены в виде строки, полученные с помощью функции yadirGetToken, так же можете передавать объекты учётных данных полученные с помощью новой функции yadirAuth, либо просто опустить данный агрумент.
• AgencyAccount — В случае если вы работаете с агентского аккаунта в этот аргумент необходимо передавать логин вашего агентского аккаунта, для каждого агентского аккаунта с которым вы работаете так же будет создан отдельный файл для хранения учётных данных.
• TokenPath — Путь к папке в которой хранятся все файлы с учётными данными, по умолчанию все функции пакета пытаются найти нужный файл с хранящимися учётными данными в текущей рабочей директории, но вы можете указывать абсолютный или условный путь к совершенно любой попке на вашем ПК, в которой вы хотите хранить все учётные данные ваших аккаунтов Яндекс Директ. Пример условного пути TokenPath = «yandex_token», в таком случае в рабочей директории будет создана папка yandex_token в которую и будут сохраняться все учётные данные, указав этот путь во всех функциях пакета вам не понадобится повторно запрашивать токены.

Работа с обычным рекламным аккаунтом

Таким образом при работе с обычным рекламным аккаунтом вам необходимо передавать логин этого аккаунта в аргументе Login или Logins. При запуске любой функции в первую очередь будет запущен процесс поиска учётных данных для заданного логина в папке, название или путь к которой указан в аргументе TokenPath. Если файл с учётными данными для заданного логина был найден то работа функции будет продолжена без вашего вмешательства, если учётные данные для данного логина ещё не были получены, или были получены но вы не указали путь к папке в которой данный файл был сохранён то автоматически будет запущен веб браузер и вам потребуется пройти авторизацию и разрешить доступ пакету ryandexdirect к вашему рекламному аккаунту, учётные данные при этом будут сохранены в локальный файл и при дальнейшей работе будут загружаться именно из файла.

Работа с агентским аккаунтом

Для получения статистики по рекламным аккаунтам прикреплённым к агентскому аккаунту необходимо использовать аргумент AgencyAccount, в который необходимо передать логин или почту для вашего агентского аккаунта, а в аргумент Login / Logins передавать логин клиента, или вектор содержащий логины клиентов данного агентского аккаунта, по которым вы хотите запросить какие либо данные или совершить ещё какие либо действия.

Авторизация в данном случае будет проходить по агентскому аккаунту.

Имена аргументов

Во всех функциях кроме функций для работы с Яндекс Метрикой были отформатированы и приведены к общему правила названия аргументов, теперь все аргументы во всех функциях пакета необходимо указывать с заглавной буквы, синтаксис всех функций приведён к ВерблюжьемуРегистру (UpperCamelCase), в связи с чем возможно после обновления ryandexdirect до версии 3.0.0 вам придётся частично внести правки в названия аргументов в коде написанном на более старых версиях ryandexdirect.

В версии 3.0.0 были переведены в ВерблюжийРегистр названия аргументов login и token в следующих функций: yadirGetClientList, yadirGetClientParam, yadirGetDictionary, yadirCurrencyRates.

Загрузка списка ключевых слов, объявлений и групп объявлений

Этот блок доработок касается функций yadirGetAds, yadirGetAdGroups и yadirGetKeyWords, ранее аргумент CampaignIds был обязательным, теперь в случае если вы не указали по каким рекламным кампаниям вы хотите получить список объявлений, групп объявлений или ключевых слов вам не обязательно указывать список ID рекламных кампаний, функция сама загрузит все ID и вернёт все объявления, группы объявлений или ключевые слова из аккаунта.

Устаревшие функции

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

Название устаревшей функции	Назначение функции	Какой функцией заменить
yadirGetSummaryStat	Загрузка статистики по рекламным кампаниям	yadirGetReport
yadirGetToken	Запрос токена доступа к API	yadirAuth

Пример кода для загрузки статистики с помощью ryandexdirect 3.0.0

Загрузка данных из обычного рекламного аккаунта Яндекс Директ.

Перед запуском кода замените значение «yandex_login», передаваемое в аргумент Login функции yadirGetReport на логин под которым вы авторизуетесь в рекламном аккаунте Яндекс Директ.

library(ryandexdirect)
statistic <- yadirGetReport(ReportType = "ACCOUNT_PERFORMANCE_REPORT",
DateRangeType = "CUSTOM_DATE",
DateFrom = "2018-01-01",
DateTo = "2018-05-10",
FieldNames = c("AdNetworkType",
"Impressions",
"Clicks",
"Cost"),
Login = "yandex_login",
TokenPath = "token_yandex")

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

# Пример работы с агентским рекламным аккаунтом
library(ryandexdirect)

# Задаём переменную с логином агентского аккаунта

agency_login <- "agency_login"

# Загрузка списка клиентов
clients <- yadirGetClientList(AgencyAccount = agency_login,
TokenPath = "token_yandex")

# Загрузка статистики по всем клиентам агентского аккаунта
agancy_stats <- yadirGetReport(ReportType = "ACCOUNT_PERFORMANCE_REPORT",
DateRangeType = "CUSTOM_DATE",
DateFrom = "2018-01-01",
DateTo = "2018-05-10",
FieldNames = c("AdNetworkType",
"Impressions",
"Clicks",
"Cost"),
Login = clients$Login,
AgencyAccount = agency_login,
TokenPath = "token_yandex")

---

Релиз обновления на GitHub.