google-api-client 0.50.0 → 0.53.0

data/docs/logging.md

@@ -1,34 +0,0 @@
-# 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

@@ -1,25 +0,0 @@
-## 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

@@ -1,191 +0,0 @@
-# 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
-```

data/docs/oauth-server.md

@@ -1,133 +0,0 @@
-# Using OAuth 2.0 for Server to Server Applications
-
-The Google APIs Client Library for Ruby supports using OAuth 2.0 for server-to-server interactions such as those between a web application and a Google service. For this scenario you need a service account, which is an account that belongs to your application instead of to an individual end user. Your application calls Google APIs on behalf of the service account, so users aren't directly involved. This scenario is sometimes called "two-legged OAuth," or "2LO." (The related term "three-legged OAuth" refers to scenarios in which your application calls Google APIs on behalf of end users, and in which user consent is sometimes required.)
-
-Typically, an application uses a service account when the application uses Google APIs to work with its own data rather than a user's data. For example, an application that uses [Google Cloud Datastore](https://cloud.google.com/datastore/) for data persistence would use a service account to authenticate its calls to the Google Cloud Datastore API.
-
-If you have a G Suite domain—if you use [G Suite](https://gsuite.google.com/), for example—an administrator of the G Suite domain can authorize an application to access user data on behalf of users in the G Suite domain. For example, an application that uses the [Google Calendar API](https://developers.google.com/calendar/) to add events to the calendars of all users in a G Suite domain would use a service account to access the Google Calendar API on behalf of users. Authorizing a service account to access data on behalf of users in a domain is sometimes referred to as "delegating domain-wide authority" to a service account.
-
-> **Note:** When you use [G Suite Marketplace](https://www.google.com/enterprise/marketplace/) to install an application for your domain, the required permissions are automatically granted to the application. You do not need to manually authorize the service accounts that the application uses.
-
-> **Note:** Although you can use service accounts in applications that run from a Google Apps domain, service accounts are not members of your Google Apps account and aren't subject to domain policies set by Google Apps administrators. For example, a policy set in the Google Apps admin console to restrict the ability of Apps end users to share documents outside of the domain would not apply to service accounts.
-
-This document describes how an application can complete the server-to-server OAuth 2.0 flow by using the Google APIs Client Library for Ruby.
-
-## Overview
-
-To support server-to-server interactions, first create a service account for your project in the API Console. If you want to access user data for users in your Google Apps domain, then delegate domain-wide access to the service account.
-
-Then, your application prepares to make authorized API calls by using the service account's credentials to request an access token from the OAuth 2.0 auth server.
-
-Finally, your application can use the access token to call Google APIs.
-
-## Creating a service account
-
-A service account's credentials include a generated email address that is unique, a client ID, and at least one public/private key pair.
-
-If your application runs on Google App Engine, a service account is set up automatically when you create your project.
-
-If your application runs on Google Compute Engine, a service account is also set up automatically when you create your project, but you must specify the scopes that your application needs access to when you create a Google Compute Engine instance. For more information, see [Preparing an instance to use service accounts](https://cloud.google.com/compute/docs/authentication#using).
-
-If your application doesn't run on Google App Engine or Google Compute Engine, you must obtain these credentials in the Google API Console. To generate service-account credentials, or to view the public credentials that you've already generated, do the following:
-
-1. Open the [**Service accounts** page](https://console.developers.google.com/permissions/serviceaccounts). If prompted, select a project.
-1. Click **Create service account**.
-1. In the **Create service account** window, type a name for the service account, and select **Furnish a new private key**. If you want to [grant G Suite domain-wide authority](https://developers.google.com/identity/protocols/OAuth2ServiceAccount#delegatingauthority) to the service account, also select **Enable G Suite Domain-wide Delegation**. Then click **Create**.
-
-Your new public/private key pair is generated and downloaded to your machine; it serves as the only copy of this key. You are responsible for storing it securely.
-
-You can return to the [API Console](https://console.developers.google.com/) at any time to view the client ID, email address, and public key fingerprints, or to generate additional public/private key pairs. For more details about service account credentials in the API Console, see [Service accounts](https://developers.google.com/console/help/service-accounts) in the API Console help file.
-
-Take note of the service account's email address and store the service account's private key file in a location accessible to your application. Your application needs them to make authorized API calls.
-
-> **Note:** You must store and manage private keys securely in both development and production environments. Google does not keep a copy of your private keys, only your public keys.
-
-## Delegating domain-wide authority to the service account
-
-If your application runs in a Google Apps domain and accesses user data, the service account that you created needs to be granted access to the user data that you want to access.
-
-The following steps must be performed by an administrator of the Google Apps domain:
-
-1. Go to your Google Apps domain’s [Admin console](http://admin.google.com/).
-1. Select **Security** from the list of controls. If you don't see **Security** listed, select **More controls** from the gray bar at the bottom of the page, then select **Security** from the list of controls. If you can't see the controls, make sure you're signed in as an administrator for the domain.
-1. Select **Advanced settings** from the list of options.
-1. Select **Manage third party OAuth Client access** in the **Authentication** section.
-1. In the **Client name** field enter the service account's **Client ID**.
-1. In the **One or More API Scopes** field enter the list of scopes that your application should be granted access to. For example, if your application needs domain-wide access to the Google Drive API and the Google Calendar API, enter: `https://www.googleapis.com/auth/drive`, `https://www.googleapis.com/auth/calendar`.
-1. Click **Authorize**.
-
-Your application now has the authority to make API calls as users in your domain (to "impersonate" users). When you prepare to make authorized API calls, you specify the user to impersonate.
-
-## Preparing to make an authorized API call
-
-After you obtain the client email address and private key from the API Console, complete the following steps:
-
-1. Create a Client object from the service account's credentials and the scopes your application needs access to. For example:
-
-```rb
-require 'googleauth'
-require 'google/apis/compute_v1'
-
-compute = Google::Apis::ComputeV1::ComputeService.new
-
-# Get the environment configured authorization
-scopes =  ['https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/compute']
-compute.authorization = Google::Auth.get_application_default(scopes)
-```
-
-If you have delegated domain-wide access to the service account and you want to impersonate a user account, specify the email address of the user account in the :sub parameter. For example:
-
-```rb
-require 'googleauth'
-require 'google/apis/sqladmin_v1beta4'
-
-# Get the environment configured authorization
-scopes =  ['https://www.googleapis.com/auth/sqlservice.admin']
-authorization = Google::Auth.get_application_default(scopes)
-
-# Clone and set the subject
-auth_client = authorization.dup
-auth_client.sub = 'user@example.org'
-```
-
-2. Use the fetch_access_token! method of the client object to acquire an access token. For example:
-
-`auth_client.fetch_access_token!`
-
-Use the authorized Client object to call Google APIs in your application.
-
-## Calling Google APIs
-
-Use the authorized 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 method of an APIClient object with the name and version of the API. For example, to call version 1beta3 of the Cloud SQL Administration API:
-
-```rb
-sqladmin = Google::Apis::SqladminV1beta4::SqladminService.new
-sqladmin.authorization = auth_client
-
-# Make requests to the API service using the interface
-# provided by the service object, and providing the authorized
-# Client object. For example, to list the instances of Cloud SQL
-# databases in the examinable-example-123 project:
-
-instances = sqladmin.list_instances('examinable-example-123')
-```
-
-## Complete example
-
-The following example prints a JSON-formatted list of Cloud SQL instances in a project.
-
-```rb
-require 'googleauth'
-require 'google/apis/sqladmin_v1beta4'
-
-sqladmin = Google::Apis::SqladminV1beta4::SqladminService.new
-
-# Get the environment configured authorization
-scopes =  ['https://www.googleapis.com/auth/sqlservice.admin']
-sqladmin.authorization = Google::Auth.get_application_default(scopes)
-
-instances = sqladmin.list_instances('examinable-example-123')
-puts instances.to_h
-```