---

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. Существуют несколько методов конфигурации:

1. Через 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
   

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

    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
   

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

    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'
    )
   

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

    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
   

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

    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)
  

License

Copyright © 2013-2018 Alexey Demin, MIT License