Получение токена
Для генерации токена в пакете есть две функции, yadirAuth() и yadirGetToken(). Получить токен можно с помощью любой из этих функций, но я рекомендую использовать yadirAuth, функция yadirGetToken() считается устарвшей начиная с ryandexdirect 3.0.0.
Разница между ними состоит в том, что yadirGetToken() просто генерирует токен и перенаправляет вас на страницу где вы можете его скопировать, а yadirAuth первый раз направляет вас на старницу где будет сгенерирован код для получения токена, после чего сама запрашивает токен и сохраняет в файл, в дальнейшем сама его обновляет и работает с сохранённым файлом.
Вы можете передавать токен в виде строки в агрумент Token при работе с любой из функций, но этот метод является устаревшим и не эффективным способом работы с функциями пакета ryandexdirect.
В версии 3.5.0 в пакет была добавлена новая функция для прохождения аутентификации в API yadirAuth(), но отдельно вызывать её для получения токена больше не требуется, при любом обращении к API если вы в используемой функции явно не указываете никакой токен, любая функция пакета сначала будет искать файл с сохранёнными учётными данными в рабочей директории, или в папке которую вы укажите в аргументе AgencyAccount, если файл найден то учётные данные будут загружены из него, если файл не был найден то будет открыт браузер и вам потребуется разрешить приложению ryandexdirect доступ к своему рекламному аккауну, далее будет сформирован код авторизации, который вам необходимо вставить в R консоль в ответ на запрос “Enter authorize code:”, после чего функция сама сохранит учётные данные в файл с именем login.yadirAuth.RData, где вместо login будет подставлен логин аккаунта к которому вы предоставили доступ, это необходимо для сохранения токенов полученных для разных аккаунтов. При следующих обращениях, все функции пакета будут запрашивать токен из сохранённого файла.
Пример кода для прохождения авторизации
aut <- yadirAuth(Login = "Ваш логин в яндексе", NewUser = TRUE, TokenPath = "token_yandex")
Обновление токена
При каждом обращении к API проверяется количество дней до того как используемый токен станет просроченным, если остаётся менее 30 дней токен автоматически будет обновлён, и файл с учётными данными перезаписан.
Аргументы функции yadirAuth
- Login - имя пользователя или электронный адрес на Яндексе, с которого есть доступ к нужному вам рекламному аккаунту
- NewUser - логическое выражаение TRUE или FALSE, признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса. Параметр полезен, например, если вы хотите переключиться на другой аккаунт. По умолчанию установлено значение FALSE.
- TokenPath - путь к папке, в которой будут сохраняться учётные данные, по умолчанию это рабочая директория, но можно указывать любой путь, как абсолютный например “C:/my_r_files/tokens”, так и относительный “tokens”, при использовании относительного пути в рабочей директории будет создана папка с установленным вами названием, и в неё будут сохраняться файлы с расширением .RData в которых хранятся учётные данные.
Ещё раз обращаю внимание на то, что хоть вы в любой момент при желании можете пройти аутентификацию в API Яндекс Директ с помощью функции yadirAuth, но это действие не является обязательным, т.к. при использовании любой функции пакета будет запущен поиск файла с учётными данными, и если файл не будет найден, то автоматически будет запущен процесс авторизации и запроса токена.
Авторизация с помощью функции yadirGetToken()
Функция для получения токена для доступа к API Яндекс.Директ с помощью упрощённой одноэтапной аутентификации. Полученый токен используется во всех остальных функциях. Перед запуском функции необходимо авторизироваться в яндексе под логином через который есть доступ к аккаунту Яндекс.Директ, далее запустить функции, в окне браузера подтвердить разрешение на доступ к данным.
Полученный токен необходимо скопировать с сайта и ввести в консоль R, далее вам будет предложено сохранить полученный токен в файл, рекомендуется отвечать y, в таком случае вам не придётся проходить авторизации при старте новой R сессии.
Можно получить токен воспользовавшись кнопкой
Ещё один способ получить токен, скопировать его, и использовать во всех остальных функциях как обычную текстовую строку.
Получить токен доступа к API!
Если у вас не отображается кнопка перейдите на страницу официальной документации ryandexdirect по этой ссылке.
Аргументы, общие для всех функций
Во всех функции пакета существуют общие аргументы, в дальнейшем эти аргументы рассматриваться в описании функций не будут.
- Login / Logins - Логин или вектор содержащий логины клиентов агентского аккаунта, в этот аргумент необходимо указывать логин в случае если вы запрашиваете данные из обычного рекламного аккаунта Яндекс Директ, или же логин клиентского аккаунта привязаного к вашему агентскому аккаунту, в таком случае в рабочей директории будет создан отдельный файл под каждый рекламный аккаунт, в котором будут хранится нужные для работы учётные данные.
- Token - С версии 3.0.0 этот аргумент больше не является обязательным, вы по прежнему можете передавать в него токены в виде строки, полученные с помощью функции yadirGetToken, так же можете передавать объекты учётных данных полученные с помощью новой функции yadirAuth, либо просто опустить данный агрумент.
- AgencyAccount - В случае если вы работаете с агентского аккаунта в этот аргумент необходимо передавать логин вашего агентского аккаунта, для каждого агентского аккаунта с которым вы работаете так же будет создан отдельный файл для хранения учётных данных.
- TokenPath - Путь к папке в которой хранятся все файлы с учётными данными, по умолчанию все функции пакета пытаются найти нужный файл с хранящимися учётными данными в текущей рабочей директории, но вы можете указывать абсолютный или условный путь к совершенно любой папке на вашем ПК, в которой вы хотите хранить все учётные данные ваших аккаунтов Яндекс Директ. Пример условного пути TokenPath = “yandex_token”, в таком случае в рабочей директории будет создана папка yandex_token в которую и будут сохраняться все учётные данные, указав этот путь во всех функциях пакета вам не понадобится повторно запрашивать токены.
Работа с обычным рекламным аккаунтом
Таким образом при работе с обычным рекламным аккаунтом вам необходимо передавать логин этого аккаунта в аргументе Login или Logins. При запуске любой функции в первую очередь будет запущен процесс поиска учётных данных для заданного логина в папке, название или путь к которой указан в аргументе TokenPath. Если файл с учётными данными для заданного логина был найден то работа функции будет продолжена без вашего вмешательства, если учётные данные для данного логина ещё не были получены, или были получены но вы не указали путь к папке в которой данный файл был сохранён то автоматически будет запущен веб браузер и вам потребуется пройти авторизацию и разрешить доступ пакету ryandexdirect к вашему рекламному аккаунту, учётные данные при этом будут сохранены в локальный файл и при дальнейшей работе будут загружаться именно из файла.
Работа с агентским аккаунтом
Для получения статистики по рекламным аккаунтам прикреплённым к агентскому аккаунту необходимо использовать аргумент AgencyAccount, в который необходимо передать логин или почту для вашего агентского аккаунта, а в аргумент Login / Logins передавать логин клиента, или вектор содержащий логины клиентов данного агентского аккаунта, по которым вы хотите запросить какие либо данные или совершить ещё какие либо действия.
Авторизация в данном случае будет проходить по агентскому аккаунту.
Функции для переключения между аккаунтами
Прописывать в каждой отдельной функции аргументы Login, TokenPath, AgencyAccount неудобно, особенно если в ходе сессии работаете только с одним аккаунтом.
Вы можете использовать следующие, вспомогательные функции для того, что бы посмотреть список всех аккаунтов к которым вы сгенерировали файлы с учётными данными, и для переключения между этими аккаунтами.
yadirSetLogin() - позволяет вам установить логин который будет использоваться в ходе сессии по умолчанию, так же в ходе сессии с помощью этой функции вы можете переключаться между аккаунтами.- `yadirSetAgencyAccount() - позволяет вам установить логин центра клиентов который будет использоваться в ходе сессии по умолчанию, так же в ходе сессии с помощью этой функции вы можете переключаться между центрами клиентов к которым у вас есть доступ.
yadirGetLogins() - позволяет вам запросить логины всех аккаунтов к которым вы сгенерировали и созранили учётные данные, далее, при работе в интерактивном режиме функция выведит их список, и вы можете указать номер аккаунта, который будет установлен в текущей сессии по умолчанию.
Опции и переменные среды
Ещё одна возможность избежать дублирования кода - установить дефолтные значения через опции или переменные среды.
Опции
Пакет ryandexdirect на данный момент поддерживает следующие опции:
ryandexdirect.user - логин по умолчаниюryandexdirect.agency_account - логин центра клиентов по умолчаниюryandexdirect.token_path - путь к директории в которой хранятся файлы с полученными учётными данными
Устанавливаются опции с помощью команды options().
options(ryandexdirect.user = 'my_yandex_login',
ryandexdirect.agency_account = 'my_client_centre_login',
ryandexdirect.token_path = 'C:/auth/yandex_direct')
Используя пример кода для установки опций вам необходимо подставить значения вместо:
- my_yandex_login - логин подчинённого аккаунта, или обычного аккаунта яндекс директ
- my_client_centre_login - логин центра клиентов, если указанный вами подчинённый аккаунт является клиентом в вашем центре клиентов
- ‘C:/auth/yandex_direct’ - путь к директории в которой хранятся, или будут хранится учётные данные полученные вами при авторизации
Переменные среды
Помимо опций ryandexdirect поддерживает работу с переменными среды, их можно установить, что бы не прописывать в каждом отдельном скрипте опции.
На данный момент поддерживаются следующие переменные среды:
- RYD_USER - логин по умолчанию
- RYD_AGENCY - логин центра клиентов по умолчанию
- RYD_TOKEN_PATH - путь к директории в которой хранятся файлы с полученными учётными данными
Прописать переменные среды можно либо в файле .Renviron
RFB_USER="my_yandex_login"
RFB_TOKEN_PATH="C:/auth/yandex_direct"
Либо вы можете использовать команду Sys.setenv():
Sys.setenv(RFB_USER="my_yandex_login"
RFB_TOKEN_PATH="C:/auth/yandex_direct")
Либо использовать возможности вашей операционной системы, для создания переменных среды.
Функции для быстрого переключения между аккаунтами
В принципе вы можете указывать нужный аккаунт с помощью аргумента Login, в любой из функций пакета, так же вы можете указать нужный вам аккаунт через опции или переменные среды, но начиная с версии 3.6.0 в пакет были включены новые функции, которые позволяют повысить читаемость вашего кода, и упростить переход между аккаунтами.
yadirGetLogins() - Показывает все логины под которыми вы прошли авторизацию, при этом запрашиваются те логины которые учётные данные которых сохраненны в указанной папке с помощью аргумента TokenPath, либо опции ryandexdirect.token_path или переменной среды RYD_TOKEN_PATH.yadirSetLogin() - Позволяет установить дефолтный логин, который будет использоваться в рамках сессии.yadirSetAgencyAccount() - Позволяет установить дефолтный центр клиентов, который будет использоваться в рамках сессии.
Обо всех подробностях использования данных функций вы можете узнать из данного видео урока.