4 <dt>Homepage</dt><dd><a href="http://www.github.com/google/google-api-ruby-client">http://www.github.com/google/google-api-ruby-client</a></dd>
5 <dt>Authors</dt><dd>Bob Aman, <a href="mailto:sbazyl@google.com">Steven Bazyl</a></dd>
6 <dt>Copyright</dt><dd>Copyright © 2011 Google, Inc.</dd>
7 <dt>License</dt><dd>Apache 2.0</dd>
10 [![Build Status](https://secure.travis-ci.org/google/google-api-ruby-client.png)](http://travis-ci.org/google/google-api-ruby-client)
11 [![Dependency Status](https://gemnasium.com/google/google-api-ruby-client.png)](https://gemnasium.com/google/google-api-ruby-client)
15 The Google API Ruby Client makes it trivial to discover and access supported
20 This library is in Alpha. We will make an effort to support the library, but we reserve the right to make incompatible changes when necessary.
24 Be sure `https://rubygems.org/` is in your gem sources.
26 For normal client usage, this is sufficient:
29 $ gem install google-api-client
35 require 'google/api_client'
36 require 'google/api_client/client_secrets'
37 require 'google/api_client/auth/installed_app'
39 # Initialize the client.
40 client = Google::APIClient.new(
41 :application_name => 'Example Ruby application',
42 :application_version => '1.0.0'
45 # Initialize Google+ API. Note this will make a request to the
46 # discovery service every time, so be sure to use serialization
47 # in your production code. Check the samples for more details.
48 plus = client.discovered_api('plus')
50 # Load client secrets from your client_secrets.json.
51 client_secrets = Google::APIClient::ClientSecrets.load
53 # Run installed application flow. Check the samples for a more
54 # complete example that saves the credentials between runs.
55 flow = Google::APIClient::InstalledAppFlow.new(
56 :client_id => client_secrets.client_id,
57 :client_secret => client_secrets.client_secret,
58 :scope => ['https://www.googleapis.com/auth/plus.me']
60 client.authorization = flow.authorize
63 result = client.execute(
64 :api_method => plus.activities.list,
65 :parameters => {'collection' => 'public', 'userId' => 'me'}
75 To take full advantage of the client, load API definitions prior to use. To load an API:
78 urlshortener = client.discovered_api('urlshortener')
81 Specific versions of the API can be loaded as well:
84 drive = client.discovered_api('drive', 'v2')
87 Locally cached discovery documents may be used as well. To load an API from a local file:
90 # Output discovery document to JSON
91 File.open('my-api.json', 'w') do |f| f.puts MultiJson.dump(client.discovery_document('myapi', 'v1')) end
93 # Read discovery document and load API
94 doc = File.read('my-api.json')
95 client.register_discovery_document('myapi', 'v1', doc)
96 my_api = client.discovered_api('myapi', 'v1')
101 Most interactions with Google APIs require users to authorize applications via OAuth 2.0. The client library uses [Signet](https://github.com/google/signet) to handle most aspects of authorization. For additional details about Google's OAuth support, see [Google Developers](https://developers.google.com/accounts/docs/OAuth2).
103 Credentials can be managed at the connection level, as shown, or supplied on a per-request basis when calling `execute`.
105 For server-to-server interactions, like those between a web application and Google Cloud Storage, Prediction, or BigQuery APIs, use service accounts.
108 key = Google::APIClient::KeyUtils.load_from_pkcs12('client.p12', 'notasecret')
109 client.authorization = Signet::OAuth2::Client.new(
110 :token_credential_uri => 'https://accounts.google.com/o/oauth2/token',
111 :audience => 'https://accounts.google.com/o/oauth2/token',
112 :scope => 'https://www.googleapis.com/auth/prediction',
113 :issuer => '123456-abcdef@developer.gserviceaccount.com',
115 client.authorization.fetch_access_token!
119 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
120 in the credentials. Detailed instructions on how to enable delegation for your domain can be found at [developers.google.com](https://developers.google.com/drive/delegation).
122 ### Automatic Retries & Backoff
124 The API client can automatically retry requests for recoverable errors. To enable retries, set the `client.retries` property to
125 the number of additional attempts. To avoid flooding servers, retries invovle a 1 second delay that increases on each subsequent retry.
126 In the case of authentication token expiry, the API client will attempt to refresh the token and retry the failed operation - this
127 is a specific exception to the retry rules.
129 The default value for retries is 0, but will be enabled by default in future releases.
131 ### Batching Requests
133 Some Google APIs support batching requests into a single HTTP request. Use `Google::APIClient::BatchRequest`
134 to bundle multiple requests together.
139 client = Google::APIClient.new
140 urlshortener = client.discovered_api('urlshortner')
142 batch = Google::APIClient::BatchRequest.new do |result|
146 batch.add(:api_method => urlshortener.url.insert,
147 :body_object => { 'longUrl' => 'http://example.com/foo' })
148 batch.add(:api_method => urlshortener.url.insert,
149 :body_object => { 'longUrl' => 'http://example.com/bar' })
150 client.execute(batch)
153 Blocks for handling responses can be specified either at the batch level or when adding an individual API call. For example:
156 batch.add(:api_method=>urlshortener.url.insert, :body_object => { 'longUrl' => 'http://example.com/bar' }) do |result|
163 For APIs that support file uploads, use `Google::APIClient::UploadIO` to load the stream. Both multipart and resumable
164 uploads can be used. For example, to upload a file to Google Drive using multipart
167 drive = client.discovered_api('drive', 'v2')
169 media = Google::APIClient::UploadIO.new('mymovie.m4v', 'video/mp4')
171 'title' => 'My movie',
172 'description' => 'The best home movie ever made'
174 client.execute(:api_method => drive.files.insert,
175 :parameters => { 'uploadType' => 'multipart' },
176 :body_object => metadata,
180 To use resumable uploads, change the `uploadType` parameter to `resumable`. To check the status of the upload
181 and continue if necessary, check `result.resumable_upload`.
184 client.execute(:api_method => drive.files.insert,
185 :parameters => { 'uploadType' => 'resumable' },
186 :body_object => metadata,
188 upload = result.resumable_upload
192 client.execute(upload)
198 See the full list of [samples on Github](https://github.com/google/google-api-ruby-client-samples).
203 Please [report bugs at the project on Github](https://github.com/google/google-api-ruby-client/issues). Don't hesitate to [ask questions](http://stackoverflow.com/questions/tagged/google-api-ruby-client) about the client or APIs on [StackOverflow](http://stackoverflow.com).