google-api-ruby-client/README.md

228 lines
6.9 KiB
Markdown
Raw Normal View History

2012-10-04 22:48:49 +00:00
# Google API Client
## Alpha
This library is in Alpha. We will make an effort to support the library, but we reserve the right to make incompatible
changes when necessary.
2012-05-11 10:16:38 +00:00
## Migrating from 0.8.x
Version 0.9 is not compatible with previous versions. See [MIGRATING](MIGRATING.md) for additional details on how to
migrate to the latest version.
## Installation
Add this line to your application's Gemfile:
2014-10-03 20:37:40 +00:00
```ruby
gem 'google-api-client', '0.9.pre1'
```
2014-10-03 20:37:40 +00:00
And then execute:
2012-10-04 22:48:49 +00:00
$ bundle
2012-10-04 22:48:49 +00:00
Or install it yourself as:
2012-10-04 22:48:49 +00:00
$ gem install google-api-client
2012-10-04 22:48:49 +00:00
## Usage
### Basic usage
To use an API, include the corresponding generated file and instantiate the service. For example to use the Drive API:
2013-04-29 02:29:39 +00:00
```ruby
require 'google/apis/drive_v2'
Drive = Google::Apis::DriveV2 # Alias the module
drive = Drive::DriveService.new
drive.authorization = 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')
2013-04-29 02:29:39 +00:00
```
2012-10-04 22:48:49 +00:00
### 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.
2012-10-04 22:48:49 +00:00
### Errors & Retries
2012-10-04 22:48:49 +00:00
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:
2012-10-04 22:48:49 +00:00
2013-04-29 02:29:39 +00:00
```ruby
Google::Apis::RequestOptions.default.retries = 5
2013-04-29 02:29:39 +00:00
```
2012-10-04 22:48:49 +00:00
With retries enabled globally, retries can be disabled for specific calls by including a retry value of 0 in the
request options:
2012-10-04 22:48:49 +00:00
2013-04-29 02:29:39 +00:00
```ruby
drive.insert_file(metadata, upload_source: 'test.txt', content_type: 'text/plain', options: { retries: 0 })
2013-04-29 02:29:39 +00:00
```
2012-10-04 22:48:49 +00:00
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.
2012-10-04 22:48:49 +00:00
### Callbacks
A block an 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
2013-04-29 02:29:39 +00:00
```
2012-10-04 22:48:49 +00:00
This calling style is required when making batch requests as responses are not available until the entire batch
is complete.
2012-10-04 22:48:49 +00:00
### Batches
2012-10-04 22:48:49 +00:00
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
2013-06-16 12:15:06 +00:00
2013-01-05 00:13:03 +00:00
```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 reusmable 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.insert_file(file) # Returns a Drive::File instance
```
is equivalent to:
2013-04-29 02:29:39 +00:00
```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
2013-06-16 12:15:06 +00:00
```
## Authorization
2013-09-10 22:31:24 +00:00
[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.
2014-01-22 23:40:06 +00:00
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.
2014-01-22 23:40:06 +00:00
For per-user authorization, use [Signet](https://github.com/google/signet) to obtain user authorization.
2013-09-10 22:31:24 +00:00
### 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:
2013-04-29 02:29:39 +00:00
```ruby
Google::Apis::RequestOptions.default.authorization = authorization
# Services instantiated after this will inherit the authorization
```
2013-06-16 12:15:06 +00:00
On a per-service level:
```ruby
drive = Google::Apis::DriveV2::DriveService.new
drive.authorization = authorization
2013-06-16 12:15:06 +00:00
# All requests made with this service will use the same authorization
2013-04-29 02:29:39 +00:00
```
2013-06-16 12:15:06 +00:00
Per-request:
2012-10-04 22:48:49 +00:00
2013-04-29 02:29:39 +00:00
```ruby
drive.get_file('123', options: { authorization: authorization })
2013-04-29 02:29:39 +00:00
```
2012-10-04 22:48:49 +00:00
## Generating APIs
2012-10-04 22:48:49 +00:00
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.
2012-10-04 22:48:49 +00:00
To generate from a local discovery file:
2013-06-16 12:15:06 +00:00
$ generate-api gen <outdir> --file=<path>
2012-10-04 22:48:49 +00:00
A URL can also be specified:
2012-10-25 23:21:00 +00:00
$ generate-api gen <outdir> --url=<url>
2012-10-25 23:21:00 +00:00
## TODO
2012-10-25 23:21:00 +00:00
* ETag support (if-not-modified)
* Auto-paging results (maybe)
* Caching
* Model validations
2012-10-26 00:02:59 +00:00
## License
This library is licensed under Apache 2.0. Full license text is
available in [LICENSE.txt](LICENSE.txt).
## Contributing
2012-10-26 00:02:59 +00:00
See [CONTRIBUTING](contributing).
## 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).