VK.com предоставляет многофункциональный и удобный API, который позволяет делать всё, что приходит на ум программисту, и даже, немного больше. API позволяет отправлять сообщения, получать и публиковать записи на стену, производить абсолютно любые действия, которые существуют в VK, от имени пользователя, кому был сгенерирован токен. Разобравшись с API на примере ВК, в будущем, вы безпроблемно сможете быстро вникать в API любых других сайтов. И, ввиду того, что 90% всех API имеют схожую реализацию, то понимание этой статьи будет для вас отличным стартом, и хорошей школой освоения «взрослых игрушек».
В недавней статье было рассмотрено, что такое REST API. Почитайте информацию по ссылке — это точно будет полезно.
- Что такое VK API, разные группы API.
- Получение токена доступа
- Запросы к API (на примере получения всех записей пользователя со стены)
- Резюме
ВК-API блиц
ВК предоставляет несколько реализаций API:
Урок 77. API ВКонтакте. Получение access token
- Streaming/Long Poll — позволяет получить данные в реальном времени. Сразу же, при обновлении данных в ВК, мы получаем актуальную информацию, без обновления страницы. Streaming и Long Poll реализуют разные подходы, но суть их одинаковая.
- Виджеты для сайта — здесь всё просто: скопировал код, без хитрых настроек, и у тебя рабочий виджет на сайте.
- Open API — работает на клиенте. Так же просто настраивается и используется. Преимуществом является то, что не обязательно иметь сервер для выполнения запросов. Будет работать в обычном HTML + JS.
- Callback API — позволяет получать данные от самомого ВК, не выполняя запрос. В случае обновления данных, ВК сам нам присылает новые данные. Например, пользователь подписался на нашу группу, и ВК, автоматически пришлёт информацию об этом пользователе нашему скрипту.
- REST API — позволяет взаимодействовать с данными ВК из скрипта. Позволяет автоматизировать любые пользовательские действия.
Для нас, как для программистов, на данном этапе — интересен REST API. Который позволяет взаимодействовать с пользователями, группами, рекламой, и прочими сущностями. Подробнее, обо всех доступных методах можно почитать здесь.
Для получение доступа к REST API, необходимо иметь специальный ключ vk api token. Это уникальное значение, аналогично логину и паролю — идентифицирует пользователя, от имени которого выполняются запросы.
Как гласит 2 правило проектирования REST API — между запросами не должно сохраняться состояния. Система по определению не может использовать сессии, потому применение токена актуально для идентификации пользователя.
Что такое ОAuth2.0?
- Вместо привычных логина и пароля, которые имеют определенный набор прав и время жизни, мы получаем доступ к ресурсам с помощью случайно сгенерированных строк — токенов
. - Можно выдавать права максимально точечно
, опираясь на собственные пожелания, а не на заранее определённый набор прав.
Роли
- Resource owner
— сущность, которая имеет права доступа на защищённый ресурс. Сущность может быть конечным пользователем или какой-либо системой. Защищённый ресурс — это HTTP endpoint, которым может быть что угодно: API endpoint, файл на CDN, web-сервис. - Resource server
— сервер, на котором хранится защищённый ресурс, к которому имеет доступ resource owner. - Client
. Это приложение, которое запрашивает доступ к защищённому ресурсу от имени resource owner и с его разрешения — с авторизацией. - Authorization server
— сервер, который выдаёт клиенту токен для доступа к защищённому ресурсу, после успешной авторизации resource owner.
VK API получаем токен группы и standalone access token
Регистрация клиента
фантазииRedirection URIClient type
- Confidential
— клиент, который может безопасно хранить свои учётные данные. Например, к такому типу клиентов относят web-приложения, имеющие backend. - Public
— не может безопасно хранить свои учётные данные. Этот клиент работает на устройстве владельца ресурса, например, это браузерные или мобильные приложения.
Абстрактный OAuth 2.0. Flow c применением Access token
- Client отправляет запрос на доступ к требуемому ресурсу resource owner.
- Resource owner передаёт обратно клиенту authorization grant, который подтверждает личность resource owner и его права на ресурс, доступ к которому запрашивает client. В зависимости от flow это может быть токен или учётные данные.
- Client отправляет authorization grant, полученный в предыдущем шаге authorization server, ожидая от него Access token для доступа к защищённому ресурсу.
- authorization server убеждается в валидности authorization grant, после чего отсылает access token клиенту в ответ.
- Получив access token, клиент запрашивает защищённый ресурс у resource server.
- Resource server убеждается в корректности access token, после чего предоставляет доступ к защищённому ресурсу.
Абстрактный OAuth 2.0. Flow c применением Refresh token
- Client приходит c authorization grant к authorization server и просит предоставить ему access token и refresh token.
- Authorization server убеждается, что с authorization grant всё нормально и возвращает клиенту запрошенные access token и refresh token.
- Client с access token запрашивает защищённый ресурс, пока не получит первую ошибку доступа к ресурсу — invalid token error.
- После получения ошибки доступа, клиент идет к authorization server с refresh token и просит заменить просроченный access token на новый.
- В ответ клиент получает новый access token, а также новый refresh token, либо продлевается время жизни старого refresh token.
Как получить токен VK.COM
Получение токена состоит из двух частей: регистрации своего приложения и получение токена в этом приложении.
Создать приложение можно на странице. Указав название приложения, и выбрав его тип. Я выбираю Standalone, потому что тогда можно будет получить токены с бОльшим возможностями, чем в остальных вариантах (придётся поверить мне на слово, что это правда).
Создав приложение и перейдя на вкладку настроек, будет показано: id приложения, секретный ключ
Теперь, имея id приложения, можно получить токен доступа. Для этого нужно сформировать ссылку, подставив в неё id своего приложения.
где вместо нужно вставить id своего приложения. а в параметре scope — перечислены разрешения, которыми мы хотим наделить токен, список всех разрешений Однако здесь, одним из самых важных разрешений является offline, которое создаёт бессрочный токен, не имеющий ограниченного времени жизни.
Если вы не хотите создавать своё приложение, то можете получить токен по ссылке
Перейдя по сформированной ссылке, откроется диалоговое окно, в которому будут зачитаны права показаны разрешения, которыми наделяется токен (чем больше указано scope свойств, тем больше будет этот список)
Подтвердив, произойдёт переадресация на страницу, в адресной строке которой будет access_token, expires_in равный нулю (что логично, учитывая, что мы указывали создание вечного токена)
Я сократил токен для сохранения читабельности. У вас он будет длиннее
Скопировав этот токен, можно делать первые запросы к API.
Где взять access_token
Токены создаются по запросу на специальном сайте. Там на сегодняшний день нет никакого удобного интерфейса, вся работа происходит через строку браузера. Методы получения access_token разные для пользователей, приложений или сообществ. Наиболее простой способ известен как Implicit flow, он подразумевает как раз использование прямой ссылки на упомянутый сайт.
Вот, например, как можно получить token, если требуется предоставить доступ к базе данных ВК какому-либо внутреннему приложению (из тех, которые пользователи могут подключать к своим страницам).
Получение токена через собственное приложение
Сначала ваша программа должна быть зарегистрирована на сайте Вконтакте и иметь собственный ID. Как это сделать, читайте в официальной документации социальной сети, в разделе, посвящённом разработке.
Далее, для получения token доступа вам нужна вот такая строка:
Здесь вместо ХХХХХХХ требуется подставить client_id вашего приложения.
В параметре scope указаны права, которые требуется передать программе. Они в примере перечислены через запятую. Их может быть довольно много, все они перечислены на особой странице документации.
Вставьте этот запрос в адресную строку браузера и нажмите Enter. Вы увидите страницу, где нужно будет подтвердить права доступа. Здесь будет название приложения, описания запрашиваемых прав и фамилия владельца аккаунта.
Состав иконок, отображающих права, определяется параметром scope из переданной адресной строки.
После клика на кнопке «Разрешить» откроется страница, в адресной строке будет параметр access_token, который и требуется.
Получение токена через официальное приложение VK
Здесь всё то же самое, только получать client_id для программы уже не нужно, она давно зарегистрирована. Используйте такую строку:
Перед тем, как передать строку серверу, целесообразно отредактировать содержимое параметра scope в соответствии с вашими потребностями.
Здесь мы привели только общие сведения о том, что такое токен доступа ВК и как его получают. За более подробными сведениями нужно обращаться в справочный раздел для разработчиков на сайте социальной сети.
Как делать запросы к API
Сохраним полученный токен, потому как его нужно будет прикреплять к каждому запросу к VK API.
Для того, чтобы сделать запрос к API из PHP, нам нужна любая из доступных функций, способных совершить HTTP-запрос: file_get_contents, curl.
К слову, даже, если открыть в браузере сформированный адрес, то получим результат
Запрос к методам API состоит из шаблона: https://api.vk.com/method/?v= где — имя метода — параметры, индивидуальные, в зависимости от метода — ранее сохранённый токен — версия API (на момент написания статья = 5.78)
Зная всё это, сделаем первый запрос, на получение всех личных записей со стены. За стену отвечает сущность wall, а метод его get, который возвращает список всех записей со стены пользователя. И, в итоге, имя метода будет сформировано в виде имени сущности (wall).имя метода (get) — wall.get
Так, первая часть URL-адреса уже сформирована: https://api.vk.com/method/wall.get
Теперь нужно определиться с передаваемыми параметрами (PARAMS). Все доступные, обязательные параметры с описанием можно посмотреть на странице метода.
Я буду передавать owner_id который соответствует id моего пользователя.
По факту же, это поле является необязательным в текущих условиях. Так как по умолчанию, ownwer_id будет проставлен id текущего пользователя.
И, можно было бы просто дописать в виде строки к существующему URL-адресу: …?owner_id=120159853
Однако, если туда добавлять множество новых параметров, то в таком виде добавлять не удобно. Потому, я создам массив параметров, где ключом будет название параметра, а значение, соответственно, его значение. А с помощью функции http_build_query() можно привести массив к виду строки нужного вида:
$params = [ ‘owner_id’ => 120159853, //params2 => ‘value2’, ]; http_build_query($params); //owner_id=120159853 $token = ’38fa46d4c0c10bab105c760cc44ed373c0bc6a34405931f34c765ea’; $version = 5.78; $params = http_build_query([ ‘owner_id’ => 120159853, ‘access_token’ => $token, ‘v’ => $version //… ]); $url = «https://api.vk.com/method/?v=»; //https://api.vk.com/method/wall.get?owner_id=120159853v=5.78
При том, что даже токен и версию теперь можно вынести в массив $params, для более централизованной записи.
Осталось последний шаг — выполнение http-запроса. И, принимая тот факт, что данные возвращаются в виде JSON, то, результат, нужно дополнительно обернуть в функцию json_decode, которая приведёт JSON к обычному PHP-массиву. Вот так просто декодировать JSON.
$result = json_decode(file_get_contents($url), true);
В итоге, получаем обычный массив записей, который можем обработать как пожелаем
И, исходя из ответа выше, для получения записей выполним:
//все записи $orders = $result[‘response’][‘items’]; //первая запись $order = $result[‘response’][‘items’][0];
Источник: neomid59.ru
VK API. Основы. Получение токена. Первые запросы к API
VK.com предоставляет многофункциональный и удобный API, который позволяет делать всё, что приходит на ум программисту, и даже, немного больше. API позволяет отправлять сообщения, получать и публиковать записи на стену, производить абсолютно любые действия, которые существуют в VK, от имени пользователя, кому был сгенерирован токен. Разобравшись с API на примере ВК, в будущем, вы безпроблемно сможете быстро вникать в API любых других сайтов. И, ввиду того, что 90% всех API имеют схожую реализацию, то понимание этой статьи будет для вас отличным стартом, и хорошей школой освоения «взрослых игрушек».
В недавней статье было рассмотрено, что такое REST API. Почитайте информацию по ссылке — это точно будет полезно.
- Что такое VK API, разные группы API.
- Получение токена доступа
- Запросы к API (на примере получения всех записей пользователя со стены)
- Резюме
ВК-API блиц
ВК предоставляет несколько реализаций API:
- Streaming/Long Poll — позволяет получить данные в реальном времени. Сразу же, при обновлении данных в ВК, мы получаем актуальную информацию, без обновления страницы. Streaming и Long Poll реализуют разные подходы, но суть их одинаковая.
- Виджеты для сайта — здесь всё просто: скопировал код, без хитрых настроек, и у тебя рабочий виджет на сайте.
- Open API — работает на клиенте. Так же просто настраивается и используется. Преимуществом является то, что не обязательно иметь сервер для выполнения запросов. Будет работать в обычном HTML + JS.
- Callback API — позволяет получать данные от самомого ВК, не выполняя запрос. В случае обновления данных, ВК сам нам присылает новые данные. Например, пользователь подписался на нашу группу, и ВК, автоматически пришлёт информацию об этом пользователе нашему скрипту.
- REST API — позволяет взаимодействовать с данными ВК из скрипта. Позволяет автоматизировать любые пользовательские действия.
Для нас, как для программистов, на данном этапе — интересен REST API. Который позволяет взаимодействовать с пользователями, группами, рекламой, и прочими сущностями. Подробнее, обо всех доступных методах можно почитать здесь.
Для получение доступа к REST API, необходимо иметь специальный ключ vk api token. Это уникальное значение, аналогично логину и паролю — идентифицирует пользователя, от имени которого выполняются запросы.
Как гласит 2 правило проектирования REST API — между запросами не должно сохраняться состояния. Система по определению не может использовать сессии, потому применение токена актуально для идентификации пользователя.
Что такое ОAuth2.0?
- Вместо привычных логина и пароля, которые имеют определенный набор прав и время жизни, мы получаем доступ к ресурсам с помощью случайно сгенерированных строк — токенов
. - Можно выдавать права максимально точечно
, опираясь на собственные пожелания, а не на заранее определённый набор прав.
Роли
- Resource owner
— сущность, которая имеет права доступа на защищённый ресурс. Сущность может быть конечным пользователем или какой-либо системой. Защищённый ресурс — это HTTP endpoint, которым может быть что угодно: API endpoint, файл на CDN, web-сервис. - Resource server
— сервер, на котором хранится защищённый ресурс, к которому имеет доступ resource owner. - Client
. Это приложение, которое запрашивает доступ к защищённому ресурсу от имени resource owner и с его разрешения — с авторизацией. - Authorization server
— сервер, который выдаёт клиенту токен для доступа к защищённому ресурсу, после успешной авторизации resource owner.
Регистрация клиента
фантазииRedirection URIClient type
- Confidential
— клиент, который может безопасно хранить свои учётные данные. Например, к такому типу клиентов относят web-приложения, имеющие backend. - Public
— не может безопасно хранить свои учётные данные. Этот клиент работает на устройстве владельца ресурса, например, это браузерные или мобильные приложения.
Абстрактный OAuth 2.0. Flow c применением Access token
- Client отправляет запрос на доступ к требуемому ресурсу resource owner.
- Resource owner передаёт обратно клиенту authorization grant, который подтверждает личность resource owner и его права на ресурс, доступ к которому запрашивает client. В зависимости от flow это может быть токен или учётные данные.
- Client отправляет authorization grant, полученный в предыдущем шаге authorization server, ожидая от него Access token для доступа к защищённому ресурсу.
- authorization server убеждается в валидности authorization grant, после чего отсылает access token клиенту в ответ.
- Получив access token, клиент запрашивает защищённый ресурс у resource server.
- Resource server убеждается в корректности access token, после чего предоставляет доступ к защищённому ресурсу.
Абстрактный OAuth 2.0. Flow c применением Refresh token
- Client приходит c authorization grant к authorization server и просит предоставить ему access token и refresh token.
- Authorization server убеждается, что с authorization grant всё нормально и возвращает клиенту запрошенные access token и refresh token.
- Client с access token запрашивает защищённый ресурс, пока не получит первую ошибку доступа к ресурсу — invalid token error.
- После получения ошибки доступа, клиент идет к authorization server с refresh token и просит заменить просроченный access token на новый.
- В ответ клиент получает новый access token, а также новый refresh token, либо продлевается время жизни старого refresh token.
Как получить токен VK.COM
Получение токена состоит из двух частей: регистрации своего приложения и получение токена в этом приложении.
Создать приложение можно на странице. Указав название приложения, и выбрав его тип. Я выбираю Standalone, потому что тогда можно будет получить токены с бОльшим возможностями, чем в остальных вариантах (придётся поверить мне на слово, что это правда).
Создав приложение и перейдя на вкладку настроек, будет показано: id приложения, секретный ключ
Теперь, имея id приложения, можно получить токен доступа. Для этого нужно сформировать ссылку, подставив в неё id своего приложения.
где вместо нужно вставить id своего приложения. а в параметре scope — перечислены разрешения, которыми мы хотим наделить токен, список всех разрешений Однако здесь, одним из самых важных разрешений является offline, которое создаёт бессрочный токен, не имеющий ограниченного времени жизни.
Если вы не хотите создавать своё приложение, то можете получить токен по ссылке
Перейдя по сформированной ссылке, откроется диалоговое окно, в которому будут зачитаны права показаны разрешения, которыми наделяется токен (чем больше указано scope свойств, тем больше будет этот список)
Подтвердив, произойдёт переадресация на страницу, в адресной строке которой будет access_token, expires_in равный нулю (что логично, учитывая, что мы указывали создание вечного токена)
Я сократил токен для сохранения читабельности. У вас он будет длиннее
Скопировав этот токен, можно делать первые запросы к API.
Где взять access_token
Токены создаются по запросу на специальном сайте. Там на сегодняшний день нет никакого удобного интерфейса, вся работа происходит через строку браузера. Методы получения access_token разные для пользователей, приложений или сообществ. Наиболее простой способ известен как Implicit flow, он подразумевает как раз использование прямой ссылки на упомянутый сайт.
Вот, например, как можно получить token, если требуется предоставить доступ к базе данных ВК какому-либо внутреннему приложению (из тех, которые пользователи могут подключать к своим страницам).
Получение токена через собственное приложение
Сначала ваша программа должна быть зарегистрирована на сайте Вконтакте и иметь собственный ID. Как это сделать, читайте в официальной документации социальной сети, в разделе, посвящённом разработке.
Далее, для получения token доступа вам нужна вот такая строка:
Здесь вместо ХХХХХХХ требуется подставить client_id вашего приложения.
В параметре scope указаны права, которые требуется передать программе. Они в примере перечислены через запятую. Их может быть довольно много, все они перечислены на особой странице документации.
Вставьте этот запрос в адресную строку браузера и нажмите Enter. Вы увидите страницу, где нужно будет подтвердить права доступа. Здесь будет название приложения, описания запрашиваемых прав и фамилия владельца аккаунта.
Состав иконок, отображающих права, определяется параметром scope из переданной адресной строки.
После клика на кнопке «Разрешить» откроется страница, в адресной строке будет параметр access_token, который и требуется.
Получение токена через официальное приложение VK
Здесь всё то же самое, только получать client_id для программы уже не нужно, она давно зарегистрирована. Используйте такую строку:
Перед тем, как передать строку серверу, целесообразно отредактировать содержимое параметра scope в соответствии с вашими потребностями.
Здесь мы привели только общие сведения о том, что такое токен доступа ВК и как его получают. За более подробными сведениями нужно обращаться в справочный раздел для разработчиков на сайте социальной сети.
Как делать запросы к API
Сохраним полученный токен, потому как его нужно будет прикреплять к каждому запросу к VK API.
Для того, чтобы сделать запрос к API из PHP, нам нужна любая из доступных функций, способных совершить HTTP-запрос: file_get_contents, curl.
К слову, даже, если открыть в браузере сформированный адрес, то получим результат
Запрос к методам API состоит из шаблона: https://api.vk.com/method/?v= где — имя метода — параметры, индивидуальные, в зависимости от метода — ранее сохранённый токен — версия API (на момент написания статья = 5.78)
Зная всё это, сделаем первый запрос, на получение всех личных записей со стены. За стену отвечает сущность wall, а метод его get, который возвращает список всех записей со стены пользователя. И, в итоге, имя метода будет сформировано в виде имени сущности (wall).имя метода (get) — wall.get
Так, первая часть URL-адреса уже сформирована: https://api.vk.com/method/wall.get
Теперь нужно определиться с передаваемыми параметрами (PARAMS). Все доступные, обязательные параметры с описанием можно посмотреть на странице метода.
Я буду передавать owner_id который соответствует id моего пользователя.
По факту же, это поле является необязательным в текущих условиях. Так как по умолчанию, ownwer_id будет проставлен id текущего пользователя.
И, можно было бы просто дописать в виде строки к существующему URL-адресу: …?owner_id=120159853
Однако, если туда добавлять множество новых параметров, то в таком виде добавлять не удобно. Потому, я создам массив параметров, где ключом будет название параметра, а значение, соответственно, его значение. А с помощью функции http_build_query() можно привести массив к виду строки нужного вида:
$params = [ ‘owner_id’ => 120159853, //params2 => ‘value2’, ]; http_build_query($params); //owner_id=120159853 $token = ’38fa46d4c0c10bab105c760cc44ed373c0bc6a34405931f34c765ea’; $version = 5.78; $params = http_build_query([ ‘owner_id’ => 120159853, ‘access_token’ => $token, ‘v’ => $version //… ]); $url = «https://api.vk.com/method/?v=»; //https://api.vk.com/method/wall.get?owner_id=120159853v=5.78
При том, что даже токен и версию теперь можно вынести в массив $params, для более централизованной записи.
Осталось последний шаг — выполнение http-запроса. И, принимая тот факт, что данные возвращаются в виде JSON, то, результат, нужно дополнительно обернуть в функцию json_decode, которая приведёт JSON к обычному PHP-массиву. Вот так просто декодировать JSON.
$result = json_decode(file_get_contents($url), true);
В итоге, получаем обычный массив записей, который можем обработать как пожелаем
И, исходя из ответа выше, для получения записей выполним:
//все записи $orders = $result[‘response’][‘items’]; //первая запись $order = $result[‘response’][‘items’][0];
Источник: kk360.ru
Авторизация в API
Реализация протокола OAuth2 в API
Для аутентификации и авторизации в API используется протокол OAuth2, из спецификации которого реализовано две стандартные схемы (flow): Client Credentials Grant и Authorization Code Grant, и одна нестандартная – Agency Client Credentials Grant.
Client Credentials Grant используется для работы с данными собственного аккаунта через API.
Agency Client Credentials Grant используется для работы с данными собственных клиентов агентств/менеджеров.
Authorization Code Grant используется для получения доступа к данным сторонних аккаунтов myTarget.
Первые две схемы доступны каждому API-клиенту, доступ к схеме Authorization Code Grant предоставляется только при выполнении условий.
Используя любой из данных методов, вы получите объект Access Token, содержащий ключи access_token и refresh_token. Ключом access_token должен быть подписан каждый запрос к API:
GET /api/v2/campaigns.json HTTP/1.1 Host: target.my.com Authorization: Bearer
Следует помнить, что доступ к данным аккаунта возможен только с токеном, полученным для данного аккаунта. Это значит, что нельзя, к примеру, просмотреть кампании клиента агентства, подписав запрос токеном самого агентства. Подробнее о типах аккаунта и процессе авторизации в расширенной инструкции по авторизации.
Client Credentials Grant
Чтобы получить токен доступа, нужно послать запрос вида:
POST /api/v2/oauth2/token.json HTTP/1.1 Host: target.my.com Content-Type: application/x-www-form-urlencoded grant_type=client_credentialsclient_secret=
В случае успешного выполнения ответ будет выглядеть следующим образом:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 < «access_token»: «», «token_type»: «bearer», «scope»: «», «expires_in»: «86400», «refresh_token»: «» >
Agency Client Credentials Grant
Эта схема протокола OAuth2 не является стандартной. Она была реализована для того, чтобы дать возможность агентствам и менеджерам создавать токены доступа для своих клиентов без подтверждения от клиента. Схема очень похожа на стандартную Client Credentials Grant за исключением того, что в запросе нужно передавать дополнительный параметр «agency_client_name» или «agency_client_id» (username или user id из запроса AgencyClients или ManagerClients):
POST /api/v2/oauth2/token.json HTTP/1.1 Host: target.my.com Content-Type: application/x-www-form-urlencoded grant_type=agency_client_credentialsclient_secret=redirect_uri» — на него myTarget будет перенаправлять пользователей после предоставления (или отказа) ими доступа к своему аккаунту API-клиенту.
Алгоритм получения доступа выглядит следующим образом:
API-клиент перенаправляет пользователя на специальную страницу https://target.my.com/oauth2/authorize, указав параметры «response_type» (со значением «code»), «state» (сгенерированный на стороне клиента токен, используется для предотвращения CSRF — может содержать произвольный набор символов), свой «client_id» и список прав доступа «scope»:
GET /oauth2/authorize?response_type=codestate=redirect_uri» при регистрации клиента, передавая параметры «code» (специальный токен со сроком жизни в один час) и «state» (то же значение, что было передано в первоначальном запросе):
GET ?code=user_id= HTTP/1.1 Host:
Ответ содержит в том числе параметр user_id, в котором содержится идентификатор пользователя, предоставляющего доступ.
Так же получить user_id по code:
POST /api/v2/oauth2/code_info.json HTTP/1.1 Host: target.my.com Content-Type: application/x-www-form-urlencoded code=client_secret=
Пример успешного ответа:
Если в вашем приложении уже есть токен для этого пользователя, можно продолжать использовать существующий, чтобы избежать превышения лимита токенов и не дублировать токены.
Получив параметр «code», клиент может запросить «access_token» для дальнейшей работы с API от имени пользователя. Для этого нужно послать запрос на /api/v2/oauth2/token.json, передав параметры «grant_type» (со значением «authorization_code»), «code» (полученный при обратном редиректе на «redirect_uri» токен):
POST /api/v2/oauth2/token.json HTTP/1.1 Host: target.my.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_codeclient_id=
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 < «access_token»: «», «token_type»: «Bearer», «scope»: [«», «»], «expires_in»: 86400, «refresh_token»: «» >
Полученный токен доступа используется для аутентификации запросов, посылаемых в API от имени пользователя:
GET /api/v2/campaigns.json HTTP/1.1 Host: target.my.com Authorization: Bearer
Для получения токенов клиентов предоставившего доступа агентства или менеджера, необходимо воспользоваться расширенной схемой Agency Client Credentials. Для этого помимо параметра agency_client_name и других, необходимо указать полученный токен агентства в параметре access_token:
POST /api/v2/oauth2/token.json HTTP/1.1 Host: target.my.com Content-Type: application/x-www-form-urlencoded grant_type=agency_client_credentialsclient_secret=access_token=
В случае успешного выполнения запроса в ответе будет содержаться токен доступа для осуществления операций от имени клиента агентства или менеджера.
Scopes — права доступа
Права доступа определяют, какие действия может произвести API-клиент с данными предоставившего доступ аккаунта. Необходимые права указываются через запятую в параметре «scope» запроса доступа у пользователя в схеме Authorization Code Grant. В зависимости от типа пользователя запрашиваемые права доступа делятся на три группы.
- read_ads — чтение статистики и РК;
- read_payments — чтение денежных транзакций и баланса;
- create_ads — создание и редактирование настроек РК, баннеров, аудиторий (ставки, статус, таргетинги и т.п.).
- create_clients — создание новых клиентов;
- read_clients — просмотр клиентов и операции от их имени;
- create_agency_payments — переводы средств на счёта клиентов и обратно.
- read_manager_clients — просмотр клиентов и операции от их имени;
- edit_manager_clients — изменение параметров клиентов;
- read_payments — чтение денежных транзакций и баланса.
Работа с токенами
Лимит на количество токенов
Для каждой связки clientId — user одновременно может существовать не более 5 токенов, вне зависимости от статуса токена. Если один и тот же аккаунт подключен к двум различным приложениям, то каждое из приложений сможет выписать по 5 токенов для данного аккаунта. Лимит фиксирован и не может быть увеличен ни в каких случаях.
Не вечные токены автоматически удаляются по истечении месяца неактивности (указано в поле «expires_in»).
По достижении лимита в ответ на попытку получить новый токен будет возвращена ошибка с HTTP-кодом 403.
Во избежание подобных ошибок, необходимо корректно обновлять выписанные токены и не создавать их избыточные копии.
Удаление токенов
При достижении лимита на количество токенов можно самостоятельно удалить все токены конкретного пользователя. Для этого используется запрос вида:
POST /api/v2/oauth2/token/delete.json HTTP/1.1 Host: target.my.com Content-Type: application/x-www-form-urlencoded client_id==
где «username» – это логин пользователя (user_id — id пользователя), для которого необходимо удалить токены. Если параметр «username» или «user_id» не передан, то будут удалены токены аккаунта, для которого был выдан доступ к API.
Срок действия access-токена
Каждый полученный токен доступа по умолчанию является действительным в течение суток. На это указывает свойство «expires_in» в ответе на запрос токена доступа. Ограниченный срок жизни позволяет более надёжно защитить значение «access_token». Даже завладев значением одного «access_token», злоумышленник не сможет выполнить запросы с ним по истечении срока действия или после первого обновления токена.
Менее безопасный способ – «вечные» токены доступа. Для получения «access_token» без ограничения срока действия, необходимо добавить GET-параметр «permanent=true» в запрос создания или обновления токена. Например:
POST /api/v2/oauth2/token.json HTTP/1.1 Host: target.my.com Content-Type: application/x-www-form-urlencoded grant_type=client_credentialsclient_secret=refresh_token» — специальный токен для обновления ключа access_token и продления времени жизни объекта. За это отвечает схема Refreshing an Access Token в протоколе OAuth2.
Запрос на обновление токена доступа:
POST /api/v2/oauth2/token.json HTTP/1.1 Host: target.my.com Content-Type: application/x-www-form-urlencoded grant_type=refresh_tokenclient_id= charset=UTF-8 < «access_token»: «», «token_type»: «bearer», «scope»: «», «expires_in»: «86400», «refresh_token»: «» >
Важно учитывать, что обновление токена не создаёт новый экземпляр: меняется значение «access_token», старое значение ключа перестаёт работать.
Это может привести к проблемам при работе с API в несколько потоков: два потока могут одновременно обнаружить, что токен истёк и отправить запрос на обновление. Запрос, пришедший первым, обновит токен и начнёт его использовать, в то время как второй поток обновит токен ещё раз, и первый поток будет пытаться использовать уже несуществующий токен.
Одним из вариантов решения этой проблемы является перехват ошибки о несуществующем токене в первом потоке и получение токена заново из общего для потоков хранилища – например, базы данных, куда каждый поток записывает токен после обновления. Нужно также учесть, что запись в хранилище тоже может быть конкурентной, и использовать, например, блокировки.
Другим вариантом решения этой проблемы может быть включение опции обновления «refresh_token» при каждом обновлении «access_token». Тогда первый поток обновит и «access_token», и «refresh_token», а во втором нужно обработать ошибку о неизвестном «refresh_token» и перечитать «access_token» из хранилища. Но при обновления «refresh_token» нужно обязательно хранить его самое последнее значение, иначе вы больше не сможете обновить «access_token», и придётся выписывать новый. Эту опцию OAuth-клиента сейчас можно включить только по запросу в службу поддержки.
Ещё один вариант: превентивное обновление всех истекающих токенов. Он заключается в том, что нужно регулярно проверять нет ли у вас токенов, истекающих, например, в ближайшие пол часа, и обновлять их в фоновом процессе. Но если совмещать его с обновлением в режиме реального времени в рабочих процессах, то всё равно придётся обрабатывать ошибки из-за возможных конфликтов.
Источник: target.my.com