Go to file
Steven Bazyl 8b2c139778 Resolve merge/rebase 2012-10-10 14:52:32 -06:00
bin Remove embedded version #s, use Gemfile 2012-10-10 14:24:25 -06:00
lib Re-org service account support 2012-10-10 14:28:46 -06:00
spec Issue 59 - handle 204 responses more gracefully 2012-10-10 14:28:46 -06:00
tasks Updating version and dependencies. 2012-07-31 16:56:17 +03:00
yard Added super-hacky script to generate the wiki reference pages. 2011-12-02 17:24:56 +03:00
.gitignore Ignore .rvmrc file 2012-06-14 10:48:29 +02:00
.rspec Upgrade RSpec 1.x to RSpec 2.10-x 2012-06-14 11:18:35 +02:00
.travis.yml Adding Steven to the Travis notification list. 2012-05-11 13:53:17 +03:00
.yardopts Add .yardopts for doc hosting 2012-07-19 14:14:03 -07:00
CHANGELOG.md Resolve merge/rebase 2012-10-10 14:52:32 -06:00
Gemfile Remove embedded version #s, use Gemfile 2012-10-10 14:24:25 -06:00
LICENSE Basic project skeleton. 2010-07-28 19:30:56 +00:00
README.md Doc improvements 2012-10-10 14:28:46 -06:00
Rakefile Updating dependencies. 2012-07-21 13:51:23 +03:00
google-api-client.gemspec Added the ability to create an authorization object from client secrets. 2012-10-05 12:07:42 +03:00

README.md

Google API Client

Homepage
http://code.google.com/p/google-api-ruby-client
Author
Bob Aman
Copyright
Copyright © 2011 Google, Inc.
License
Apache 2.0

Build Status Dependency Status

Description

The Google API Ruby Client makes it trivial to discover and access supported APIs.

Install

Be sure http://rubygems.org/ is in your gem sources.

For normal client usage, this is sufficient:

$ sudo gem install google-api-client

The command line interface, the example applications, and the test suite require additional dependencies. These may be obtained with:

$ sudo gem install google-api-client --development --force --no-rdoc --no-ri

Example Usage

# Initialize the client & Google+ API
require 'google/api_client'
client = Google::APIClient.new
plus = client.discovered_api('plus')

# Initialize OAuth 2.0 client    
client.authorization.client_id = '<CLIENT_ID_FROM_API_CONSOLE>'
client.authorization.client_secret = '<CLIENT_SECRET>'
client.authorization.redirect_uri = '<YOUR_REDIRECT_URI>'

client.authorization.scope = 'https://www.googleapis.com/auth/plus.me'

# Request authorization
redirect_uri = client.authorization.authorization_uri

# Wait for authorization code then exchange for token
client.authorization.code = '....'
client.authorization.fetch_access_token!

# Make an API call
result = client.execute(
  :api_method => plus.activities.list,
  :parameters => {'collection' => 'public', 'userId' => 'me'}
)

puts result.data

API Features

API Discovery

To take full advantage of the client, load API definitions prior to use. To load an API:

urlshortener = client.discovered_api('urlshortener')

Specific versions of the API can be loaded as well:

drive = client.discovered_api('drive', 'v2')

Locally cached discovery documents may be used as well. To load an API from a local file:

doc = File.read('my-api.json')
my_api = client.register_discovery_document('myapi', 'v1', doc)

Authorization

Most interactions with Google APIs require users to authorize applications via OAuth 2.0. The client library uses Signet to handle most aspects of authorization. For additional details about Google's OAuth support, see Google Developers.

Credentials can be managed at the connection level, as shown, or supplied on a per-request basis when calling execute.

For server-to-server interactions, like those between a web application and Google Cloud Storage, Prediction, or BigQuery APIs, use service accounts. Assertions for service accounts are made with Google::APIClient::JWTAsserter.

client = Google::APIClient.new
key = Google::APIClient::PKCS12.load_key('client.p12', 'notasecret')
service_account = Google::APIClient::JWTAsserter(
    '123456-abcdef@developer.gserviceaccount.com',
    'https://www.googleapis.com/auth/prediction',
    key)
client.authorization = service_account.authorize

Batching Requests

Some Google APIs support batching requests into a single HTTP request. Use Google::APIClient::BatchRequest to bundle multiple requests together.

Example:

client = Google::APIClient.new
urlshortener = client.discovered_api('urlshortner')

batch = Google::APIClient::BatchRequest.new do |result|
    puts result.data
end

batch.add(:api_method=>urlshortener.url.insert, 
          :body_object => { 'longUrl' => 'http://example.com/foo' })
batch.add(:api_method=>urlshortener.url.insert, 
          :body_object => { 'longUrl' => 'http://example.com/bar' })
client.execute(batch)

Blocks for handling responses can be specified either at the batch level or when adding an individual API call. For example:

batch.add(:api_method=>urlshortener.url.insert, :body_object => { 'longUrl' => 'http://example.com/bar' }) do |result|
   puts result.data
end

Media Upload

For APIs that support file uploads, use Google::APIClient::UploadIO to load the stream. Both multipart and resumable uploads can be used. For example, to upload a file to Google Drive using multipart

drive = client.discovered_api('drive', 'v2')

media = Google::APIClient::UploadIO.new('mymovie.m4v', 'video/mp4')
metadata = {
    'title' => 'My movie',
    'description' => 'The best home movie ever made'
}
client.execute(:api_method => drive.files.insert,
               :parameters => { 'uploadType' => 'multipart' },
               :body_object => metadata,
               :media => media )

To use resumable uploads, change the uploadType parameter to resumable. To check the status of the upload and continue if necessary, check result.resumable_upload.

client.execute(:api_method => drive.files.insert,
           :parameters => { 'uploadType' => 'resumable' },
           :body_object => metadata,
           :media => media )
upload = result.resumable_upload

# Resume if needed
if upload.resumable?
    client.execute(upload)
end