google-api-client 0.34.1 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f5c6f57b6e73f8ff32192717e8bfc29c428aa183bc1d46752432491df33aa72
-  data.tar.gz: 68a8b34179552ed160b0f9841671c9cae1a4eb1815ff11252b2195297a542785
+  metadata.gz: fcc784d3215a12ce376ba8c9915d579ad935a7c673ae86837f967fa2424d0647
+  data.tar.gz: 449e4a3c5c79905f96b9d0fcf7912089291f6e307c2849e8148dc9d2efc4883f
 SHA512:
-  metadata.gz: 2e4a8df1d22c47dfdedb69ea883a668653c40218a4c07b290f451f7b1284cdfc005ec833240ef76568e1f5f37ca8f390acb506b2c3fed1aefb2aafb8ae74918e
-  data.tar.gz: 95b19f198084c1fdcbf13a845bb4416c67bbedf983cee7b1bfd539aab0edaac9165fa1125194bd01ce5ec9c5e07980ca520f31defdd29642b6c193c99680bd7c
+  metadata.gz: fc08d3a30a1336ab5b2aa685a3e56794c65d914c4a74dbbf0e6dbbc105e61818a10931cb069018676fd1c9fcc854b28d52f1ac4e804d577042823902b3bc011c
+  data.tar.gz: a3f08c15420319a04a9e82f601012d6f393958f83015c885253c7df306a26ab3bef97ca964b61e38b84ef0df94d70a11d517c71b24988a69cf8ba9ae1c65c1b7

data/.yardopts

@@ -3,10 +3,23 @@
 --verbose
 --markup-provider=redcarpet
 --markup=markdown
+--main OVERVIEW.md
+
 lib/**/*.rb
-generated/**/*.rb
 -
-README.md
+OVERVIEW.md
+docs/getting-started.md
+docs/installation.md
+docs/auth.md
+docs/api-keys.md
+docs/oauth.md
+docs/oauth-web.md
+docs/oauth-installed.md
+docs/oauth-server.md
+docs/client-secrets.md
+docs/logging.md
+docs/media-upload.md
+docs/pagination.md
+docs/performance.md
 MIGRATING.md
-CONTRIBUTING.md
 LICENSE

data/CHANGELOG.md

@@ -1,3 +1,115 @@
+# 0.35.0
+* Breaking changes:
+  * Deleted `storage_v1beta1`
+* Backwards compatible changes:
+  * Added `datacatalog_v1beta1`
+  * Added `dfareporting_v3_4`
+  * Added `doubleclickbidmanager_v1_1`
+  * Updated `adexchangebuyer2_v2beta1`
+  * Updated `adexchangebuyer_v1_3`
+  * Updated `adexchangebuyer_v1_4`
+  * Updated `androidmanagement_v1`
+  * Updated `androidpublisher_v3`
+  * Updated `appengine_v1`
+  * Updated `appengine_v1beta`
+  * Updated `appsmarket_v2`
+  * Updated `bigquery_v2`
+  * Updated `bigqueryconnection_v1beta1`
+  * Updated `bigquerydatatransfer_v1`
+  * Updated `bigqueryreservation_v1`
+  * Updated `bigqueryreservation_v1alpha2`
+  * Updated `bigqueryreservation_v1beta1`
+  * Updated `bigtableadmin_v1`
+  * Updated `bigtableadmin_v2`
+  * Updated `binaryauthorization_v1`
+  * Updated `binaryauthorization_v1beta1`
+  * Updated `books_v1`
+  * Updated `calendar_v3`
+  * Updated `civicinfo_v2`
+  * Updated `cloudasset_v1`
+  * Updated `cloudasset_v1beta1`
+  * Updated `cloudbilling_v1`
+  * Updated `cloudbuild_v1`
+  * Updated `cloudbuild_v1alpha1`
+  * Updated `cloudfunctions_v1`
+  * Updated `cloudiot_v1`
+  * Updated `cloudkms_v1`
+  * Updated `cloudprivatecatalogproducer_v1beta1`
+  * Updated `cloudresourcemanager_v1`
+  * Updated `cloudresourcemanager_v1beta1`
+  * Updated `cloudresourcemanager_v2`
+  * Updated `cloudresourcemanager_v2beta1`
+  * Updated `cloudscheduler_v1`
+  * Updated `cloudscheduler_v1beta1`
+  * Updated `cloudsearch_v1`
+  * Updated `cloudtasks_v2`
+  * Updated `cloudtasks_v2beta2`
+  * Updated `cloudtasks_v2beta3`
+  * Updated `commentanalyzer_v1alpha1`
+  * Updated `compute_alpha`
+  * Updated `compute_beta`
+  * Updated `compute_v1`
+  * Updated `containeranalysis_v1alpha1`
+  * Updated `containeranalysis_v1beta1`
+  * Updated `content_v2`
+  * Updated `content_v2_1`
+  * Updated `dataproc_v1`
+  * Updated `dataproc_v1beta2`
+  * Updated `dfareporting_v3_3`
+  * Updated `dialogflow_v2`
+  * Updated `dialogflow_v2beta1`
+  * Updated `dlp_v2`
+  * Updated `dns_v1beta2`
+  * Updated `docs_v1`
+  * Updated `doubleclickbidmanager_v1`
+  * Updated `drive_v3`
+  * Updated `fcm_v1`
+  * Updated `firebase_v1beta1`
+  * Updated `firebasehosting_v1beta1`
+  * Updated `firebaserules_v1`
+  * Updated `genomics_v2alpha1`
+  * Updated `healthcare_v1beta1`
+  * Updated `homegraph_v1`
+  * Updated `iam_v1`
+  * Updated `logging_v2`
+  * Updated `ml_v1`
+  * Updated `monitoring_v3`
+  * Updated `pagespeedonline_v5`
+  * Updated `policytroubleshooter_v1beta`
+  * Updated `pubsub_v1`
+  * Updated `pubsub_v1beta2`
+  * Updated `recommender_v1beta1`
+  * Updated `remotebuildexecution_v1`
+  * Updated `remotebuildexecution_v1alpha`
+  * Updated `remotebuildexecution_v2`
+  * Updated `run_v1`
+  * Updated `run_v1alpha1`
+  * Updated `runtimeconfig_v1beta1`
+  * Updated `securitycenter_v1`
+  * Updated `securitycenter_v1beta1`
+  * Updated `servicebroker_v1`
+  * Updated `servicebroker_v1alpha1`
+  * Updated `servicebroker_v1beta1`
+  * Updated `serviceconsumermanagement_v1`
+  * Updated `servicecontrol_v1`
+  * Updated `servicemanagement_v1`
+  * Updated `servicenetworking_v1`
+  * Updated `servicenetworking_v1beta`
+  * Updated `serviceusage_v1`
+  * Updated `serviceusage_v1beta1`
+  * Updated `sheets_v4`
+  * Updated `spanner_v1`
+  * Updated `speech_v1`
+  * Updated `speech_v1p1beta1`
+  * Updated `sql_v1beta4`
+  * Updated `storagetransfer_v1`
+  * Updated `videointelligence_v1`
+  * Updated `videointelligence_v1beta2`
+  * Updated `videointelligence_v1p1beta1`
+  * Updated `videointelligence_v1p2beta1`
+  * Updated `videointelligence_v1p3beta1`
+  * Updated `youtube_partner_v1`
+
 # 0.34.1
 * Backwards compatible changes:
   * Updated `bigquery_v2`
@@ -174,6 +286,8 @@
   * Updated `serviceusage_v1`
   * Updated `serviceusage_v1beta1`
   * Updated `sheets_v4`
+* Other changes:
+  * Dropped support for Ruby versions older than 2.4
 
 # 0.32.1
 * Backwards compatible changes:

data/OVERVIEW.md

@@ -0,0 +1,36 @@
+# Google API Client Library for Ruby Docs
+
+The Google API Client Library for Ruby is designed for Ruby
+client-application developers. It offers simple, flexible
+access to many Google APIs.
+
+## Features
+
+- Call Google APIs simply
+- Handle Auth with fewer lines of code
+- Use standard tooling for installation
+
+## Documentation
+
+Learn how to use the Google API Client Library for Ruby with these guides:
+
+### Usage Guides
+
+- {file:docs/getting-started.md Getting Started}
+- {file:docs/installation.md Installation}
+- {file:docs/auth.md Auth}
+  - {file:docs/api-keys.md API Keys}
+  - {file:docs/oauth.md OAuth 2.0}
+  - {file:docs/oauth-web.md OAuth 2.0 for Web Server Applications}
+  - {file:docs/oauth-installed.md OAuth 2.0 for Installed Applications}
+  - {file:docs/oauth-server.md OAuth 2.0 for Server to Server Applications}
+  - {file:docs/client-secrets.md Client Secrets}
+- How to...
+  - {file:docs/logging.md Use Logging}
+  - {file:docs/media-upload.md Upload Media}
+  - {file:docs/pagination.md Use Pagination}
+  - {file:docs/performance.md Improve Performance}
+
+### Reference Documentation
+
+- Reference documentation for [google-api-client](https://googleapis.dev/ruby/google-api-client/latest/index.html).

data/README.md

@@ -10,12 +10,37 @@ For Google Cloud Platform APIs such as Datastore, Cloud Storage or Pub/Sub, we r
 
 See [MIGRATING](MIGRATING.md) for additional details on how to migrate to the latest version.
 
+## Documentation
+
+Learn how to use the Google API Client Library for Ruby with these guides:
+
+### Usage Guides
+
+- [Getting Started](docs/getting-started.md)
+- [Installation](docs/installation.md)
+- [Auth](docs/auth.md)
+  - [API Keys](docs/api-keys.md)
+  - [OAuth 2.0](docs/oauth.md)
+  - [OAuth 2.0 for Web Server Applications](docs/oauth-web.md)
+  - [OAuth 2.0 for Installed Applications](docs/oauth-installed.md)
+  - [OAuth 2.0 for Server to Server Applications](docs/oauth-server.md)
+  - [Client Secrets](docs/client-secrets.md)
+- How to...
+  - [Use Logging](docs/logging.md)
+  - [Upload Media](docs/media-upload.md)
+  - [Use Pagination](docs/pagination.md)
+  - [Improve Performance](docs/performance.md)
+
+### Reference Documentation
+
+- Reference documentation for [google-api-client](https://googleapis.dev/ruby/google-api-client/latest/index.html).
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'google-api-client', '~> 0.11'
+gem 'google-api-client', '~> 0.34'
 
 ```
 
@@ -53,6 +78,29 @@ metadata = drive.insert_file(metadata, upload_source: 'test.txt', content_type:
 # Download a file
 drive.get_file(metadata.id, download_dest: '/tmp/myfile.txt')
 ```
+
+An example to use the Content API (Google Merchant Center)
+
+```ruby
+require 'google/apis/content_v2'
+require 'googleauth' # https://github.com/googleapis/google-auth-library-ruby
+
+Content = Google::Apis::ContentV2 # Alias the module
+content = Content::ShoppingContentService.new
+
+scope = 'https://www.googleapis.com/auth/content'
+merchant_id = # Merchant ID found on dashboard
+
+content.authorization = Google::Auth::ServiceAccountCredentials.make_creds(
+  json_key_io: File.open('./content-api-key.json'),
+  scope: scope)
+
+content.authorization.fetch_access_token!
+# Service methods: https://googleapis.dev/ruby/google-api-client/latest/Google/Apis/ContentV2/ShoppingContentService.html
+content.list_datafeeds(merchant_id) # Returns Google::Apis::ContentV2::ListDatafeedsResponse
+
+```
+
 ### Naming conventions vs JSON representation
 
 Object properties in the ruby client use the standard ruby convention for naming -- snake_case. This differs from the underlying JSON representation which typically uses camelCase for properties. There are a few notable exceptions to this rule:

data/Rakefile

@@ -71,7 +71,7 @@ namespace :kokoro do
   end
 
   task :post do
-    require_relative "rakelib/link_checker.rb"
+    require_relative "rakelib/devsite/link_checker.rb"
 
     link_checker = LinkChecker.new
     link_checker.run

data/docs/api-keys.md

@@ -0,0 +1,20 @@
+# API Keys
+
+When calling APIs that do not access private user data, you can use simple API keys. These keys are used to authenticate your application for accounting purposes. The Google Developers Console documentation also describes [API keys](https://developers.google.com/console/help/using-keys).
+
+> Note: If you do need to access private user data, you must use OAuth 2.0. See [Using OAuth 2.0 for Installed Applications](oauth-installed.md), [Using OAuth 2.0 for Server to Server Applications](oauth-server.md), and [Using OAuth 2.0 for Web Server Applications](oauth-web.md) for more information.
+
+## Using API Keys
+
+To use API keys, set the `key` attribute on service objects. For example:
+
+```ruby
+require 'google/apis/translate_v2'
+
+translate = Google::Apis::TranslateV2::TranslateService.new
+translate.key = 'YOUR_API_KEY_HERE'
+result = translate.list_translations('Hello world!', 'es', source: 'en')
+puts result.translations.first.translated_text
+```
+
+All calls made using that service object will include your API key.

data/docs/auth.md

@@ -0,0 +1,53 @@
+# Authentication Overview
+
+This document is an overview of how authentication, authorization, and accounting are accomplished. For all API calls, your application needs to be authenticated. When an API accesses a user's private data, your application must also be authorized by the user to access the data. For example, accessing a public Google+ post would not require user authorization, but accessing a user's private calendar would. Also, for quota and billing purposes, all API calls involve accounting. This document summarizes the protocols used by Google APIs and provides links to more information.
+
+## Access types
+
+It is important to understand the basics of how API authentication and authorization are handled. All API calls must use either simple or authorized access (defined below). Many API methods require authorized access, but some can use either. Some API methods that can use either behave differently, depending on whether you use simple or authorized access. See the API's method documentation to determine the appropriate access type.
+
+### 1. Simple API access (API keys)
+
+These API calls do not access any private user data. Your application must authenticate itself as an application belonging to your Google API Console project. This is needed to measure project usage for accounting purposes.
+
+**API key:** To authenticate your application, use an [API key](api-keys.md) for your API Console project. Every simple access call your application makes must include this key.
+
+> **Warning:** Keep your API key private. If someone obtains your key, they could use it to consume your quota or incur charges against your API Console project.
+
+### 2. Authorized API access (OAuth 2.0)
+
+These API calls access private user data. Before you can call them, the user that has access to the private data must grant your application access. Therefore, your application must be authenticated, the user must grant access for your application, and the user must be authenticated in order to grant that access. All of this is accomplished with OAuth 2.0 and libraries written for it.
+
+**Scope:** Each API defines one or more scopes that declare a set of operations permitted. For example, an API might have read-only and read-write scopes. When your application requests access to user data, the request must include one or more scopes. The user needs to approve the scope of access your application is requesting.
+
+**Refresh and access tokens:** When a user grants your application access, the OAuth 2.0 authorization server provides your application with refresh and access tokens. These tokens are only valid for the scope requested. Your application uses access tokens to authorize API calls. Access tokens expire, but refresh tokens do not. Your application can use a refresh token to acquire a new access token.
+
+> **Warning:** Keep refresh and access tokens private. If someone obtains your tokens, they could use them to access private user data.
+
+**Client ID and client secret:** These strings uniquely identify your application and are used to acquire tokens. They are created for your project on the [API Console](https://console.developers.google.com/). There are three types of client IDs, so be sure to get the correct type for your application:
+
+- [Web application](https://developers.google.com/accounts/docs/OAuth2WebServer) client IDs
+- [Installed application](https://developers.google.com/accounts/docs/OAuth2InstalledApp) client IDs
+- [Service Account](https://developers.google.com/accounts/docs/OAuth2ServiceAccount) client IDs
+
+> **Warning:** Keep your client secret private. If someone obtains your client secret, they could use it to consume your quota, incur charges against your Console project, and request access to user data.
+
+## Using API keys
+
+More information and examples for API keys are provided on the [API Keys](api-keys.md) page.
+
+## Using OAuth 2.0
+
+More information and examples for OAuth 2.0 are provided on the [OAuth 2.0](oauth.md) page.
+
+## Using environment variables
+
+The [GoogleAuth Library for Ruby](https://github.com/google/google-auth-library-ruby) also supports authorization via
+environment variables if you do not want to check in developer credentials
+or private keys. Simply set the following variables for your application:
+
+```sh
+GOOGLE_ACCOUNT_TYPE="YOUR ACCOUNT TYPE" # ie. 'service'
+GOOGLE_CLIENT_EMAIL="YOUR GOOGLE DEVELOPER EMAIL"
+GOOGLE_PRIVATE_KEY="YOUR GOOGLE DEVELOPER API KEY"
+```

data/docs/client-secrets.md

@@ -0,0 +1,69 @@
+# Client Secrets
+
+The Google APIs Client Library for Ruby uses the `client_secrets.json` file format for storing the `client_id`, `client_secret`, and other OAuth 2.0 parameters.
+
+See [Creating authorization credentials](https://developers.google.com/identity/protocols/OAuth2WebServer#creatingcred) for how to obtain a `client_secrets.json` file.
+
+The `client_secrets.json` file format is a [JSON](http://www.json.org/) formatted file containing the client ID, client secret, and other OAuth 2.0 parameters. Here is an example client_secrets.json file for a web application:
+
+```json
+{
+  "web": {
+    "client_id": "asdfjasdljfasdkjf",
+    "client_secret": "1912308409123890",
+    "redirect_uris": ["https://www.example.com/oauth2callback"],
+    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+    "token_uri": "https://accounts.google.com/o/oauth2/token"
+  }
+}
+```
+
+Here is an example client_secrets.json file for an installed application:
+
+```json
+{
+  "installed": {
+    "client_id": "837647042410-75ifg...usercontent.com",
+    "client_secret":"asdlkfjaskd",
+    "redirect_uris": ["http://localhost", "urn:ietf:wg:oauth:2.0:oob"],
+    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+    "token_uri": "https://accounts.google.com/o/oauth2/token"
+  }
+}
+```
+
+The format defines one of two client ID types:
+
+- `web`: Web application.
+- `installed`: Installed application.
+
+The `web` and `installed` sub-objects have the following mandatory members:
+
+- `client_id` (string): The client ID.
+- `client_secret` (string): The client secret.
+- `redirect_uris` (list of strings): A list of valid redirection endpoint URIs. This list should match the list entered for the client ID on the [API Access pane](https://code.google.com/apis/console#:access) of the Google APIs Console.
+- `auth_uri` (string): The authorization server endpoint URI.
+- `token_uri` (string): The token server endpoint URI.
+
+All of the above members are mandatory. The following optional parameters may appear:
+
+- `client_email` (string) The service account email associated with the client.
+- `auth_provider_x509_cert_url` (string) The URL of the public x509 certificate, used to verify the signature on JWTs, such as ID tokens, signed by the authentication provider.
+- `client_x509_cert_url` (string) The URL of the public x509 certificate, used to verify JWTs signed by the client.
+
+The following shows how you can use a client_secrets.json file and the Google::APIClient::ClientSecrets class to create a new authorization object:
+
+```rb
+require 'google/api_client/client_secrets'
+
+CLIENT_SECRETS = Google::APIClient::ClientSecrets.load
+authorization = CLIENT_SECRETS.to_authorization
+
+# You can then use this with an API client, e.g.:
+client.authorization = authorization
+```
+
+## Motivation
+
+Traditionally providers of OAuth endpoints have relied upon cut-and-paste as the way users of their service move the client id and secret from a registration page into working code. That can be error prone, along with it being an incomplete picture of all the information that is needed to get OAuth 2.0 working, which requires knowing all the endpoints and configuring a Redirect Endpoint. If service providers start providing a downloadable client_secrets.json file for client information and client libraries start consuming client_secrets.json then a large amount of friction in implementing OAuth 2.0 can be reduced.
+

data/docs/getting-started.md

@@ -0,0 +1,340 @@
+# Getting Started
+
+This document provides all the basic information you need to start using the library. It covers important library concepts, shows examples for various use cases, and gives links to more information.
+
+## Setup
+
+There are a few setup steps you need to complete before you can use this library:
+
+1.  If you don't already have a Google account, [sign up](https://www.google.com/accounts).
+2.  If you have never created a Google APIs Console project, read the [Managing Projects page](http://developers.google.com/console/help/managing-projects) and create a project in the [Google API Console](https://console.developers.google.com/).
+
+## Authentication and authorization
+
+It is important to understand the basics of how API authentication and authorization are handled. All API calls must use either simple or authorized access (defined below). Many API methods require authorized access, but some can use either. Some API methods that can use either behave differently, depending on whether you use simple or authorized access. See the API's method documentation to determine the appropriate access type.
+
+### 1. Simple API access (API keys)
+
+These API calls do not access any private user data. Your application must authenticate itself as an application belonging to your Google Cloud project. This is needed to measure project usage for accounting purposes.
+
+**API key**: To authenticate your application, use an [API key](https://cloud.google.com/docs/authentication/api-keys) for your Google Cloud Console project. Every simple access call your application makes must include this key.
+    
+> **Warning**: Keep your API key private. If someone obtains your key, they could use it to consume your quota or incur charges against your Google Cloud project.
+    
+### 2. Authorized API access (OAuth 2.0)
+
+These API calls access private user data. Before you can call them, the user that has access to the private data must grant your application access. Therefore, your application must be authenticated, the user must grant access for your application, and the user must be authenticated in order to grant that access. All of this is accomplished with [OAuth 2.0](https://developers.google.com/identity/protocols/OAuth2) and libraries written for it.
+
+*   **Scope**: Each API defines one or more scopes that declare a set of operations permitted. For example, an API might have read-only and read-write scopes. When your application requests access to user data, the request must include one or more scopes. The user needs to approve the scope of access your application is requesting.
+*   **Refresh and access tokens**: When a user grants your application access, the OAuth 2.0 authorization server provides your application with refresh and access tokens. These tokens are only valid for the scope requested. Your application uses access tokens to authorize API calls. Access tokens expire, but refresh tokens do not. Your application can use a refresh token to acquire a new access token.
+    
+    > **Warning**: Keep refresh and access tokens private. If someone obtains your tokens, they could use them to access private user data.
+    
+*   **Client ID and client secret**: These strings uniquely identify your application and are used to acquire tokens. They are created for your Google Cloud project on the [API Access pane](https://console.developers.google.com/apis/credentials) of the Google Cloud. There are several types of client IDs, so be sure to get the correct type for your application:
+    
+    *   Web application client IDs
+    *   Installed application client IDs
+    *   [Service Account](https://developers.google.com/identity/protocols/OAuth2ServiceAccount) client IDs
+    
+    > **Warning**: Keep your client secret private. If someone obtains your client secret, they could use it to consume your quota, incur charges against your Google Cloud project, and request access to user data.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'google-api-client', '~> 0.34'
+
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install google-api-client
+
+## Usage
+
+### Basic usage
+
+To use an API, include the corresponding generated file and instantiate the service. For example to use the Drive API:
+
+```ruby
+require 'google/apis/drive_v2'
+
+Drive = Google::Apis::DriveV2 # Alias the module
+drive = Drive::DriveService.new
+drive.authorization = ... # See Googleauth or Signet libraries
+
+# Search for files in Drive (first page only)
+files = drive.list_files(q: "title contains 'finances'")
+files.items.each do |file|
+  puts file.title
+end
+
+# Upload a file
+metadata = Drive::File.new(title: 'My document')
+metadata = drive.insert_file(metadata, upload_source: 'test.txt', content_type: 'text/plain')
+
+# Download a file
+drive.get_file(metadata.id, download_dest: '/tmp/myfile.txt')
+```
+### Naming conventions vs JSON representation
+
+Object properties in the ruby client use the standard ruby convention for naming -- snake_case. This differs from the underlying JSON representation which typically uses camelCase for properties. There are a few notable exceptions to this rule:
+
+* For properties that are defined as hashes with user-defined keys, no translation is performed on the key.
+* For embedded field masks in requests (for example, the Sheets API), specify the camelCase form when referencing fields.
+
+Outside those exceptions, if a property is specified using camelCase in a request, it will be ignored during serialization and omitted from the request.
+
+### Media
+
+Methods that allow media operations have additional parameters to specify the upload source or download destination.
+
+For uploads, the `upload_source` parameter can be specified with either a path to a file, an `IO` stream, or `StringIO`
+instance.
+
+For downloads, the `download_dest` parameter can also be either a path to a file, an `IO` stream, or `StringIO` instance.
+
+Both uploads & downloads are resumable. If an error occurs during transmission the request will be automatically
+retried from the last received byte.
+
+### Errors & Retries
+
+Retries are disabled by default, but enabling retries is strongly encouraged. The number of retries can be configured
+via `Google::Apis::RequestOptions`. Any number greater than 0 will enable retries.
+
+To enable retries for all services:
+
+```ruby
+Google::Apis::RequestOptions.default.retries = 5
+```
+
+With retries enabled globally, retries can be disabled for specific calls by including a retry value of 0 in the
+request options:
+
+```ruby
+drive.insert_file(metadata, upload_source: 'test.txt', content_type: 'text/plain', options: { retries: 0 })
+```
+
+When retries are enabled, if a server or rate limit error occurs during a request it is automatically retried with
+an exponentially increasing delay on subsequent retries. If a request can not be retried or if the maximum number
+of retries is exceeded, an exception is thrown.
+
+### Callbacks
+
+A block can be specified when making calls. If present, the block will be called with the result or error, rather than
+returning the result from the call or raising the error. Example:
+
+```ruby
+# Search for files in Drive (first page only)
+drive.list_files(q: "title contains 'finances'") do |res, err|
+  if err
+    # Handle error
+  else
+    # Handle response
+  end
+end
+```
+
+This calling style is required when making batch requests as responses are not available until the entire batch
+is complete.
+
+### Paging
+
+To fetch multiple pages of data, use the `fetch_all` method to wrap the paged query. This returns an
+`Enumerable` that automatically fetches additional pages as needed.
+
+```ruby
+# List all calendar events
+now = Time.now.iso8601
+items = calendar.fetch_all do |token|
+  calendar.list_events('primary',
+                        single_events: true,
+                        order_by: 'startTime',
+                        time_min: now,
+                        page_token: token)
+end
+items.each { |event| puts event.summary }
+```
+
+For APIs that use a field other than `items` to contain the results, an alternate field name can be supplied.
+
+```ruby
+# List all files in Drive
+items = drive.fetch_all(items: :files) { |token| drive.list_files(page_token: token) }
+items.each { |file| puts file.name }
+```
+
+### Batches
+
+Multiple requests can be batched together into a single HTTP request to reduce overhead. Batched calls are executed
+in parallel and the responses processed once all results are available
+
+
+```ruby
+# Fetch a bunch of files by ID
+ids = ['file_id_1', 'file_id_2', 'file_id_3', 'file_id_4']
+drive.batch do |drive|
+  ids.each do |id|
+    drive.get_file(id) do |res, err|
+      # Handle response
+    end
+  end
+end
+```
+
+Media operations -- uploads & downloads -- can not be included in batch with other requests.
+
+However, some APIs support batch uploads. To upload multiple files in a batch, use the `batch_upload` method instead.
+Batch uploads should only be used when uploading multiple small files. For large files, upload files individually to
+take advantage of the libraries built-in resumable upload support.
+
+### Hashes
+
+While the API will always return instances of schema classes, plain hashes are accepted in method calls for
+convenience. Hash keys must be symbols matching the attribute names on the corresponding object the hash is meant
+to replace. For example:
+
+```ruby
+file = {id: '123', title: 'My document', labels: { starred: true }}
+file = drive.create_file(file, {}) # Returns a Drive::File instance
+```
+
+is equivalent to:
+
+```ruby
+file = Drive::File.new(id: '123', title: 'My document')
+file.labels = Drive::File::Labels.new(starred: true)
+file = drive.update_file(file) # Returns a Drive::File instance
+```
+
+IMPORTANT: Be careful when supplying hashes for request objects. If it is the last argument to a method, ruby will interpret the hash as keyword arguments. To prevent this, appending an empty hash as an extra parameter will avoid misinterpretation.
+
+```ruby
+file = {id: '123', title: 'My document', labels: { starred: true }}
+file = drive.create_file(file) # Raises ArgumentError: unknown keywords: id, title, labels
+file = drive.create_file(file, {}) # Returns a Drive::File instance
+```
+
+### Using raw JSON
+
+To handle JSON serialization or deserialization in the application, set `skip_serialization` or
+or `skip_deserializaton` options respectively. When setting `skip_serialization` in a request,
+the body object must be a string representing the serialized JSON.
+
+When setting `skip_deserialization` to true, the response from the API will likewise
+be a string containing the raw JSON from the server.
+
+## Authorization
+
+[OAuth 2](https://developers.google.com/accounts/docs/OAuth2) is used to authorize applications. This library uses
+both [Signet](https://github.com/google/signet) and
+[Google Auth Library for Ruby](https://github.com/google/google-auth-library-ruby) for OAuth 2 support.
+
+The [Google Auth Library for Ruby](https://github.com/google/google-auth-library-ruby) provides an implementation of
+[application default credentials] for Ruby. It offers a simple way to get authorization credentials for use in
+calling Google APIs, best suited for cases when the call needs to have the same identity
+and authorization level for the application independent of the user. This is
+the recommended approach to authorize calls to Cloud APIs, particularly when
+you're building an application that uses Google Compute Engine.
+
+For per-user authorization, use [Signet](https://github.com/google/signet) to obtain user authorization.
+
+### Passing authorization to requests
+
+Authorization can be specified for the entire client, for an individual service instance, or on a per-request basis.
+
+Set authorization for all service:
+
+```ruby
+Google::Apis::RequestOptions.default.authorization = authorization
+# Services instantiated after this will inherit the authorization
+```
+
+On a per-service level:
+
+```ruby
+drive = Google::Apis::DriveV2::DriveService.new
+drive.authorization = authorization
+
+# All requests made with this service will use the same authorization
+```
+
+Per-request:
+
+```ruby
+drive.get_file('123', options: { authorization: authorization })
+```
+
+### Authorization using API keys
+
+Some APIs allow using an API key instead of OAuth2 tokens. For these APIs, set
+the `key` attribute of the service instance. For example:
+
+```ruby
+require 'google/apis/translate_v2'
+
+translate = Google::Apis::TranslateV2::TranslateService.new
+translate.key = 'YOUR_API_KEY_HERE'
+result = translate.list_translations('Hello world!', 'es', source: 'en')
+puts result.translations.first.translated_text
+```
+
+## Customizing endpoints
+
+By default, client objects will connect to the default Google endpoints for =
+their respective APIs. If you need to connect to a regional endpoint, a test
+endpoint, or other custom endpoint, modify the `root_url` attribute of the
+client object. For example:
+
+```ruby
+require "google/apis/docs_v1"
+docs_service = Google::Apis::DocsV1::DocsService.new
+
+docs_service.root_url = "https://my-custom-docs-endpoint.example.com/"
+
+document = docs_service.get_document("my-document-id")
+```
+
+## Samples
+
+See the [samples](https://github.com/google/google-api-ruby-client/tree/master/samples) for examples on how to use the client library for various
+services.
+
+## Generating APIs
+
+For [Cloud Endpoints](https://cloud.google.com/endpoints/) or other APIs not included in the gem, ruby code can be
+generated from the discovery document.
+
+To generate from a local discovery file:
+
+    $ generate-api gen <outdir> --file=<path>
+
+A URL can also be specified:
+
+    $ generate-api gen <outdir> --url=<url>
+
+## Supported Ruby Versions
+
+This library is currently supported on Ruby 1.9+.
+However, Ruby 2.4 or later is strongly recommended, as earlier releases have
+reached or are nearing end-of-life. After March 31, 2019, Google will provide
+official support only for Ruby versions that are considered current and
+supported by Ruby Core (that is, Ruby versions that are either in normal
+maintenance or in security maintenance).
+See https://www.ruby-lang.org/en/downloads/branches/ for further details.
+
+## License
+
+This library is licensed under Apache 2.0. Full license text is
+available in [LICENSE](LICENSE).
+
+## Support
+
+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).