class Google::Apis::Core::BaseService
Base service for all APIs. Not to be used directly.
Attributes
Additional path prefix for all API methods @return [Addressable::URI]
Alternate path prefix for all batch methods @return [Addressable::URI]
HTTP client @return [Hurley::Client]
General settings @return [Google::Apis::ClientOptions]
Default options for all requests @return [Google::Apis::RequestOptions]
Root URL (host/port) for the API @return [Addressable::URI]
Alternate path prefix for media uploads @return [Addressable::URI]
Public Class Methods
@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
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
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
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
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
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 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
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
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
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
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
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
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
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