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.

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

Этот блок доработок касается функций yadirGetAdsyadirGetAdGroups и 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.

Реклама

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

Добавьте свой

  1. Добрый день!
    Во время установки командой
    devtools::install_github(«selesnow/ryandexdirect»)

    Появляется сообщение:

    These packages have more recent versions available.
    Which would you like to update?

    1: Rcpp (0.12.19 -> 1.0.0 ) [CRAN]
    2: rlang (0.3.0 -> 0.3.0.1) [CRAN]
    3: CRAN packages only
    4: All
    5: None

    Я правильно понял, что версия ryandexdirect устарела?

    Нравится

    1. Я правильно понял, что версия ryandexdirect устарела?

      Нет, как раз в данном случае у вас устарели версии перечисленных там пакетов (Rcpp и rlang).

      Это доработанный пакет devtools с недавних пор выполняет такую проверку, что вы можете сделать.

      1. Как видите у вас доступны 5 пунктов, вы можете ввести номер любого из них в консоль, для выполнения какой либо из предложенных операций а именно:
        1. Обновить пакет Rcpp с версии 0.12.19 на 1.0.0
        2. Обновить пакет rlang с версии 0.3.0 на 0.3.0.1
        3. Обновить пакеты которые ранее были установлены с CRAN
        4. Обновить все предложенные пакеты.
        5. Не обновлять ни один из предложенных пакетов.

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

      Так же вы вообще можете игнорировать проверку версионности пакетов при установке ryandexdirect, через devtools с помощью аргумента upgrade.

      devtools::install_github("selesnow/ryandexdirect", upgrade = "never")

      Нравится

  2. Добрый день.

    После обновления появилось следующее сообщение:

    DataSource.Error: ADO.NET: R script error.
    Ошибка: package or namespace load failed for ‘ryandexdirect’ in loadNamespace(i, c(lib.loc, .libPaths()), versionCheck = vI[[i]]):
    пространство имен ‘rlang’ 0.2.2 загружается, но нужно >= 0.3.0
    Выполнение остановлено

    Выполнил:

    install.packages(«rlang»)

    Получил:

    package ‘rlang’ successfully unpacked and MD5 sums checked

    The downloaded binary packages are in
    C:\Users***\AppData\Local\Temp\RtmpGgDPrC\downloaded_packages

    Получается, что распаковалась во временную директорию.
    Оттуда ручками скопировал её в 2 места:

    c:\Program Files\R\R-3.5.1\library\

    c:\Users***\Documents\R\win-library\3.5\

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

    Нравится

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

      Что я вам рекомендую, удалите всё что руками скопировали, и заново установите rlang, по идее должно завестись.

      Нравится

      1. Я как раз копировать руками начал после того как не сработало. Сейчас снёс то что руками добавлял и снова тот же результат…

        Нравится

      2. Давайте сделаем иначе, я всегда рекомедую отлаживать код в RStudio, а не в power bi которая совершенно для этого не годится.

        Открывайте RStudio и :

        Удалите rlang, remove.packages(«rlang»)
        Так же удалите ryandexdirect
        Установите заново ryandexdirect, при этом rlang сам подтянется.

        Думаю всё будет ок.

        Нравится

      3. https://yadi.sk/d/sj58Q8bnlHvYKw

        Удалил «rlang» через remove.packages → success
        Удалил «ryandexdirect» через remove.packages → success
        Установил devtools → success
        Установил «ryandexdirect» → Error: нет пакета под названием «rlang»

        Тогда поставил «rlang» отдельно:

        install.packages(«rlang»),
        и установил «ryandexdirect»:
        install.packages(«devtools»)
        devtools::install_github(«selesnow/ryandexdirect»)

        Вроде, установился, но в конце выдал странное предупреждение: https://yadi.sk/d/eU_rfbTxKKr_dw

        При этом в PBI ошибка осталась без изменений.

        Тогда проделал то же, но иначе: удалил «rlang» и «ryandexdirect» через RStudio и ручками из библиотек,
        Перезагрузил RStudio,
        Проверил что PBI ругается на отсутствие «ryandexdirect», — да
        Устанавливаю «ryandexdirect» → Error: нет пакета под названием «rlang»,
        Ставлю отдельно «rlang», снова ставлю «ryandexdirect»:

        Warning messages:
        1: In untar2(tarfile, files, list, exdir) :
        skipping pax global extended headers
        2: In untar2(tarfile, files, list, exdir) :
        skipping pax global extended headers

        Проделал всё заново начиная с удаления и установки пакета «devtools», результат тот же:

        В Power BI выдаёт «пространство имен ‘rlang’ 0.2.2 загружается, но нужно >= 0.3.0»

        Нравится

      4. У меня такое впечатление что Power BI и RStudio блин используют у вас разные библиотеки.

        Проверить это можно функцией .libPaths().

        И ещё, в power BI, вы можете при подключении пакета в функции library указать из какой именно библиотеки надо подключать пакет, это с помощью аргумента lib.loc делается, прим. library(rlang, lib.loc = «D:/r_library»)

        Нравится

  3. Здесь всё сходится. Это именно те директории из которых я руками удалял:

    .libPaths()
    [1] «C:/Users/***/Documents/R/win-library/3.5» «C:/Program Files/R/R-3.5.1/library»

    в PBI указан путь до C:/Program Files/R/R-3.5.1

    Очень смущает это:

    devtools::install_github(«selesnow/ryandexdirect»)
    Error in loadNamespace(i, c(lib.loc, .libPaths()), versionCheck = vI[[i]]) :
    нет пакета под названием ‘rlang’

    В PBI та же ошибка при установленном «rlang» (отдельно):

    Ошибка: package or namespace load failed for ‘ryandexdirect’ in loadNamespace(i, c(lib.loc, .libPaths()), versionCheck = vI[[i]]):
    пространство имен ‘rlang’ 0.2.2 загружается, но нужно >= 0.3.0
    Выполнение остановлено

    Видимо придется переустанавливать весь R… других идей пока нет.

    Нравится

    1. Мне кажется это самый простой вариант, у вас он что то совсем запутался в библиотеках, если что можно назначат и новые папки библиотеками, я описывал как это сделать вот тут — https://alexeyseleznev.wordpress.com/2018/08/08/%D0%BE%D1%88%D0%B8%D0%B1%D0%BA%D0%B0-%D0%BF%D1%80%D0%B8-%D1%83%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B5-r-%D0%BF%D0%B0%D0%BA%D0%B5%D1%82%D0%BE%D0%B2-%D0%BD%D0%B0-windows-%D0%BE%D1%88%D0%B8/

      Нравится

      1. Задача решена!!

        Оказалась проблема в Power BI.

        https://yadi.sk/d/bDt1-J8Rftg9oA
        Указанные на скрине настройки стояли: «R Studio» и пути прописано не было.
        Поставил «Other», прописал путь к rstudio.exe и всё заработало)

        Алексей, огромное спасибо за участливость и вашу помощь, без этого пути я бы не разобрался)

        Нравится 1 человек

      2. Отлично! Рад, что получилось решить проблему, и что пользуетесь пакетами.
        Если что обращайтесь.

        Нравится

  4. Способ не помог, ибо не удалось найти файл .Renviron
    Его создание с необходимой строкой ничего не изменило → .libPaths() показал те же директории.

    Удалил весь R, R Studio и все библиотеки.

    Поставил заново, всё с нуля. Результат тот же.

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

    Нравится 1 человек

Добавить комментарий

Заполните поля или щелкните по значку, чтобы оставить свой комментарий:

Логотип WordPress.com

Для комментария используется ваша учётная запись WordPress.com. Выход /  Изменить )

Google photo

Для комментария используется ваша учётная запись Google. Выход /  Изменить )

Фотография Twitter

Для комментария используется ваша учётная запись Twitter. Выход /  Изменить )

Фотография Facebook

Для комментария используется ваша учётная запись Facebook. Выход /  Изменить )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Создайте бесплатный сайт или блог на WordPress.com. Тема: Baskerville 2, автор: Anders Noren.

Вверх ↑

%d такие блоггеры, как: