Правильный подход к использованию API Вконтакте
В своё время, бороздя просторы интернета на предмет рационального использования API Вконтакте, я не смог найти чего-то вразумительного, единственные библиотеки, которые были найдены мной были реализованы без использования каких-либо общепринятых практик и без красивого кода. Я решил исправить, сложившееся недоразумение и написал свою библиотеку для работы с API Вконтакте.
Животрепещущие подробности и подходы под хабракатом.
Так уж сложилось, что API Вк, реализован довольно хорошо, за исключением некоторых не логичных моментов, о которых я упомяну позднее. Но речь, сегодня не о качестве, а о конкретном применении.
Сразу необходимо сделать оговорку, помимо описания, я буду приводить куски рабочего кода к моей библиотеке, ссылку на которую я приведу в конце статьи. Библиотека работает на последней стабильной версии 5.5, если вырезать генераторы из пакетного получения, то должно работать на 5.4.
Пример кода, с помощью которого можно провернуть это не хитрое дело.
С момента, когда мы имеем ключ доступа, мы можем выполнять запросы к API. Общая логика запросов проста, вы передаёте специально сформированный запрос на URL API. Запрос должен содержать, название метода и аргументы.
Список методов, это одна из богатых вещей API. В нём вы можете встретить методы, которые не требуют ключ доступа для своей работы, следовательно вызывать их вы можете, не получая его.
При использовании библиотеки нам необходимо создать базовый объект, например так:
Пара примеров запросов с использованием библиотеки:
Через анонимную функцию в each, пройдёт ровно 100 объектов, содержащих данные о пользователях от 1 до 100. Заметьте, если мы уберём вызов функции, то не произойдёт никакого запроса, всё потому что вернётся объект, у которого переопределены магические методы __call и __get, что позволяет нам делать запрос, когда нам это действительно необходимо.
Одна из вещей, что открывает, нам использование генераторов — пакетное получение. То есть, мы получаем данные только тогда, когда они нам нужны. Следующий пример, позволит нам получить ВСЕ наши сообщения, запросами по 100. Будьте внимательны, метод требует от вас прав для messages, Standalone приложения, такой-же авторизации и соответственно передачи ключа доступа.
Хороший метод, который можно отыскать в API — execute. Он принимает параметр code в качестве аргумента, code — некий псевдо JavaScript, который позволяет нам выполнять наш код на стороне сервера, так-же он позволяет выполнять хранимые процедуры, которые мы можем создать при редактировании нашего приложения.
Эту вещь я не смог обойти стороной и реализовал её в библиотеке. В двух словах, она позволяет выполнить несколько запросов, как один. Смотрите следующий пример кода.
Как и обещал, одно из тех недоразумений, которое вы можете встретить в текущей версии API(5.21), метод users.get вернёт нам response, как массив, хотя в других местах, например friends.get, начиная с версии номер 5, нам возвращаются поля count и items, мне кажется это не совсем логичным, к тому же это требует лишнего кода при работе с API.
Так-же в библиотеке реализованы обработчики для некоторых операций, с вашей помощью их может стать больше.
С использованием библиотеки мы можем добиться довольно приятного и красивого кода, а это, самое важное в нашем не лёгком деле.
Вполне вероятно, что в коде остались какие-то недоразумения или баги, надеюсь на вашу внимательность и Pull Requests приветствуются.
Библиотека в большинстве своём отвечает стандарту PSR-0.
Надеюсь, мне удалось показать вам, что API Вконтакте не страшно, а даже приятно.
Благодарю за внимание!
UPDATE:
Можно установить через Composer: composer require «getjump/vk:*»
UPDATE 2:
Теперь минимальная версия 5.4, теоретически(по идее не используется большинство его функционала) может завестись и на 5.3, если не использовать короткий синтаксис для массивов.
Как узнать api вконтакте
Используйте Authorization Code Flow для вызова методов API ВКонтакте с серверной части Вашего приложения (например, из PHP). Ключ доступа, полученный таким способом, не привязан к IP-адресу, но набор прав, которые может получить приложение, ограничен из соображений безопасности.
Необходимо перенаправить браузер пользователя по адресу
https://oauth.vk.com/authorize, передав следующие параметры:
Если пользователь не вошел на сайт, то в диалоговом окне ему будет предложено ввести свой логин и пароль.
После успешного входа на сайт пользователю будет предложено авторизовать приложение, разрешив доступ к необходимым настройкам, запрошенным при помощи параметра scope. Полный список настроек доступен в разделе прав доступа приложений.
Обратите внимание, что некоторые права доступа пользователя из списка (например, messages) могут быть запрошены только Standalone-приложением — что означает необходимость использования Implicit Flow для запроса таких прав.
Параметр code может быть использован в течение 1 часа для получения ключа доступа к API access_token с Вашего сервера.
В случае возникновения ошибки браузер пользователя будет перенаправлен с кодом и описанием ошибки:
Для получения access_token необходимо выполнить запрос с Вашего сервера на https://oauth.vk.com/access_token, передав следующие параметры:
| client_id обязательный | Идентификатор Вашего приложения |
| client_secret обязательный | Защищенный ключ Вашего приложения (указан в настройках приложения) |
| redirect_uri обязательный | URL, который использовался при получении code на первом этапе авторизации. Должен быть аналогичен переданному при авторизации. |
| code обязательный | Временный код, полученный после прохождения авторизации. |
Пример запроса:
В результате выполнения данного запроса Ваш сервер получит вновь созданный access_token. Вместе с access_token серверу возвращается время жизни ключа expires_in в секундах. expires_in содержит 0, если токен бессрочный (при использовании scope = offline). Процедуру авторизации приложения необходимо повторять в случае истечения срока действия access_token, смены пользователем своего логина или пароля или удаления приложения из настроек.
Если у пользователя указан email, а приложением были запрошены соответствующие права, сервер также вернет email пользователя.
В случае ошибки будут переданы параметры error и error_description.
Как узнать api вконтакте
Для приложений на iOS, Android, Windows Phone мы рекомендуем использовать упрощенную схему авторизации через SDK.
Необходимо перенаправить браузер пользователя по адресу
https://oauth.vk.com/authorize, передав следующие параметры:
Redirect_uri — это URL, на который будет переадресован браузер пользователя после разрешения им прав доступа.
Если Вы разрабатываете веб-приложение и хотите работать с API из Javascript, в redirect_uri необходимо указать адрес страницы на Вашем сайте. В целях безопасности, этот адрес также должен быть указан в настройках Вашего приложения (поля «Адрес сайта», «Базовый домен» и «Доверенный Redirect URI»).
Обратите внимание, Вы не сможете работать с методами, которые помечены как доступные только для Standalone-приложений.
Во всех остальных случаях (мобильное, десктопное приложение) необходимо использовать redirect_uri по умолчанию: https://oauth.vk.com/blank.html
Если пользователь не авторизован ВКонтакте в используемом браузере, то в диалоговом окне ему будет предложено ввести свой логин и пароль.
После успешного входа на сайт пользователю будет предложено авторизовать приложение, разрешив доступ к необходимым настройкам, запрошенным при помощи параметра scope. Полный список настроек доступен в разделе прав доступа приложений.
С ключом пользователя, полученным в Implicit Flow, можно работать с наибольшим количеством прав доступа и соответствующих методов по сравнению с остальными способами авторизации.
Обратите внимание, что некоторые права могут быть запрошены только Standalone-приложением (например, право доступа messages). Это автоматически означает необходимость использования redirect_uri по умолчанию (см. redirect_uri).
После успешной авторизации приложения браузер пользователя будет перенаправлен по адресу redirect_uri, указанному при открытии диалога авторизации. При этом ключ доступа к API access_token и другие параметры будут переданы в URL-фрагменте ссылки:
Вместе с ключом access_token также будет указано время его жизни expires_in, заданное в секундах. expires_in содержит 0, если токен бессрочный (при использовании scope = offline). Если срок использования ключа истек, то необходимо повторно провести все описанные выше шаги, но в этом случае пользователю уже не придется дважды разрешать доступ. Запрашивать access_token также необходимо при смене пользователем логина или пароля или удалением приложения в настройках доступа.
Кроме того, среди возвращаемых параметров будет указан user_id — идентификатор авторизовавшегося пользователя.
В случае возникновения ошибки авторизации в качестве GET-параметров в redirect_uri будет передана информация об этой ошибке.
Как узнать api вконтакте
В методе market.editOrder добавлены поля, которые может изменять администратор сообщества: delivery_price — стоимость доставки;
track_number — трек-номер;
payment_status — статус оплаты.
Так же появились новые поля для редактирования габаритов и веса заказа:
width — ширина;
length — длина;
height — высота;
weight — вес.
Также поле merchant_comment теперь сохраняет комментарий продавца.
В объекте записи появилась информация о VK Donut.
В объекте комментария появилась информация о VK Donut.
В объекте товара поля date и views_count теперь возвращаются только администратору группы, которой принадлежит товар.
В объекте заказа информация о доставке и заказчике вынесена из основного объекта в новые подобъекты: delivery и recepient.
Формат ответа storage.get для одного ключа key изменился, теперь возвращается объект того же типа, что и при передаче keys.
apps.get и объект приложения добавлены 2 новых поля:
mobile_controls_type и mobile_view_support_type, которые описывают, как отображаются элементы управления для игр в вебвью в нативных клиентах.
mobile_controls_type = 0 — чёрная полоска над областью с игрой;
mobile_controls_type = 1 — прозрачный элемент управления поверх области с игрой;
mobile_controls_type = 2 — только для vk apps, без контроллов.
mobile_view_support_type = 0 — игра не использует нижнюю часть экрана на iPhoneX, черная полоса есть.
mobile_view_support_type = 1 — игра использует нижнюю часть экрана на iPhoneX, черной полосы нет.
Для метода ads.getPostsReach изменилось поведение при ошибках, они будут возвращаться для каждого объявления отдельно.
Метод ads.getAdsPostsReach отключён, вместо него следует использовать ads.getPostsReach.
Поддержка новых типов клавиш в клавиатуре ботов.
В Callback API и LongPoll API у события message_new вместо < object: message >будет приходить < object: < message, client_info >>.
В client_info содержится информация о клиенте полезная для формирования сообщений ботами.
В методах секции messages доступен аттач-история.
Сообщения, которые не влезают в Bots Long Poll API или Callback API будут обрезаны и иметь пометку is_cropped. В случае обрезания остается одно пересланное сообщение или ответ и только одно вложение на каждое сообщение.
Для методов ads.createTargetGroup и ads.updateTargetGroup параметр lifetime станет обязательным. Параметр будет принимать значения от 1 до 720.
Истории в stories.get в рамках одного автора приходят в хронологическом порядке. Раньше приходили в обратном.
Методы работы со стеной возвращают новый аттач-сниппет для событий с типом events
Обложки в объекте видео теперь передаются в полях image и first_frame в виде массивов объектов video_image.
Обложки в объекте альбома видео теперь передается в поле image в виде массива объектов video_image.
Параметры limit, count и offset в методе messages.deleteConversation объявлены устаревшими.
Метод wall.edit в случае успеха возвращает post_id — идентификатор отредактированного поста.
Методы market.add, market.edit принимают параметр url. Объект market теперь может возвращать url и button_title.
Метод wall.createComment возвращает новую ошибку 222
В объекте сообщения разделены ответы и пересланные сообщения (reply_message и fwd_messages).
VkApi (основной класс)¶
login (str) – Логин ВКонтакте (лучше использовать номер телефона для автоматического обхода проверки безопасности)
password (str) – Пароль ВКонтакте (если пароль не передан, то будет попытка использовать сохраненные данные)
token (str) – access_token
auth_handler – Функция для обработки двухфакторной аутентификации, должна возвращать строку с кодом и булево значение, означающее, стоит ли запомнить это устройство, для прохождения аутентификации.
captcha_handler – Функция для обработки капчи, см. captcha_handler()
config ( jconfig.base.BaseConfig ) – Класс для сохранения настроек
config_filename – Расположение config файла для jconfig.config.Config
api_version (str) – Версия API
app_id (int) – app_id Standalone-приложения
scope (int or str) – Запрашиваемые права, можно передать строкой или числом. См. VkUserPermissions
client_secret – Защищенный ключ приложения для Client Credentials Flow авторизации приложения (https://vk.com/dev/client_cred_flow). Внимание: Этот способ авторизации устарел, рекомендуется использовать сервисный ключ из настроек приложения.
login и password необходимы для автоматического получения токена при помощи Implicit Flow авторизации пользователя и возможности работы с веб-версией сайта (включая vk_api.audio.VkAudio )
session ( requests.Session ) – Кастомная сессия со своими параметрами(из библиотеки requests)
reauth – Позволяет переавторизоваться, игнорируя сохраненные куки и токен
token_only –
Включает оптимальную стратегию аутентификации, если необходим только access_token
Например если сохраненные куки не валидны, но токен валиден, то аутентификация пройдет успешно
При token_only=False, сначала проверяется валидность куки. Если кука не будет валидна, то будет произведена попытка аутетификации с паролем. Тогда если пароль не верен или пароль не передан, то аутентификация закончится с ошибкой.
Если вы не делаете запросы к веб версии сайта используя куки, то лучше использовать token_only=True
Проверка Cookies remixsid на валидность
Получение access_token из code
captcha – объект исключения Captcha
need_validation_handler ( error ) [source] ¶ Обработчик проверки безопасности при запросе API
error – исключение
Обработчик ошибок соединения
error – исключение
too_many_rps_handler ( error ) [source] ¶ Обработчик ошибки “Слишком много запросов в секунду”.
Ждет полсекунды и пробует отправить запрос заново
error – исключение
Обработчик двухфакторной аутентификации
Позволяет обращаться к методам API как к обычным классам. Например vk.wall.get(…)
method (str) – название метода
values (dict) – параметры
captcha_sid – id капчи
captcha_key (str) – ответ капчи
raw (bool) – при False возвращает response[‘response’] при True возвращает response (может понадобиться для метода execute для получения execute_errors)
class vk_api.vk_api. VkUserPermissions ( value ) [source]¶
Перечисление прав пользователя. Список прав получается побитовым сложением (x | y) каждого права. Подробнее в документации VK API: https://vk.com/dev/permissions
Пользователь разрешил отправлять ему уведомления (для flash/iframe-приложений). Не работает с этой библиотекой.
Доступ к фотографиям.
Доступ к аудиозаписям. При отсутствии доступа к закрытому API аудиозаписей это право позволяет только загрузку аудио.
Доступ к видеозаписям.
Доступ к wiki-страницам.
Добавление ссылки на приложение в меню слева.
Доступ к статусу пользователя.
Доступ к заметкам пользователя.
Доступ к расширенным методам работы с сообщениями.
Доступ к обычным и расширенным методам работы со стеной.
Доступ к расширенным методам работы с рекламным API.
Доступ к API в любое время. Рекомендуется при работе с этой библиотекой.
Доступ к документам.
Доступ к группам пользователя.
Доступ к оповещениям об ответах пользователю.
Доступ к статистике групп и приложений пользователя, администратором которых он является.
