Mailru-api

Mailru-api - это гем, предоставляющий простой и лаконичный способ взаимодействия с сервисами @MAIL.RU, реализованный на базе @MAIL.RU REST API (документацию можно найти по ссылке: http://api.mail.ru/docs/guides/restapi/).

Для того, чтобы установить гем выполните команду:

gem install mailru-api

или добавьте следующую строчку в свой Gemfile:

gem "mailru-api", :require => 'mailru/api'

Документация

Конфигурация
Вызов методов @MAIL.RU
Обработка результатов вызова
Примеры из реальной жизни

Конфигурация API

Перед тем как начать непосредственно вызывать методы @MAIL.RU, нужно создать и сконфигурировать API. Существуют несколько методов конфигурации:

Через DSL синтаксис:

api = MailRU::API.new do
  app_id 'your app id is here'
  secret_key 'your secret key is here'
  session_key 'your session key is here when required'
  format MailRU::API::Format::XML
end

Через конфигурирование в блоке

api = MailRU::API.new do |configuration|
  configuration.app_id = 'your app id is here'
  configuration.secret_key = 'your secret key is here'
  configuration.session_key = 'your session key is here when required'
end

Через параметры конструктора

api = MailRU::API.new(
  app_id: 'your app id is here', 
  uid: 'the UID the request made on behalf of', 
  private_key: 'your private key is here',
  session_key: 'your session key is here when required'
)

Путем комбинирования несколько методов конфигурации:

api = MailRU::API.new(app_id: 'your app id is here', secret_key: 'your secret key is here') do
  secret_key 'your secret key is here'
  session_key 'your session key is here when required'
  private_key 'your private key is here'
end

Путем обычной установки параметров

api = MailRU::API.new
app.app_id = 'your app id is here'
app.secret_key = 'your secret key is here'
...

Поддерживаемые параметры конфигурации:

app_id	Идентификатор приложения
secret_key	Значение secret_key из настроек приложения
private_key	Значение private_key из настроек приложения
uid	Идентификатор пользователя, для которого вызывается метод; данный аргумент должен быть указан, если не указан session_key
session_key	Сессия текущего пользователя
format	Формат ответа API; возможные значения: MailRU::API::Format::XML или MailRU::API::Format::JSON (по-умолчанию)

Более подробную информацию можно найти по ссылке http://api.mail.ru/docs/guides/restapi/

Вызов методов @MAIL.RU

После того как объект API создан и сконфигурирован можно начинать взаимодействовать с методами @MAIL.RU. Все методы @MAIL.RU REST API представленны соответствующими Ruby методами в underscore варианте. Например:

REST API метод: friends.getAppUsers
Ruby API метод: friends.get_app_users

Методы вызываются по схеме "Сервер-Сервер" везде, где это возможно. Если этого сделать не возможно (например, не был указан secret_key), будет сделана попытка вызвать метода по схеме "Клиент-Сервер".

Примеры вызова методов:

Метод audio.get:

api.audio.get
api.audio.get(limit: 10)
api.audio.get(offset: 10, limit:20)

Метод notifications.send

uids = ['uid1', 'uid2', ..., 'uidn'].join(',')
text = 'hello'.encode('utf-8')
api.notifications.send(uids: uids, text: text)

Метод users.hasAppPermission

api.users.has_app_permission(ext_perm: 'events')

Что делать если @MAIL.RU обновил API, но их поддержка еще не добавленна в Mailru-api?

Любой метод можно вызвать выполнением HTTP GET или HTTP POST запроса. Для этого Mailru-api предоставляет два метода:

api.get(name, params = {}, secure = MailRU::API::Request::Secure::Any)
api.post(name, params = {}, secure = MailRU::API::Request::Secure::Any)

Вызов метода audio.get через HTTP GET

api.get('audio.get')
api.get('audio.get', limit:10)
api.get('audio.get', offset: 2, limit: 10)

Вызов метода audio.get через HTTP POST
```
api.post('audio.get')
```

Вызов метода notifications.send через HTTP POST

uids = ['uid1', 'uid2', 'uid3'].join(',')
text = 'Тексе сообщения.'.encoding('utf-8')

api.post('notifications.send', {uids: uids, text: text})

Обработка результатов вызова

В зависимости от того, какой формат взаимодействия с API выбран, XML или JSON, все методы будут возвращать соответствующие объекты.

Примеры из реальной жизни

Пример 1

require 'mailru/api'

...

api = MailRU::API.new do |configuration|
  configuration.app_id = 'hidden'
  configuration.secret_key = 'hidden'
  configuration.session_key = 'hidden'
end

begin
  api.events.get_new_count
rescue MailRU::API::PermissionDeniedError => e
  begin
    p "Can not obtain count of new events!"
    p "Has 'events' permission: #{api.users.has_app_permission(ext_perm: 'events')['events']}"
  rescue MailRU::API::Error => e
  end
end

Пример 2

uids = ['uid1', 'uid2', 'uid3'].join(',')
text = message.encoding('utf-8')

MailRU::API.new(app_id: 'hidden', secret_key: 'hidden').notifications.send(uids: uids,text: text)