Class: Google::APIClient::Service

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
StubGenerator
Defined in:
lib/google/api_client/service.rb,
lib/google/api_client/service/batch.rb,
lib/google/api_client/service/result.rb,
lib/google/api_client/service/request.rb,
lib/google/api_client/service/resource.rb,
lib/google/api_client/service/stub_generator.rb,
lib/google/api_client/service/simple_file_store.rb

Overview

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

Examples:

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

Defined Under Namespace

Modules: StubGenerator Classes: BatchRequest, BatchedCallResult, Request, Resource, Result, SimpleFileStore

Constant Summary collapse

DEFAULT_CACHE_FILE = 
'discovery.cache'
@@discovered =

Cache for discovered APIs.

{}

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from StubGenerator

#generate_call_stubs

Constructor Details

#initialize(api_name, api_version, options = {}) ⇒ Service

Creates a new Service.

Parameters:

  • api_name (String, Symbol) —

    The name of the API this service will access.

  • api_version (String, Symbol) —

    The version of the API this service will access.

  • options (Hash) (defaults to: {}) —

    The configuration parameters for the service.

Options Hash (options):

  • :authorization (Symbol, #generate_authenticated_request) — default: :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>

  • :auto_refresh_token (Boolean) — default: 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.

  • :application_name (String) —

    The name of the application using the client.

  • :application_version (String) —

    The version number of the application using the client.

  • :host (String) — default: "www.googleapis.com" —

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

  • :port (String) — default: 443 —

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

  • :discovery_path (String) — default: "/discovery/v1" —

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

  • :ca_file (String) —

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

  • :authorization (#generate_authenticated_request) —

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

  • :authenticated (TrueClass, FalseClass) — default: default: true —

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

  • :gzip (TrueClass, FalseClass) — default: default: true —

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

  • :connection (Faraday::Connection) —

    A custom connection to be used for all requests.

  • :discovery_cache (ActiveSupport::Cache::Store, :default) —

    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.



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# 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

Instance Attribute Details

#cache_store ⇒ ActiveSupport::Cache::Store, ... (readonly)

The cache store used for storing discovery documents.

Returns:



180
181
182
 
# File 'lib/google/api_client/service.rb', line 180

def cache_store
  @cache_store
end

#connection ⇒ Faraday::Connection

The Faraday/HTTP connection used by this service.

Returns:

  • (Faraday::Connection) 


172
173
174
 
# File 'lib/google/api_client/service.rb', line 172

def connection
  @connection
end

Instance Method Details

#batch(calls = nil, &block) {|Google::APIClient::Service::Result| ... } ⇒ Object

Prepares a Google::APIClient::BatchRequest object to make batched calls.

Parameters:

  • calls (Array) (defaults to: nil) —

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

  • block (Proc) —

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

Yields:



193
194
195
 
# 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) ⇒ Object

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

The request to be executed.

Parameters:



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# 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