google-api-client 0.32.1 → 0.40.0

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

data/docs/logging.md

@@ -0,0 +1,34 @@
+# Logging
+
+This page provides logging tips to help you debug your applications.
+
+## Accessing the Logger
+
+Logging is enabled by default in this library using Ruby's standard Logger class.
+
+You can access the library logger with the logger property of Google::Apis.
+
+## Log Level
+You can set the logging level to one of the following:
+
+- FATAL (least amount of logging)
+- ERROR
+- WARN
+- INFO
+- DEBUG (most amount of logging)
+In the following code, the logging level is set to DEBUG and the Google Plus API is called:
+
+```rb
+require 'google/apis/plus_v1'
+
+Google::Apis.logger.level = Logger::DEBUG
+
+plus = Google::Apis::PlusV1::PlusService.new
+activities = plus.list_activities('103354693083460731603', 'public')
+```
+
+The output of this code should include debug info:
+
+```
+D, [2015-06-26T14:33:42.583914 #12144] DEBUG -- : Sending HTTP get https://www.googleapis.com/plus/v1/people/103354693083460731603/activities/public?key=...
+```

data/docs/media-upload.md

@@ -0,0 +1,25 @@
+## Media Upload
+
+For APIs that support file uploads, two additional keyword parameters are available on the method. The parameter upload_source specifies the content to upload while content_type indicates the MIME type. The upload source may be either a file name, IO, or StringIO instance.
+
+For example, to upload a file named 'mymovie.m4v' to Google Drive:
+
+```rb
+require 'google/apis/drive_v2'
+
+drive = Google::Apis::DriveV2:DriveService.new
+drive.authorization = ...
+drive.insert_file({title: 'My Favorite Movie'}, upload_source: 'mymovie.m4v',
+                  content_type: 'video/mp4')
+```
+
+## Resumable media
+
+For large media files, you can use resumable media uploads to send files, which allows files to be uploaded in smaller chunks. This is especially useful if you are transferring large files, and the likelihood of a network interruption or some other transmission failure is high. It can also reduce your bandwidth usage in the event of network failures because you don't have to restart large file uploads from the beginning.
+
+To use resumable uploads, enable retries by setting the retry count to any value greater than 0. The client will automatically resume the upload in the event of an error, up to the configured number of retries.:
+
+```rb
+drive.insert_file(file_metadata, upload_source: 'mymovie.m4v',
+                  content_type: 'video/mp4', options: { retries: 3 } )
+```

data/docs/oauth-installed.md

@@ -0,0 +1,191 @@
+# Using OAuth 2.0 for Installed Applications
+
+The Google APIs Client Library for Ruby supports using OAuth 2.0 in applications that are installed on a device such as a computer, a cell phone, or a tablet. Installed apps are distributed to individual machines, and it is assumed that these apps cannot keep secrets. These apps might access a Google API while the user is present at the app, or when the app is running in the background.
+
+This document is for you if:
+
+- You are writing an installed app for a platform other than Android or iOS, and
+- Your installed app will run on devices that have a system browser and rich input capabilities, such as devices with full keyboards.
+
+If you are writing an app for Android or iOS, use [Google Sign-In](https://developers.google.com/identity) to authenticate your users. The Google Sign-In button manages the OAuth 2.0 flow both for authentication and for obtaining authorization to Google APIs. To add the Google Sign-In button, follow the steps for [Android](https://developers.google.com/identity/sign-in/android) or [iOS](https://developers.google.com/identity/sign-in/ios).
+
+If your app will run on devices that do not have access to a system browser, or devices with limited input capabilities (for example, if your app will run on game consoles, video cameras, or printers), then see [Using OAuth 2.0 for Devices](https://developers.google.com/accounts/docs/OAuth2ForDevices).
+
+## Overview
+
+To use OAuth 2.0 in a locally-installed application, first create application credentials for your project in the API Console.
+
+Then, when your application needs to access a user's data with a Google API, your application sends the user to Google's OAuth 2.0 server. The OAuth 2.0 server authenticates the user and obtains consent from the user for your application to access the user's data.
+
+Next, Google's OAuth 2.0 server sends a single-use authorization code to your application, either in the title bar of the browser or in the query string of an HTTP request to the local host. Your application exchanges this authorization code for an access token.
+
+Finally, your application can use the access token to call Google APIs.
+
+This flow is similar to the one shown in the [Using OAuth 2.0 for Web Server Applications](docs/oauth-server.md), but with three differences:
+
+- When creating a client ID, you specify that your application is an Installed application. This results in a different value for the redirect_uri parameter.
+- The client ID and client secret obtained from the API Console are embedded in the source code of your application. In this context, the client secret is obviously not treated as a secret.
+- The authorization code can be returned to your application in the title bar of the browser or in the query string of an HTTP request to the local host.
+
+## Creating application credentials
+
+All applications that use OAuth 2.0 must have credentials that identify the application to the OAuth 2.0 server. Applications that have these credentials can access the APIs that you enabled for your project.
+
+To obtain application credentials for your project, complete these steps:
+
+1. Open the [Credentials page](https://console.developers.google.com/apis/credentials) in the API Console.
+1. If you haven't done so already, create your OAuth 2.0 credentials by clicking **Create new Client ID** under the **OAuth** heading and selecting the **Installed application** type. Next, look for your application's client ID and client secret in the relevant table.
+
+Download the client_secrets.json file and securely store it in a location that only your application can access.
+
+> **Important:** Do not store the client_secrets.json file in a publicly-accessible location, and if you share the source code to your application—for example, on GitHub—store the client_secrets.json file outside of your source tree to avoid inadvertently sharing your client credentials.
+
+## Configuring the client object
+
+Use the client application credentials that you created to configure a client object in your application. When you configure a client object, you specify the scopes your application needs to access, along with a redirect URI, which will handle the response from the OAuth 2.0 server.
+
+### Choosing a redirect URI
+
+When you create a client ID in the [Google API Console](https://console.developers.google.com/), two redirect_uri parameters are created for you: `urn:ietf:wg:oauth:2.0:oob` and `http://localhost`. The value your application uses determines how the authorization code is returned to your application.
+
+#### http://localhost
+
+This value signals to the Google Authorization Server that the authorization code should be returned as a query string parameter to the web server on the client. You can specify a port number without changing the [Google API Console](https://console.developers.google.com/) configuration. To receive the authorization code using this URI, your application must be listening on the local web server. This is possible on many, but not all, platforms. If your platform supports it, this is the recommended mechanism for obtaining the authorization code.
+
+> **Note:** In some cases, although it is possible to listen, other software (such as a Windows firewall) prevents delivery of the message without significant client configuration.
+
+#### urn:ietf:wg:oauth:2.0:oob
+
+This value signals to the Google Authorization Server that the authorization code should be returned in the title bar of the browser, with the page text prompting the user to copy the code and paste it in the application. This is useful when the client (such as a Windows application) cannot listen on an HTTP port without significant client configuration.
+
+When you use this value, your application can then detect that the page has loaded, and can read the title of the HTML page to obtain the authorization code. It is then up to your application to close the browser window if you want to ensure that the user never sees the page that contains the authorization code. The mechanism for doing this varies from platform to platform.
+
+If your platform doesn't allow you to detect that the page has loaded or read the title of the page, you can have the user paste the code back to your application, as prompted by the text in the confirmation page that the OAuth 2.0 server generates.
+
+#### urn:ietf:wg:oauth:2.0:oob:auto
+
+urn:ietf:wg:oauth:2.0:oob:auto
+This is identical to urn:ietf:wg:oauth:2.0:oob, but the text in the confirmation page that the OAuth 2.0 server generates won't instruct the user to copy the authorization code, but instead will simply ask the user to close the window.
+
+This is useful when your application reads the title of the HTML page (by checking window titles on the desktop, for example) to obtain the authorization code, but can't close the page on its own.
+
+### Creating the object
+
+To create a client object from the client_secrets.json file, use the to_authorization method of a ClientSecrets object. For example, to request read-only access to a user's Google Drive:
+
+```rb
+require 'google/api_client'
+
+client_secrets = Google::APIClient::ClientSecrets.load
+auth_client = client_secrets.to_authorization
+auth_client.update!(
+  :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
+  :redirect_uri => 'urn:ietf:wg:oauth:2.0:oob'
+)
+```
+
+Your application uses the client object to perform OAuth 2.0 operations, such as generating authorization request URIs and applying access tokens to HTTP requests.
+
+## Sending users to Google's OAuth 2.0 server
+
+When your application needs to access a user's data, redirect the user to Google's OAuth 2.0 server.
+
+1. Generate a URL to request access from Google's OAuth 2.0 server:
+
+`auth_uri = auth_client.authorization_uri.to_s`
+
+2. Open auth_uri in a browser:
+
+```rb
+require 'launchy'
+
+Launchy.open(auth_uri)
+```
+
+Google's OAuth 2.0 server will authenticate the user and obtain consent from the user for your application to access the requested scopes. The response will be sent back to your application using the redirect URI specified in the client object.
+
+## Handling the OAuth 2.0 server response
+
+The OAuth 2.0 server responds to your application's access request by using the URI specified in the request.
+
+If the user approves the access request, then the response contains an authorization code. If the user does not approve the request, the response contains an error message. Depending on the redirect URI that you specified, the response is in the query string of an HTTP request to the local host, or in a web page, from which the user can copy and paste the authorization code.
+
+To exchange an authorization code for an access token, use the fetch_access_token! method:
+
+```rb
+auth_client.code = auth_code
+auth_client.fetch_access_token!
+```
+
+## Calling Google APIs
+
+Use the auth_client object to call Google APIs by completing the following steps:
+
+1. Build a service object for the API that you want to call. You build a a service object by calling the discovered_api function with the name and version of the API. For example, to call version 2 of the Drive API:
+
+```rb
+require 'google/apis/drive_v2'
+drive = Google::Apis::DriveV2::DriveService.new
+drive.authorization = auth_client
+```
+
+2. Make requests to the API service using the interface provided by the service object. For example, to list the files in the authenticated user's Google Drive:
+
+```rb
+files = drive.list_files()
+```
+
+## Complete example
+
+The following example prints a JSON-formatted list of files in a user's Google Drive after the user authenticates and gives consent for the application to access the user's Drive files.
+
+```rb
+require 'google/apis/drive_v2'
+require 'google/api_client/client_secrets'
+require 'launchy'
+
+client_secrets = Google::APIClient::ClientSecrets.load
+auth_client = client_secrets.to_authorization
+auth_client.update!(
+  :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
+  :redirect_uri => 'urn:ietf:wg:oauth:2.0:oob'
+)
+
+auth_uri = auth_client.authorization_uri.to_s
+Launchy.open(auth_uri)
+
+puts 'Paste the code from the auth response page:'
+auth_client.code = gets
+auth_client.fetch_access_token!
+
+drive = Google::Apis::DriveV2::DriveService.new
+drive.authorization = auth_client
+files = drive.list_files
+
+files.items.each do |file|
+  puts file.title
+end
+```
+
+If you want to use a local web server to handle the OAuth 2.0 response, you can use the InstalledAppFlow helper to simplify the process. For example:
+
+```rb
+require 'google/apis/drive_v2'
+require 'google/api_client/client_secrets'
+require 'google/api_client/auth/installed_app'
+
+client_secrets = Google::APIClient::ClientSecrets.load
+flow = Google::APIClient::InstalledAppFlow.new(
+  :client_id => client_secrets.client_id,
+  :client_secret => client_secrets.client_secret,
+  :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
+  :port => 5000)
+
+drive = Google::Apis::DriveV2::DriveService.new
+drive.authorization = flow.authorize
+files = drive.list_files
+
+files.items.each do |file|
+  puts file.title
+end
+```