Parent

Class/Module Index [+]

Quicksearch

Google::APIClient::Service

Experimental new programming interface at the API level. Hides Google::APIClient. Designed to be easier to use, with less code.

@example

calendar = Google::APIClient::Service.new('calendar', 'v3')
result = calendar.events.list('calendarId' => 'primary').execute()

Constants

DEFAULT_CACHE_FILE

Attributes

cache_store[R]

The cache store used for storing discovery documents.

@return [ActiveSupport::Cache::Store,

Google::APIClient::Service::SimpleFileStore,
nil]
connection[RW]

The Faraday/HTTP connection used by this service.

@return [Faraday::Connection]

Public Class Methods

new(api_name, api_version, options = {}) click to toggle source

Creates a new Service.

@param [String, Symbol] api_name

The name of the API this service will access.

@param [String, Symbol] api_version

The version of the API this service will access.

@param [Hash] options

The configuration parameters for the service.

@option options [Symbol, generate_authenticated_request] :authorization

(:oauth_1)
The authorization mechanism used by the client.  The following
mechanisms are supported out-of-the-box:
<ul>
  <li><code>:two_legged_oauth_1</code></li>
  <li><code>:oauth_1</code></li>
  <li><code>:oauth_2</code></li>
</ul>

@option options [Boolean] :auto_refresh_token (true)

The setting that controls whether or not the api client attempts to
refresh authorization when a 401 is hit in #execute. If the token does
not support it, this option is ignored.

@option options [String] :application_name

The name of the application using the client.

@option options [String] :application_version

The version number of the application using the client.

@option options [String] :host ("www.googleapis.com")

The API hostname used by the client. This rarely needs to be changed.

@option options [String] :port (443)

The port number used by the client. This rarely needs to be changed.

@option options [String] :discovery_path ("/discovery/v1")

The discovery base path. This rarely needs to be changed.

@option options [String] :ca_file

Optional set of root certificates to use when validating SSL connections.
By default, a bundled set of trusted roots will be used.

@option options [generate_authenticated_request] :authorization

The authorization mechanism for requests. Used only if
`:authenticated` is `true`.

@option options [TrueClass, FalseClass] :authenticated (default: true)

`true` if requests must be signed or somehow
authenticated, `false` otherwise.

@option options [TrueClass, FalseClass] :gzip (default: true)

`true` if gzip enabled, `false` otherwise.

@option options [Faraday::Connection] :connection

A custom connection to be used for all requests.

@option options [ActiveSupport::Cache::Store, :default] :discovery_cache

A cache store to place the discovery documents for loaded APIs.
Avoids unnecessary roundtrips to the discovery service.
:default loads the default local file cache store.
# File lib/google/api_client/service.rb, line 91
def initialize(api_name, api_version, options = {})
  @api_name = api_name.to_s
  if api_version.nil?
    raise ArgumentError,
      "API version must be set"
  end
  @api_version = api_version.to_s
  if options && !options.respond_to?(:to_hash)
    raise ArgumentError,
      "expected options Hash, got #{options.class}"
  end

  params = {}
  [:application_name, :application_version, :authorization, :host, :port,
   :discovery_path, :auto_refresh_token, :key, :user_ip,
   :ca_file].each do |option|
    if options.include? option
      params[option] = options[option]
    end
  end

  @client = Google::APIClient.new(params)

  @connection = options[:connection] || @client.connection

  @options = options

  # Initialize cache store. Default to SimpleFileStore if :cache_store
  # is not provided and we have write permissions.
  if options.include? :cache_store
    @cache_store = options[:cache_store]
  else
    cache_exists = File.exists?(DEFAULT_CACHE_FILE)
    if (cache_exists && File.writable?(DEFAULT_CACHE_FILE)) ||
       (!cache_exists && File.writable?(Dir.pwd))
      @cache_store = Google::APIClient::Service::SimpleFileStore.new(
        DEFAULT_CACHE_FILE)
    end
  end

  # Attempt to read API definition from memory cache.
  # Not thread-safe, but the worst that can happen is a cache miss.
  unless @api = @@discovered[[api_name, api_version]]
    # Attempt to read API definition from cache store, if there is one.
    # If there's a miss or no cache store, call discovery service.
    if !@cache_store.nil?
      @api = @cache_store.fetch("%s/%s" % [api_name, api_version]) do
        @client.discovered_api(api_name, api_version)
      end
    else
      @api = @client.discovered_api(api_name, api_version)
    end
    @@discovered[[api_name, api_version]] = @api
  end

  generate_call_stubs(self, @api)
end

Public Instance Methods

@client click to toggle source

Returns the authorization mechanism used by the service.

@return [generate_authenticated_request] The authorization mechanism.

# File lib/google/api_client/service.rb, line 153
def_delegators :@client, :authorization, :authorization=
batch(calls = nil, &block) click to toggle source

Prepares a Google::APIClient::BatchRequest object to make batched calls. @param [Array] calls

Optional array of Google::APIClient::Service::Request to initialize
the batch request with.

@param [Proc] block

Callback for every call's response. Won't be called if a call defined
a callback of its own.

@yield [Google::APIClient::Service::Result]

block to be called when result ready
# File lib/google/api_client/service.rb, line 193
def batch(calls = nil, &block)
  Google::APIClient::Service::BatchRequest.new(self, calls, &block)
end
execute(request) click to toggle source

Executes an API request. Do not call directly; this method is only used by Request objects when executing.

@param [Google::APIClient::Service::Request,

      Google::APIClient::Service::BatchCall] request
The request to be executed.
# File lib/google/api_client/service.rb, line 205
def execute(request)
  if request.instance_of? Google::APIClient::Service::Request
    params = {:api_method => request.method,
      :parameters => request.parameters,
      :connection => @connection}
    if request.respond_to? :body
      if request.body.respond_to? :to_hash
        params[:body_object] = request.body
      else
        params[:body] = request.body
      end
    end
    if request.respond_to? :media
      params[:media] = request.media
    end
    [:authenticated, :gzip].each do |option|
      if @options.include? option
        params[option] = @options[option]
      end
    end
    result = @client.execute(params)
    return Google::APIClient::Service::Result.new(request, result)
  elsif request.instance_of? Google::APIClient::Service::BatchRequest
    @client.execute(request.base_batch, {:connection => @connection})
  end
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.