class Google::Apis::Core::BaseService

Base service for all APIs. Not to be used directly.

Attributes

base_path[RW]

Additional path prefix for all API methods @return [Addressable::URI]

batch_path[RW]

Alternate path prefix for all batch methods @return [Addressable::URI]

client[RW]

HTTP client @return [Hurley::Client]

client_options[RW]

General settings @return [Google::Apis::ClientOptions]

request_options[RW]

Default options for all requests @return [Google::Apis::RequestOptions]

root_url[RW]

Root URL (host/port) for the API @return [Addressable::URI]

upload_path[RW]

Alternate path prefix for media uploads @return [Addressable::URI]

Public Class Methods

new(root_url, base_path) click to toggle source

@param [String,Addressable::URI] #root_url

Root URL for the API

@param [String,Addressable::URI] #base_path

Additional path prefix for all API methods

@api private

# File lib/google/apis/core/base_service.rb, line 114
def initialize(root_url, base_path)
  self.root_url = root_url
  self.base_path = base_path
  self.upload_path = "upload/#{base_path}"
  self.batch_path = 'batch'
  self.client_options = Google::Apis::ClientOptions.default.dup
  self.request_options = Google::Apis::RequestOptions.default.dup
end

Public Instance Methods

authorization() click to toggle source
# File lib/google/apis/core/base_service.rb, line 130
def authorization
  request_options.authorization
end
authorization=(authorization) click to toggle source

@!attribute [rw] authorization @return [Signet::OAuth2::Client]

OAuth2 credentials
# File lib/google/apis/core/base_service.rb, line 126
def authorization=(authorization)
  request_options.authorization = authorization
end
batch(options = nil) { |self| ... } click to toggle source

Perform a batch request. Calls made within the block are sent in a single network request to the server.

@example

service.batch do |s|
  s.get_item(id1) do |res, err|
    # process response for 1st call
  end
  # ...
  s.get_item(idN) do |res, err|
    # process response for Nth call
  end
end

@param [Hash, Google::Apis::RequestOptions] options

Request-specific options

@yield [self] @return [void]

# File lib/google/apis/core/base_service.rb, line 154
def batch(options = nil)
  batch_command = BatchCommand.new(:post, Addressable::URI.parse(root_url + batch_path))
  batch_command.options = request_options.merge(options)
  apply_command_defaults(batch_command)
  begin
    Thread.current[:google_api_batch] = batch_command
    yield self
  ensure
    Thread.current[:google_api_batch] = nil
  end
  batch_command.execute(client)
end
batch_upload(options = nil) { |self| ... } click to toggle source

Perform a batch upload request. Calls made within the block are sent in a single network request to the server. Batch uploads are useful for uploading multiple small files. For larger files, use single requests which use a resumable upload protocol.

@example

service.batch do |s|
  s.insert_item(upload_source: 'file1.txt') do |res, err|
    # process response for 1st call
  end
  # ...
  s.insert_item(upload_source: 'fileN.txt') do |res, err|
    # process response for Nth call
  end
end

@param [Hash, Google::Apis::RequestOptions] options

Request-specific options

@yield [self] @return [void]

# File lib/google/apis/core/base_service.rb, line 186
def batch_upload(options = nil)
  batch_command = BatchUploadCommand.new(:put, Addressable::URI.parse(root_url + upload_path))
  batch_command.options = request_options.merge(options)
  apply_command_defaults(batch_command)
  begin
    Thread.current[:google_api_batch] = batch_command
    yield self
  ensure
    Thread.current[:google_api_batch] = nil
  end
  batch_command.execute(client)
end
fetch_all(max: nil, items: :items, cache: true, &block) click to toggle source

Executes a given query with paging, automatically retrieving additional pages as necessary. Requires a block that returns the result set of a page. The current page token is supplied as an argument to the block.

Note: The returned enumerable also contains a `last_result` field containing the full result of the last query executed.

@param [Fixnum] max

Maximum number of items to iterate over. Defaults to nil -- no upper bound.

@param [Symbol] items

Name of the field in the result containing the items. Defaults to :items

@param [Boolean] cache

True (default) if results should be cached so multiple iterations can be used.

@return [Enumerble] @yield [token, service]

Current page token & service instance

@yieldparam [String] token

Current page token to be used in the query

@yieldparm [service]

Current service instance

@since 0.9.4

@example Retrieve all files,

file_list = service.fetch_all { |token, s| s.list_files(page_token: token) }
file_list.each { |f| ... }
# File lib/google/apis/core/base_service.rb, line 267
def fetch_all(max: nil, items: :items, cache: true,  &block)
  fail "fetch_all may not be used inside a batch" if batch?
  return PagedResults.new(self, max: max, items: items, cache: cache, &block)
end
http(method, url, params: nil, body: nil, download_dest: nil, options: nil, &block) click to toggle source

Simple escape hatch for making API requests directly to a given URL. This is not intended to be used as a generic HTTP client and should be used only in cases where no service method exists (e.g. fetching an export link for a Google Drive file.)

@param [Symbol] method

HTTP method as symbol (e.g. :get, :post, :put, ...)

@param [String] url

URL to call

@param [Hash<String,String>] params

Optional hash of query parameters

