google-api-client 0.50.0 → 0.53.0

data/MIGRATING.md

@@ -1,215 +0,0 @@
-# Migrating from version`0.10` to `0.11`
-
-## Unicode normalization
-
-The client no longer normalizes unicode strings in path parameters. This may affect
-some applications using multibyte strings that were previously normalized.:
-To restore the previous behavior, use the `normalize_unicode` request option.
-
-## Type change for large numbers
-
-Previously, types declared as 64 bit numbers were mapped to strings. These are now mapped to
-`Fixednum`/`Bignum`.
-
-## Timeouts
-
-Timeout options have been moved from `RequestOptions` to `ClientOptions`.
-
-Old                               | New
-----------------------------------|-----------------
-`RequestOptions.open_timeout_sec` | `ClientOptions.open_timeout_sec`
-`RequestOptions.timeout_sec`      | `ClientOptions.read_timeout_sec`
-`RequestOptions.timeout_sec`      | `ClientOptions.send_timeout_sec`
-
-## Batch requests across services no longer supported
-
-It is no longer possible to combine multiple services (e.g. Gail & Drive)
-in a batch request. If batching requests that span services, group
-requests for each service in their own batch request.
-
-# Migrating from version `0.9.x` to `0.10`
-
-Only one minor breaking change was introduced in the `to_json` method due to a version bump for the `representable` gem from `2.3` to `3.0`. If you used the `skip_undefined` in `to_json`, you should replace that with `user_options: { skip_undefined: true }`.
-
-ex:
-```ruby
-foo.to_json(skip_undefined: true)
-```
-to
-```ruby
-foo.to_json(user_options: { skip_undefined: true })
-```
-
-# Migrating from version `0.8.x` to `0.9` or above
-
-Many changes and improvements have been made to the `google-api-ruby-client`
-library to bring it to `0.9`. If you are starting a new project or haven't used
-this library before version `0.9`, see the [README](README.md) to get started
-as you won't need to migrate anything.
-
-Code written against the `0.8.x` version of this library will not work with the `0.9`
-version without modification.
-
-## Discovery
-
-In `0.8.x` the library would "discover" APIs on the fly, introducing
-additional network calls and instability. That has been fixed in `0.9`.
-
-To get the `drive` client in `0.8.x` required this:
-
-```ruby
-require 'google/api_client'
-
-client = Google::APIClient.new
-drive = client.discovered_api('drive', 'v2')
-```
-
-In `0.9` the same thing can be accomplished like this:
-
-```ruby
-require 'google/apis/drive_v2'
-
-drive = Google::Apis::DriveV2::DriveService.new
-```
-
-All APIs are immediately accessible without requiring additional network calls or runtime code generation.
-
-## API Methods
-
-The calling style for API methods has changed. In `0.8.x` all calls were via a generic `execute` method. In `0.9`
-the generated services have fully defined method signatures for all available methods.
-
-To get a file using the Google Drive API in `0.8.x` required this:
-
-```ruby
-file = client.execute(:api_method => drive.file.get, :parameters => { 'id' => 'abc123' })
-```
-
-In `0.9` the same thing can be accomplished like this:
-
-```ruby
-file = drive.get_file('abc123')
-```
-
-Full API definitions including available methods, parameters, and data classes can be found in the `generated` directory.
-
-## Authorization
-
-In the 0.9 version of this library, the authentication and authorization code was moved
-to the new [googleauth](https://github.com/google/google-auth-library-ruby) library. While the new library provides
-significantly simpler APIs for some use cases, not all features have been migrated. Missing features
-are expected to be added by end of Q2 2015.
-
-The underlying [Signet](https://github.com/google/signet) is still used for authorization. OAuth 2 credentials obtained
-previously will continue to work with the `0.9` version. OAuth 1 is no longer supported.
-
-If you were using a PKCS12 file to authorize, we recommend you generate a new key for the service account using the JSON format ( client_secret.json) file with googleauth.
-
-## Media uploads
-
-Media uploads are significantly simpler in `0.9`.
-
-The old `0.8.x` way of uploading media:
-
-```ruby
-media = Google::APIClient::UploadIO.new('mymovie.m4v', 'video/mp4')
-metadata = {
-  'title' => 'My movie',
-  'description' => 'The best home movie ever made'
-}
-client.execute(:api_method => drive.files.insert,
-               :parameters => { 'uploadType' => 'multipart' },
-               :body_object => metadata,
-               :media => media )
-```
-
-The new way in `0.9` using `upload_source` and `content_type` parameters:
-
-```ruby
-metadata = {
-  title: 'My movie',
-  description: 'The best home movie ever made'
-}
-drive.insert_file(metadata, upload_source: 'mymovie.m4v', content_type: 'video/mp4')
-```
-
-`upload_source` can be either a path to a file, an `IO` stream, or a `StringIO` instance.
-
-Uploads are resumable and will be automatically retried if interrupted.
-
-## Media downloads
-
-`0.9` introduces support for media downloads (`alt=media`). To download content, use the `download_dest` parameter:
-
-```ruby
-drive.get_file('abc123', download_dest: '/tmp/myfile.txt')
-```
-
-`download_dest` may be either a path to a file or an `IO` stream.
-
-## Batch Requests
-
-The old `0.8.x` way of performing batch requests:
-
-```ruby
-client = Google::APIClient.new
-urlshortener = client.discovered_api('urlshortener')
-
-batch = Google::APIClient::BatchRequest.new do |result|
-    puts result.data
-end
-
-batch.add(:api_method => urlshortener.url.insert,
-          :body_object => { 'longUrl' => 'http://example.com/foo' })
-batch.add(:api_method => urlshortener.url.insert,
-          :body_object => { 'longUrl' => 'http://example.com/bar' })
-client.execute(batch)
-```
-
-In `0.9`, the equivalent code is:
-
-```ruby
-require 'google/apis/urlshortener_v1'
-
-urlshortener = Google::Apis::UrlshortenerV1::UrlshortenerService.new
-
-urlshortener.batch do |urlshortener|
-  urlshortener.insert_url({long_url: 'http://example.com/foo'}) do |res, err|
-    puts res
-  end
-  urlshortener.insert_url({long_url: 'http://example.com/bar'}) do |res, err|
-    puts res
-  end
-end
-```
-
-Or if sharing the same block:
-
-```ruby
-require 'google/apis/urlshortener_v1'
-
-urlshortener = Google::Apis::UrlshortenerV1::UrlshortenerService.new
-
-callback = lambda { |res, err| puts res }
-urlshortener.batch do |urlshortener|
-  urlshortener.insert_url({long_url: 'http://example.com/foo'}, &callback)
-  urlshortener.insert_url({long_url: 'http://example.com/bar'}, &callback)
-end
-```
-
-## JRuby
-
-Jruby 1.7.4 in 2.0 compatibility mode is supported. To enable for a specific script:
-
-```
-jruby --2.0 myscript.rb
-```
-
-Or set as the default:
-
-```
-export JRUBY_OPTS=--2.0
-```
-
-JRuby 9000 will be supported once released.
-

data/README.md

@@ -1,402 +0,0 @@
-# Google API Client [![Documentation](https://img.shields.io/badge/docs-Google%3A%3AApis-red.svg)](https://googleapis.dev/ruby/google-api-client/latest/Google/Apis.html) [![Gem Version](https://badge.fury.io/rb/google-api-client.svg)](https://badge.fury.io/rb/google-api-client)
-
-These client libraries are officially supported by Google.  However, the libraries are considered complete and are in maintenance mode. This means that we will address critical bugs and security issues but will not add any new features.
-
-## Google Cloud Platform
-
-For Google Cloud Platform APIs such as Datastore, Cloud Storage or Pub/Sub, we recommend using [GoogleCloudPlatform/google-cloud-ruby](https://github.com/GoogleCloudPlatform/google-cloud-ruby) which is under active development.
-
-## Migrating from 0.8.x
-
-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.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')
-```
-
-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:
-
-* 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
-```
-
-### Authorization 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"
-```
-
-## Logging
-
-The client includes a `Logger` instance that can be used to capture debugging information.
-
-When running in a Rails environment, the client will default to using `::Rails.logger`. If you
-prefer to use a separate logger instance for API calls, you can provide a new logger instance:
-
-```ruby
-Google::Apis.logger = Logger.new(STDERR)
-```
-
-Or, you can set the environment variable `GOOGLE_API_USE_RAILS_LOGGER` to any value other than `'true'`; this will send all logging information to STDOUT.
-
-To set the logging level for the client:
-
-```ruby
-Google::Apis.logger.level = Logger::DEBUG
-```
-
-## 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.
-
-Contributions for additional samples are welcome. See [CONTRIBUTING](CONTRIBUTING.md).
-
-## 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>
-
-## TODO
-
-*  ETag support (if-not-modified)
-*  Caching
-*  Model validations
-
-## 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).
-
-## Contributing
-
-See [CONTRIBUTING](.github/CONTRIBUTING.md).
-
-## 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).