X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/ed0a8921c0f6a6afa478fc77de9202fac3405683..b02bfe3028a72ef625c24b66bf90952cb7830afa:/README.md diff --git a/README.md b/README.md index 226a5f563c..f396949535 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ APIs. ## Install -Be sure `http://rubygems.org/` is in your gem sources. +Be sure `https://rubygems.org/` is in your gem sources. For normal client usage, this is sufficient: @@ -28,26 +28,34 @@ $ gem install google-api-client ## Example Usage ```ruby -# Initialize the client & Google+ API require 'google/api_client' -client = Google::APIClient.new -plus = client.discovered_api('plus') +require 'google/api_client/client_secrets' +require 'google/api_client/auth/installed_app' -# 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' +# Initialize the client. +client = Google::APIClient.new( + :application_name => 'Example Ruby application', + :application_version => '1.0.0' +) -# Request authorization -redirect_uri = client.authorization.authorization_uri +# 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') -# Wait for authorization code then exchange for token -client.authorization.code = '....' -client.authorization.fetch_access_token! +# 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 +# Make an API call. result = client.execute( :api_method => plus.activities.list, :parameters => {'collection' => 'public', 'userId' => 'me'} @@ -81,10 +89,10 @@ 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). +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. ```ruby @@ -97,8 +105,18 @@ client.authorization = Signet::OAuth2::Client.new( :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](https://developers.google.com/drive/delegation). + +### Automatic Retries & Backoff + +The API client can automatically retry requests for recoverable errors. To enable retries, set the `client.retries` property to +the number of additional attempts. To avoid flooding servers, retries invovle a 1 second delay that increases on each subsequent retry. + +The default value for retries is 0, but will be enabled by default in future releases. + ### Batching Requests Some Google APIs support batching requests into a single HTTP request. Use `Google::APIClient::BatchRequest` @@ -109,18 +127,18 @@ Example: ```ruby 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, + +batch.add(:api_method => urlshortener.url.insert, :body_object => { 'longUrl' => 'http://example.com/foo' }) -batch.add(:api_method => urlshortener.url.insert, +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: ```ruby @@ -136,7 +154,7 @@ uploads can be used. For example, to upload a file to Google Drive using multipa ```ruby drive = client.discovered_api('drive', 'v2') - + media = Google::APIClient::UploadIO.new('mymovie.m4v', 'video/mp4') metadata = { 'title' => 'My movie', @@ -147,7 +165,7 @@ client.execute(:api_method => drive.files.insert, :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`. @@ -164,31 +182,11 @@ if upload.resumable? end ``` -## Command Line - -Included with the gem is a command line interface for working with Google APIs. - -```bash -# 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 Google Code](http://code.google.com/p/google-api-ruby-client/source/browse?repo=samples). +See the full list of [samples on Github](https://github.com/google/google-api-ruby-client-samples). ## Support -Please [report bugs at the project on Google Code](http://code.google.com/p/google-api-ruby-client/issues/entry). 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). +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).