From 7fb35aab06139e208b006c55977cbf607dc58e28 Mon Sep 17 00:00:00 2001 From: Steven Bazyl Date: Thu, 4 Oct 2012 15:48:49 -0700 Subject: [PATCH] Doc improvements --- CHANGELOG.md | 6 +- README.md | 153 ++++++++++++++++++----- lib/google/api_client/batch.rb | 3 +- lib/google/api_client/service_account.rb | 2 + 4 files changed, 131 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b2a09d7d1..14c775097 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,8 @@ # 0.5.0 -* Beta candidate, potential incompatible changes with how requests are processed. All requests - should be made using execute() or execute!() +* Beta candidate, potential incompatible changes with how requests are processed. + * All requests should be made using execute() or execute!() + * :api_method in request can no longer be a string + * Deprecated ResumableUpload.send_* methods. * Reduce memory utilization when uploading large files * Simplify internal request processing. diff --git a/README.md b/README.md index c35e11f91..0ae51b404 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# APIClient +# Google API Client
Homepage
http://code.google.com/p/google-api-ruby-client
@@ -10,39 +10,12 @@ [![Build Status](https://secure.travis-ci.org/google/google-api-ruby-client.png)](http://travis-ci.org/google/google-api-ruby-client) [![Dependency Status](https://gemnasium.com/google/google-api-ruby-client.png)](https://gemnasium.com/google/google-api-ruby-client) -# Description +## Description The Google API Ruby Client makes it trivial to discover and access supported APIs. -# 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.authorization.client_secret = '' - 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 - -# Install +## Install Be sure `http://rubygems.org/` is in your gem sources. @@ -54,3 +27,123 @@ 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.authorization.client_secret = '' + client.authorization.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](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). + +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 + diff --git a/lib/google/api_client/batch.rb b/lib/google/api_client/batch.rb index 0efb17447..464fc976f 100644 --- a/lib/google/api_client/batch.rb +++ b/lib/google/api_client/batch.rb @@ -54,7 +54,7 @@ module Google # @example # # client = Google::APIClient.new - # urlshortener = client.discovered_api('urlshortner') + # urlshortener = client.discovered_api('urlshortener') # batch = Google::APIClient::BatchRequest.new do |result| # puts result.data # end @@ -150,6 +150,7 @@ module Google result = Google::APIClient::Result.new(call, call_response) callback.call(result) if callback end + Google::APIClient::Result.new(self, response) end ## diff --git a/lib/google/api_client/service_account.rb b/lib/google/api_client/service_account.rb index 3f1a69fe2..54737add3 100644 --- a/lib/google/api_client/service_account.rb +++ b/lib/google/api_client/service_account.rb @@ -64,6 +64,8 @@ module Google # key) # client.authorization = service_account.authorize # client.execute(...) + # + # @see https://developers.google.com/accounts/docs/OAuth2ServiceAccount class JWTAsserter # @return [String] ID/email of the issuing party attr_accessor :issuer