Go to file
Sergio Gomes f06f1e33fa Minor documentation fix 2013-10-29 13:25:55 +00:00
bin don't require faraday/utils; faraday already includes it 2013-08-02 17:13:15 -05:00
lib Minor documentation fix 2013-10-29 13:25:55 +00:00
spec Adding discovery document caching to Service interface 2013-10-29 12:59:52 +00:00
tasks Redo 0.7.0... 2013-09-09 13:58:13 -07: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 Full jruby and rubinius coverage 2013-04-17 22:46:53 -07:00
.yardopts Add .yardopts for doc hosting 2012-07-19 14:14:03 -07:00
CHANGELOG.md Redo 0.7.0... 2013-09-09 13:58:13 -07:00
CONTRIBUTING.md Rename contributing file to match github expectations 2013-09-09 12:48:14 -07:00
Gemfile Update faraday 2013-06-03 16:06:12 -07:00
LICENSE Basic project skeleton. 2010-07-28 19:30:56 +00:00
README.md Link to Github Repo 2013-10-03 09:42:08 -07:00
Rakefile Totally paranoia. 2012-11-19 12:07:37 +03:00
google-api-client.gemspec Redo 0.7.0... 2013-09-09 13:58:13 -07:00

README.md

Google API Client

Homepage
http://www.github.com/google/google-api-ruby-client
Authors
Bob Aman, Steven Bazyl
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 https://rubygems.org/ is in your gem sources.

For normal client usage, this is sufficient:

$ gem install google-api-client

Example Usage

require 'google/api_client'
require 'google/api_client/client_secrets'
require 'google/api_client/auth/installed_app'

# Initialize the client.
client = Google::APIClient.new(
  :application_name => 'Example Ruby application',
  :application_version => '1.0.0'
)

# Initialize Google+ API. Note this will make a request to the
# discovery service every time, so be sure to use serialization
# in your production code. Check the samples for more details.
plus = client.discovered_api('plus')

# Load client secrets from your client_secrets.json.
client_secrets = Google::APIClient::ClientSecrets.load

# Run installed application flow. Check the samples for a more
# complete example that saves the credentials between runs.
flow = Google::APIClient::InstalledAppFlow.new(
  :client_id => client_secrets.client_id,
  :client_secret => client_secrets.client_secret,
  :scope => ['https://www.googleapis.com/auth/plus.me']
)
client.authorization = flow.authorize

# 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.

key = Google::APIClient::KeyUtils.load_from_pkcs12('client.p12', 'notasecret')
client.authorization = Signet::OAuth2::Client.new(
  :token_credential_uri => 'https://accounts.google.com/o/oauth2/token',
  :audience => 'https://accounts.google.com/o/oauth2/token',
  :scope => 'https://www.googleapis.com/auth/prediction',
  :issuer => '123456-abcdef@developer.gserviceaccount.com',
  :signing_key => key)
client.authorization.fetch_access_token!
client.execute(...)

Service accounts are also used for delegation in Google Apps domains. The target user for impersonation is specified by setting the :person parameter to the user's email address in the credentials. Detailed instructions on how to enable delegation for your domain can be found at developers.google.com.

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

Command Line

Included with the gem is a command line interface for working with Google APIs.

# Log in
google-api oauth-2-login --client-id='...' --client-secret='...' --scope="https://www.googleapis.com/auth/plus.me"

# List the signed-in user's activities
google-api execute plus.activities.list --api=plus -- userId="me" collection="public"

# Start an interactive API session
google-api irb
>> plus = $client.discovered_api('plus')
>> $client.execute(plus.activities.list, {'userId' => 'me', 'collection' => 'public'})
=> # returns a response from the API

For more information, use google-api --help

Samples

See the full list of samples on Github.

Support

Please report bugs at the project on Github. Don't hesitate to ask questions about the client or APIs on StackOverflow.