google-api-ruby-client/lib/google/apis/core/base_service.rb

442 lines
16 KiB
Ruby

# Copyright 2015 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
require 'addressable/uri'
require 'addressable/template'
require 'google/apis/version'
require 'google/apis/core/api_command'
require 'google/apis/core/batch'
require 'google/apis/core/upload'
require 'google/apis/core/download'
require 'google/apis/options'
require 'googleauth'
require 'httpclient'
module Google
module Apis
module Core
# Helper class for enumerating over a result set requiring multiple fetches
class PagedResults
include Enumerable
attr_reader :last_result
# @param [BaseService] service
# Current service instance
# @param [Fixnum] max
# Maximum number of items to iterate over. Nil if no limit
# @param [Boolean] cache
# True (default) if results should be cached so multiple iterations can be used.
# @param [Symbol] items
# Name of the field in the result containing the items. Defaults to :items
def initialize(service, max: nil, items: :items, cache: true, response_page_token: :next_page_token, &block)
@service = service
@block = block
@max = max
@items_field = items
@response_page_token_field = response_page_token
if cache
@result_cache = Hash.new do |h, k|
h[k] = @block.call(k, @service)
end
@fetch_proc = Proc.new { |token| @result_cache[token] }
else
@fetch_proc = Proc.new { |token| @block.call(token, @service) }
end
end
# Iterates over result set, fetching additional pages as needed
def each
page_token = nil
item_count = 0
loop do
@last_result = @fetch_proc.call(page_token)
items = @last_result.send(@items_field)
if items.kind_of?(Array)
for item in items
item_count = item_count + 1
break if @max && item_count > @max
yield item
end
elsif items.kind_of?(Hash)
items.each do |key, val|
item_count = item_count + 1
break if @max && item_count > @max
yield key, val
end
elsif items
# yield singular non-nil items (for genomics API)
yield items
end
break if @max && item_count >= @max
next_page_token = @last_result.send(@response_page_token_field)
break if next_page_token.nil? || next_page_token == page_token
page_token = next_page_token
end
end
end
# Base service for all APIs. Not to be used directly.
#
class BaseService
include Logging
# Root URL (host/port) for the API
# @return [Addressable::URI]
attr_accessor :root_url
# Additional path prefix for all API methods
# @return [Addressable::URI]
attr_accessor :base_path
# Alternate path prefix for media uploads
# @return [Addressable::URI]
attr_accessor :upload_path
# Alternate path prefix for all batch methods
# @return [Addressable::URI]
attr_accessor :batch_path
# HTTP client
# @return [HTTPClient]
attr_accessor :client
# General settings
# @return [Google::Apis::ClientOptions]
attr_accessor :client_options
# Default options for all requests
# @return [Google::Apis::RequestOptions]
attr_accessor :request_options
# @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
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
# @!attribute [rw] authorization
# @return [Signet::OAuth2::Client]
# OAuth2 credentials
def authorization=(authorization)
request_options.authorization = authorization
end
def authorization
request_options.authorization
end
# TODO: with(options) method
# 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]
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
start_batch(batch_command)
yield self
ensure
end_batch
end
batch_command.execute(client)
end
# 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]
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
start_batch(batch_command)
yield self
ensure
end_batch
end
batch_command.execute(client)
end
# Get the current HTTP client
# @return [HTTPClient]
def client
@client ||= new_client
end
# 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
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
# 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
# @yieldparam [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| ... }
def fetch_all(max: nil, items: :items, cache: true, response_page_token: :next_page_token, &block)
fail "fetch_all may not be used inside a batch" if batch?
return PagedResults.new(self, max: max, items: items, cache: cache, response_page_token: response_page_token, &block)
end
protected
# 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]
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
# 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]
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
# 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]
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
# 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
def execute_or_queue_command(command, &callback)
batch_command = current_batch
if batch_command
fail "Can not combine services in a batch" if Thread.current[:google_api_batch_service] != self
batch_command.add(command, &callback)
nil
else
command.execute(client, &callback)
end
end
# Update commands with service-specific options. To be implemented by subclasses
# @param [Google::Apis::Core::HttpCommand] _command
def apply_command_defaults(_command)
end
private
# Get the current batch context
#
# @return [Google:Apis::Core::BatchRequest]
def current_batch
Thread.current[:google_api_batch]
end
# Check if a batch is in progress
# @return [Boolean]
def batch?
!current_batch.nil?
end
# Start a new thread-local batch context
# @param [Google::Apis::Core::BatchCommand] cmd
def start_batch(cmd)
fail "Batch already in progress" if batch?
Thread.current[:google_api_batch] = cmd
Thread.current[:google_api_batch_service] = self
end
# Clear thread-local batch context
def end_batch
Thread.current[:google_api_batch] = nil
Thread.current[:google_api_batch_service] = nil
end
# Create a new HTTP client
# @return [HTTPClient]
def new_client
client = ::HTTPClient.new
if client_options.transparent_gzip_decompression
client.transparent_gzip_decompression = client_options.transparent_gzip_decompression
end
client.proxy = client_options.proxy_url if client_options.proxy_url
if client_options.open_timeout_sec
client.connect_timeout = client_options.open_timeout_sec
end
if client_options.read_timeout_sec
client.receive_timeout = client_options.read_timeout_sec
end
if client_options.send_timeout_sec
client.send_timeout = client_options.send_timeout_sec
end
client.follow_redirect_count = 5
client.default_header = { 'User-Agent' => user_agent }
client.debug_dev = logger if client_options.log_http_requests
client
end
# Build the user agent header
# @return [String]
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
end
end
end
end