alextalker / vk-ruby Goto Github PK

#VK-RUBY

Ruby wrapper for vk.com API. Documentation.

VK-RUBY gives you full access to all API features:

• Has several types of methods naming and methods calling
• Parallel method calling
• All authorization methods
  • Site
  • Server
  • Standalone
• File uploading
• Any faraday features
• IRB integration

To get started, you need to register with vk.com own application and get the keys and read VK API documentation.

gem install vk-ruby

VK-RUBY has many configuration parameters, they are passed in when creating the application. Complete list, see the configuration section.

app = VK::Application.new(app_id: 1, version: '5.26', access_token: '[TOKEN]')

app.friends.getOnline uid: 1 # => Online friends

or

app.friends.get_online uid: 1 # => Online friends

or

app.vk_call 'friends.getOnline', {uid: 1} # => Online friends

The parameters passed to the method call, have a higher priority than the configuration settings. In this example, API version upon request will be equal to 5.1.

VK::Application.new(version: '5.0').get_online(uid: 1, v: '5.1') # HTTP request with v=5.1 param

VK-RUBY also supports parallel execution of requests. More information about parallel requests.

require 'typhoeus'
require 'typhoeus/adapters/faraday'

app.adapter = :typhoeus

manager = Typhoeus::Hydra.new(max_concurrency: 10) # (200 is default)
#manager.disable_memoization

uids = { 1 => {}, 2 => {}, 3 => {}}

app.in_parallel(manager) do 
  uids.each do |uid,_|
    app.users.get(user_ids: uid).each do |user|
      uids[user["id"]] = user
    end
  end
end

puts uids 
#=> {
#  1 => {"id"=>1, "first_name"=>"Павел", "last_name"=>"Дуров"}, 
#  2 => {"id"=>2, "first_name"=>"Александра", "last_name"=>"Владимирова", "hidden"=>1}, 
#  3 => {"id"=>3, "first_name"=>"DELETED", "last_name"=>"", "deactivated"=>"deleted"}
#}

Uploading files to vk servers performed in 3 steps:

1. Getting url to download the file.
2. File download.
3. Save the file.

The first and third steps are produced by calls to certain API methods as described above. Details downloading files, see the relevant section of the documentation.

When you call the upload also need to specify the mime type file.

app.upload(
  'http://example.vk.com/path',{
    file1: ['/path/to/file1.jpg', 'image/jpeg'],
    file2: [File.open('/path/to/file2.png'), 'image/png', '/path/to/file2.png'] 
})

or

app.upload(
  'http://example.vk.com/path',[
    ['/path/to/file1.jpg', 'image/jpeg'],
    [File.open('/path/to/file2.png'), 'image/png', '/path/to/file2.png']
])

VK has several types of applications and several types of authorization. They are different ways of authorization and access rights, more details refer to the documentation.

Site authorization process consists of 4 steps:

1. Opening the browser to authenticate the user on the VK
2. Permit the user to access their data
3. Transfer site value code for the access key
4. Preparation of the application server access key access_token to access the VK API

For the first step you need to generate correct URL

app.authorization_url({
  type: :site,
  app_id: 123,
  settings: 'friends,audio',
  version: '5.26',
  redirect_uri: 'https://example.com/'
})

#=> "https://oauth.vk.com/authorize?client_id=123&scope=friends,audio&redirect_uri=https://example.com/&response_type=token&v=5.26"

Once user permit the to access their data, on specified :redirect_url come GET request with code parameter, which is used to obtain an access_token.

app.site_auth(code: request_params[:code]) #=> { "access_token" : '[TOKEN]', "expires_in" : "100500"}

To access the administrative methods API, which does not require user authentication, you need to get a special access_token. To obtain the key required when creating an application to specify the correct :app_id and :app_secret to the method server_auth.

app.server_auth(app_id: '[APP_ID]', app_secret: '[SECRET]') #=> { "access_token" : '[TOKEN]' }

VK have a client authentication method, it implies a use of using a browser on the client (for example, UIWebView component when creating applications for iOS). In RUBY we can not afford it, and so we use the Mechanize. Most likely it is contrary to the rules of use API, so be careful ;-)

VK implies that the authorization process will consist of three steps:

• Opening the browser to authenticate the user on the site VK
• Permit the user to access their data
• Transfer to the application key access_token to access the API

But VK-RUBY reduces this process in just a single method call

app.client_auth(login: '[LOGIN]', password: '[PASSWORD]') #=> { "access_token" : '[TOKEN]', "expires_in" : "100500"} }

VK-RUBY has a large number of configuration attributes. You can pass them when you create the application, and the method call.

# global config
VK.configure do |config|
  config.app_id = 1
end

VK::Application.new.app_id #=> 1

VK::Application.new(app_id: 2).app_id #=> 2

app = VK::Application.new do |a|
  a.app_id = 3
end

app.app_id #=> 3

In this example, the configuration is only one key, so it does not look difficult.

Below are all the configuration keys for VK-RUBY.

More information on configuring ssl documentation faraday

VK-RUBY based on faraday.

It is an HTTP client lib that provides a common interface over many adapters (such as Net::HTTP) and embraces the concept of Rack middleware when processing the request/response cycle.

Advanced middleware usage.

This stack consists of standard :multipart,:url_encoded, :json middlewares, details of which are looking at [here] (https://github.com/lostisland/faraday#advanced-middleware-usage).

Are also used:

• :http_errors throws an exception if the HTTP status header is different from the 200
• :api_errors throws an exception if the server response contains the API error

And here is set on the default HTTP adapter (Net::HTTP).

app.middlewares = proc do |faraday|
  faraday.request :multipart
  faraday.request :url_encoded

  faraday.response :api_errors
  faraday.response :json, content_type: /\bjson$/
  faraday.response :http_errors

  faraday.adapter Faraday.default_adapter
end

app.middlewares = proc do |faraday|
  faraday.request :multipart
  faraday.request :url_encoded
  faraday.request :retry, max: 5,
                          interval: 0.3,
                          interval_randomness: 0.5,
                          backoff_factor: 2,
                          exceptions: [VK::ApiException,
                                       VK::BadResponseException,
                                       Faraday::TimeoutError]

  faraday.response :api_errors
  faraday.response :json, content_type: /\bjson$/
  faraday.response :http_errors
  faraday.response :vk_logger, logger: Logger.new('/path/to/file.log')

  faraday.adapter :net_http_persistent
end

In this example, additional used :retry middleware. It allows you to conveniently handle certain exceptions specified number of times with a certain interval – very convenient ;-) Also defined here is not the default HTTP adapter (Net::HTTP::Persistent).

Read more middleware usage.

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
• Fork the project
• Start a feature/bugfix branch
• Commit and push until you are happy with your contribution
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.

Copyright (c) 2014 Andrew Zinenko. See LICENSE.txt for further details.