@param [#read] body

Optional body for POST/PUT

@param [IO, String] download_dest

IO stream or filename to receive content download

@param [Google::Apis::RequestOptions] options

Request-specific options

@yield [result, err] Result & error if block supplied @yieldparam result [String] HTTP response body @yieldparam err [StandardError] error object if request failed

@return [String] HTTP response body

# File lib/google/apis/core/base_service.rb, line 229
def http(method, url, params: nil, body: nil, download_dest: nil, options: nil, &block)
  if download_dest
    command = DownloadCommand.new(method, url, body: body)
  else
    command = HttpCommand.new(method, url, body: body)
  end
  command.options = request_options.merge(options)
  apply_command_defaults(command)
  command.query.merge(Hash(params))
  execute_or_queue_command(command, &block)
end

Protected Instance Methods

apply_command_defaults(_command) click to toggle source

Update commands with service-specific options. To be implemented by subclasses @param [Google::Apis::Core::HttpCommand] _command

# File lib/google/apis/core/base_service.rb, line 351
def apply_command_defaults(_command)
end
execute_or_queue_command(command, &callback) click to toggle source

Execute the request. If a batch is in progress, the request is added to the batch instead.

@param [Google::Apis::Core::HttpCommand] command

Command to execute

@return [Object] response object if command executed and no callback supplied @yield [result, err] Result & error if block supplied @raise [Google::Apis::ServerError] An error occurred on the server and the request can be retried @raise [Google::Apis::ClientError] The request is invalid and should not be retried without modification @raise [Google::Apis::AuthorizationError] Authorization is required

# File lib/google/apis/core/base_service.rb, line 339
def execute_or_queue_command(command, &callback)
  batch_command = current_batch
  if batch_command
    batch_command.add(command, &callback)
    nil
  else
    command.execute(client, &callback)
  end
end
make_download_command(method, path, options) click to toggle source

Create a new download command.

@param [symbol] method

HTTP method for uploading (typically :get)

@param [String] path

Additional path to download endpoint, appended to API base path

@param [Hash, Google::Apis::RequestOptions] options

Request-specific options

@return [Google::Apis::Core::DownloadCommand]

# File lib/google/apis/core/base_service.rb, line 304
def make_download_command(method, path, options)
  template = Addressable::Template.new(root_url + base_path + path)
  command = DownloadCommand.new(method, template)
  command.options = request_options.merge(options)
  command.query['alt'] = 'media'
  apply_command_defaults(command)
  command
end
make_simple_command(method, path, options) click to toggle source

Create a new command.

@param [symbol] method

HTTP method (:get, :post, :delete, etc...)

@param [String] path

Additional path, appended to API base path

@param [Hash, Google::Apis::RequestOptions] options

Request-specific options

@return [Google::Apis::Core::DownloadCommand]

# File lib/google/apis/core/base_service.rb, line 322
def make_simple_command(method, path, options)
  template = Addressable::Template.new(root_url + base_path + path)
  command = ApiCommand.new(method, template)
  command.options = request_options.merge(options)
  apply_command_defaults(command)
  command
end
make_upload_command(method, path, options) click to toggle source

Create a new upload command.

@param [symbol] method

HTTP method for uploading (typically :put or :post)

@param [String] path

Additional path to upload endpoint, appended to API base path

@param [Hash, Google::Apis::RequestOptions] options

Request-specific options

@return [Google::Apis::Core::UploadCommand]

# File lib/google/apis/core/base_service.rb, line 283
def make_upload_command(method, path, options)
  template = Addressable::Template.new(root_url + upload_path + path)
  if batch?
    command = MultipartUploadCommand.new(method, template)
  else
    command = ResumableUploadCommand.new(method, template)
  end
  command.options = request_options.merge(options)
  apply_command_defaults(command)
  command
end

Private Instance Methods

batch?() click to toggle source

Check if a batch is in progress @return [Boolean]

# File lib/google/apis/core/base_service.rb, line 365
def batch?
  !current_batch.nil?
end
current_batch() click to toggle source

Get the current batch context

@return [Google:Apis::Core::BatchRequest]

# File lib/google/apis/core/base_service.rb, line 359
def current_batch
  Thread.current[:google_api_batch]
end
new_client() click to toggle source

Create a new HTTP client @return [Hurley::Client]

# File lib/google/apis/core/base_service.rb, line 371
def new_client
  client = Hurley::Client.new
  client.connection = Google::Apis::Core::HttpClientAdapter.new unless client_options.use_net_http
  client.request_options.timeout = request_options.timeout_sec
  client.request_options.open_timeout = request_options.open_timeout_sec
  client.request_options.proxy = client_options.proxy_url
  client.request_options.query_class = Hurley::Query::Flat
  client.ssl_options.ca_file = File.join(Google::Apis::ROOT, 'lib', 'cacerts.pem')
  client.header[:user_agent] = user_agent
  client
end
user_agent() click to toggle source

Build the user agent header @return [String]

# File lib/google/apis/core/base_service.rb, line 385
def user_agent
  sprintf('%s/%s google-api-ruby-client/%s %s (gzip)',
          client_options.application_name,
          client_options.application_version,
          Google::Apis::VERSION,
          Google::Apis::OS_VERSION)
end