---
title: "Авторизация в API MyTarget с помощью пакета rmytarget"
author: "Alexey Seleznev"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Авторизация в API MyTarget с помощью пакета rmytarget}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  eval = FALSE,
  comment = "#>"
)
```

Авторизация в API через `rmytarget` осуществляется по схеме авторизации *Authorization Code Grant*, подробнее о способах авторизации можно узнать в [официальной справке API MyTarget](https://target.my.com/help/advertisers/api_authorization/ru).

Пройти авторизации можно с помощью функции `myTarAuth`:
```{r}
myTarAuth(login = "my_test_client",
          token_path = "mt_tokens")
```

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

* login - логин, используется только для формирования названия файла, в котором будут сохранены учётные данные для работы с API, при первом обращении, в дальнейшем так же по этому аргументу будет осуществляться поиск файла для загрузки учётных данных.
* token_path - путь к папке в котором будет создан файл для хранеия учётных данных, в дальнейшем в данный файл будет загружаться из указанной в этом аргументе папки.

Помните что в API MyTarget вы можете запрашивать всего 5 токенов для одного аккаунта.

После запуска функции откроется окно браузера, в котором вам необходимо подтвердить разрешение на оступ к вашим данным для пакета rmytarget. Если вы работаете через **агентский** аккаунт, то в открывшемся окне у вас будет возможность выбора, сгенерировать токен для вашего агентского акккаунта, или же получить токен для работы с одним прикреплённых к нему клиентских аккаунтов.

Для работы с агентским аккаунтом выберите верхний пункт.

![генерация токена для агентского аккаунта](https://img.netpeak.ua/alsey/154523525673_kiss_31kb.png)

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

Если же вам необходимо получить какие либо данные из подчинённого клиентского аккаунта то при авторизации через браузер выберите пункт "Предоставить доступ к аккаунту клиента или менеджера".

![Генерация токена для работы с клеинтским аккаунтом](https://img.netpeak.ua/alsey/154523530679_kiss_35kb.png)

Далее необходимо нажать кнопку подтверждения доступа, после чего вы будете перенаправлены на страницу где вам необходимо скопировать код подтверждения доступа к API.

Скопированный код необходимо ввести в консоль RStudio, в качестве ответа на запрос `Enter code from browser:`.

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

`You tokens left for this account: 2`, что говорит о том, что для данного аккаунта можно запросить ещё 2 токена.

И будет выведен запрос, разрешаете ли вы сохранить полученный токен в локальный файл на ваш жесткий диск, для того, что использовать его между разными сессиями работы в R, и не проходить постоянно процесс авторизации в браузере. `Do you want save API credential in local file (C:/webinars/automationday-2018/my_login.rymAuth.RData), for use it between R sessions?`. **Напоминаю что вы можете получить всего 5 токенов на 1 аккаунт**, поэтому я крайне рекомендую сохранять полученные токены в файл, и в качестве ответа на этот запрос ввести `y` или `yes`, в противном случае вы загрузите данные, но токен сохранён не будет, и вам при следующем обращении к API понадобиться повторно его запрашивать.

Если вы  согласились, и всё сделали правильно то в консоль будет выведено сообщение `Token saved at C:/webinars/automationday-2018/my_login.mytar.Auth.RData`.

Далее в рабочей директории будет создан файл хранящий учётные данные, название файла будет начинаться с указаннолого логина и далее *.mytar.Auth.RData*.

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

На самом деле проходить авторизацию отдельно через функцию `myTargetAuth` необзательно, т.к. при запуске любой из доступных в пакете функций процесс авторизации будет запущен автоматически.

### Другие схемы авторизации

Так же `rmytarget` поддерживает и другие схемы авторизации.  Но для прохождения аутентификации с их помощью вам для начала надо самостоятельно получить доступ к API, о том как это сделать вы можете узнать по [этой ссылке](https://target.my.com/help/advertisers/api_access/ru). На данный момент он предоставляется только юр.лицам в ручном режиме.

В зависимости от типа вашего аккаунта вам необходимо получить токен доступа согласно типу вашего аккаунта в MyTarget. Пройти авторизацию для обычного клиентского аккаунта так ж можно по сехеме Client Credentials Grant для обычного рекламодателя и для агентства.

Получение токена для обычного рекламного аккаунта.
```{r}
myTargetAuth <- myTarAuth(grant_type = "client_credentials",
                          client_id = "XXXXXXXXXX",
                          client_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
			  code_grant = FALSE)		
```

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

* grant_type - Тип вашего аккаунта, в данном случае обычный клиентский аккаунт.
* client_id - ID выдаётся вам при подтверждение доступа к API MyTarget.
* client_secret - Выдаётся вам при подтверждение доступа к API MyTarget вместе с Client ID.

Получение токена для агентского аккаунта.
```{r}
myTarGetAuth <- myTarAuth(grant_type = "agency_client_credentials",
                          client_id = "XXXXXXXXXX",
                          client_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                          agency_client_name = "xxxxxxxxx@agency_client",
			  code_grant = FALSE)
```

Вариант grant_type=agency_client_credentials не является стандартным для OAuth2. Он реализован для того, чтобы агентства могли создавать access-токены для своих клиентов напрямую. Помимо параметров client_id, client_secret нужно передавать agency_client_name.
Для получения информации по агентскому аккаунту, например поучить список клиентов агентсва необходимо следовать первой описанной схеме с grant_type = "client_credentials" и получить токен агентского аккаунта.

## Обновление токена доступа
При авторизации по схеме Authorization Code Grant, которая установлена в `rmytarget` по умолчанию, обновлять токены вам не потребуются, во первых потому, что вы получаете бессрочный токен, а во вторых при работе по этой схеме пакет при необходимости сам будет обновлять токеню

При работе со схемамы авторизации Client Credentials Grant и Agency Credentials Grant. Каждый полученный access-токен является действительным в течение суток. На это указывает свойство expires_in в ответе на запрос access-токена.
Для обновления токета в пакете rmytarget есть функция `myTarRefreshToken`

```r
myTarGetAuth <- myTarRefreshToken(old_auth = myTargetAuth,
                                  client_id = "xxxxxxxxx",
                                  client_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxx...")
```

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

* old_auth - R объект с учётными данными полученный с помощью функции myTarAuth.
* client_id - ID выдаётся вам при подтверждение доступа к API MyTarget.
* client_secret - Выдаётся вам при подтверждение доступа к API MyTarget вместе с Client ID.

Подробную информацию о схеме аутинтификации в API вы можете получить по [ссылке](https://target.my.com/help/advertisers/api_authorization/ru).