vkontakte_api

Ruby-адаптер для ВКонтакте API

View the Project on GitHub 7even/vkontakte_api

Что это?

vkontakte_api - ruby-адаптер для ВКонтакте API. Библиотека позволяет вызывать методы API, получая их результаты в виде Hashie::Mash и массивов с ними (за исключением предикатных методов, возвращающих true или false); загружать файлы на сервера ВКонтакте, а также поддерживает авторизацию всех 3 типов, предоставляемых сервисом.

Методы из пространств имен (например, friends.get) реализованы в виде цепных вызовов, например app.friends.get(fields: [:last_name, :first_name]). В соответствии с соглашениями в языке ruby, названия методов пишутся в snake_case, в отличие от официальной документации, использующей camelCase-стиль.

Как этим пользоваться?

Можно использовать vkontakte_api как для авторизованных запросов (требующих авторизованного пользователя, типа friends.get или groups.get без параметра :uid), так и для неавторизованных (типа users.get).

Неавторизованные запросы

Некоторые методы API не требуют авторизации, для их вызова достаточно создать объект VkontakteApi::Client и адресовать методы ему:

require 'vkontakte_api'
@app = VkontakteApi::Client.new
@app.users.get(uid: 1)

Авторизованные запросы

Большинство методов API требуют предварительной авторизации, в результате которой приложение получает токен доступа. Для этой задачи можно использовать сторонние решения наподобие omniauth и omniauth-vkontakte, либо воспользоваться механизмом авторизации, встроенным в vkontakte_api. В первом случае полученный токен нужно просто передать при создании клиента (VkontakteApi::Client.new(token)), а встроенную авторизацию рассмотрим подробнее.

Авторизация

Схема получения токена доступа следующая:

Первое, что нужно сделать - зарегистрировать приложение на vk.com. Идем сюда, вводим название приложения, его домен и тип (для данного примера - веб-сайт). После создания на странице редактирования приложения можно найти ID приложения и защищенный ключ.

Далее необходимо указать в конфигурации vkontakte_api полученные данные, а также URL для редиректа на 2 шаге. Это делается следующим образом:

VkontakteApi.configure do |config|
  config.app_id       = '123'      # ID приложения
  config.app_secret   = 'AbCdE654' # защищенный ключ
  config.redirect_uri = 'http://example.com/oauth/callback'
end

Далее перебрасываем пользователя на ВК для получения прав на доступ к его данным. URL для редиректа возвращается методом VkontakteApi.authorization_url, в его опциях можно указать требуемые права доступа:

VkontakteApi.authorization_url(scope: [:friends, :photos])

При редиректе пользователя обратно в приложение будет передан параметр code:

http://example.com/oauth/callback?code=7a6fa4dff77a228eeda56603b8f53806c883f011c40b72630bb50df056f6479e52a

Теперь, когда у нас есть код, можно получить токен доступа. За это отвечает метод VkontakteApi.authorize - он получает токен и создает клиент, готовый к вызову методов, требующих авторизации:

@vk = VkontakteApi.authorize(code: params[:code])
@vk.friends.get

Использование API

Как уже говорилось, методы из пространств имен вызываются цепочкой, а названия пишутся в snake_case стиле. Параметры всех методов являются именованными, и передаются в виде хэша; при этом если необходимо передать список, разделенный запятыми, его можно оформить как массив из строк или символов - конкатенация произойдет автоматически. Возвращаемые значения - как правило, объекты Hashie::Mash (разновидность хэша, позволяющая доступ к элементам через методы, соответствующие ключам этого хэша) и содержащие их массивы.

@app.groups.get # => [1, 31022447]

friends = @app.friends.get(fields: [:uid, :first_name, :screen_name, :last_name])
friends.first.uid         # => "1"
friends.first.first_name  # => "Павел"
friends.first.screen_name # => "durov"
friends.first.last_name   # => "Дуров"

Более подробно о вызове методов, загрузке файлов, авторизации, логгировании и настройке гема можно почитать в README.

Пример интеграции vkontakte_api с rails-приложением можно посмотреть здесь; исходники проекта находятся тут.