class Google::APIClient::BatchRequest

Wraps multiple API calls into a single over-the-wire HTTP request.

@example

client = Google::APIClient.new
urlshortener = client.discovered_api('urlshortener')
batch = Google::APIClient::BatchRequest.new do |result|
   puts result.data
end

batch.add(:api_method => urlshortener.url.insert, :body_object => { 'longUrl' => 'http://example.com/foo' })
batch.add(:api_method => urlshortener.url.insert, :body_object => { 'longUrl' => 'http://example.com/bar' })

client.execute(batch)

Constants

BATCH_BOUNDARY

Attributes

calls[R]

@api private @return [Array<(String,Google::APIClient::Request,Proc)] List of API calls in the batch

Public Class Methods

new(options = {}, &block) click to toggle source

Creates a new batch request.

@param [Hash] options

Set of options for this request.

@param [Proc] block

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

@return [Google::APIClient::BatchRequest]

The constructed object.

@yield [Google::APIClient::Result]

block to be called when result ready
# File lib/google/api_client/batch.rb, line 88
def initialize(options = {}, &block)
  @calls = []
  @global_callback = block if block_given?
  @last_auto_id = 0
  
  # TODO(sgomes): Use SecureRandom.uuid, drop UUIDTools when we drop 1.8
  @base_id = UUIDTools::UUID.random_create.to_s

  options[:uri] ||= 'https://www.googleapis.com/batch'
  options[:http_method] ||= 'POST'

  super options
end

Public Instance Methods

add(call, call_id = nil, &block) click to toggle source

Add a new call to the batch request. Each call must have its own call ID; if not provided, one will automatically be generated, avoiding collisions. If duplicate call IDs are provided, an error will be thrown.

@param [Hash, Google::APIClient::Request] call

the call to be added.

@param [String] call_id

the ID to be used for this call. Must be unique

@param [Proc] block

callback for this call's response.

@return [Google::APIClient::BatchRequest]

the BatchRequest, for chaining

@yield [Google::APIClient::Result]

block to be called when result ready
# File lib/google/api_client/batch.rb, line 120
def add(call, call_id = nil, &block)
  unless call.kind_of?(Google::APIClient::Reference)
    call = Google::APIClient::Reference.new(call)
  end
  call_id ||= new_id
  if @calls.assoc(call_id)
    raise BatchError,
        'A call with this ID already exists: %s' % call_id
  end
  callback = block_given? ? block : @global_callback
  @calls << [call_id, call, callback]        
  return self
end
process_http_response(response) click to toggle source

Processes the HTTP response to the batch request, issuing callbacks.

@api private

@param [Faraday::Response] response

the HTTP response.
# File lib/google/api_client/batch.rb, line 141
def process_http_response(response)
  content_type = find_header('Content-Type', response.headers)
  boundary = %r.*boundary=(.+)/.match(content_type)[1]
  parts = response.body.split(%r--#{Regexp.escape(boundary)}/)
  parts = parts[1...-1]
  parts.each do |part|
    call_response = deserialize_call_response(part)
    _, call, callback = @calls.assoc(call_response.call_id)
    result = Google::APIClient::Result.new(call, call_response)
    callback.call(result) if callback
  end
  Google::APIClient::Result.new(self, response)
end
to_http_request() click to toggle source

Return the request body for the BatchRequest's HTTP request.

@api private

@return [String]

the request body.
# File lib/google/api_client/batch.rb, line 162
def to_http_request
  if @calls.nil? || @calls.empty?
    raise BatchError, 'Cannot make an empty batch request'
  end
  parts = @calls.map {|(call_id, call, callback)| serialize_call(call_id, call)}
  build_multipart(parts, 'multipart/mixed', BATCH_BOUNDARY)
  super
end

Protected Instance Methods

deserialize_call_response(call_response) click to toggle source

Convert a single batched response into a BatchedCallResponse object.

@api private

@param [String] call_response

the request to deserialize.

@return [Google::APIClient::BatchedCallResponse]

the parsed and converted response.
# File lib/google/api_client/batch.rb, line 266
def deserialize_call_response(call_response)
  outer_headers, outer_body = split_headers_and_body(call_response)
  status_line, payload = outer_body.split("\n", 2)
  protocol, status, reason = status_line.split(' ', 3)

  headers, body = split_headers_and_body(payload)
  content_id = find_header('Content-ID', outer_headers)
  call_id = header_to_id(content_id)
  return BatchedCallResponse.new(call_id, status.to_i, headers, body)
end
find_header(name, headers) click to toggle source

Helper method to find a header from its name, regardless of case.

@api private

@param [String] name

the name of the header to find.

@param [Hash] headers

the hash of headers and their values.

@return [String]

the value of the desired header.
# File lib/google/api_client/batch.rb, line 186
def find_header(name, headers)
  _, header = headers.detect do |h, v|
    h.downcase == name.downcase
  end
  return header
end
header_to_id(header) click to toggle source

Convert a Content-ID header value to an id. Presumes the Content-ID header conforms to the format that #id_to_header() returns.

@api private

@param [String] header

Content-ID header value.

@return [String]

The extracted ID value.
# File lib/google/api_client/batch.rb, line 219
def header_to_id(header)
  if !header.start_with?('<') || !header.end_with?('>') ||
      !header.include?('+')
    raise BatchError, 'Invalid value for Content-ID: "%s"' % header
  end

  base, call_id = header[1...-1].split('+')
  return Addressable::URI.unencode(call_id)
end
id_to_header(call_id) click to toggle source

Convert an id to a Content-ID header value.

@api private

@param [String] call_id

identifier of individual call.

@return [String]

A Content-ID header with the call_id encoded into it. A UUID is
prepended to the value because Content-ID headers are supposed to be
universally unique.
# File lib/google/api_client/batch.rb, line 317
def id_to_header(call_id)
  return '<%s+%s>' % [@base_id, Addressable::URI.encode(call_id)]
end
new_id() click to toggle source

Create a new call ID. Uses an auto-incrementing, conflict-avoiding ID.

@api private

@return [String]

the new, unique ID.
# File lib/google/api_client/batch.rb, line 200
def new_id
  @last_auto_id += 1
  while @calls.assoc(@last_auto_id)
    @last_auto_id += 1
  end
  return @last_auto_id.to_s
end
serialize_call(call_id, call) click to toggle source

Serialize a single batched call for assembling the multipart message

@api private

@param [Google::APIClient::Request] call

the call to serialize.

@return [Faraday::UploadIO]

the serialized request
# File lib/google/api_client/batch.rb, line 287
def serialize_call(call_id, call)
  method, uri, headers, body = call.to_http_request
  request = "#{method.to_s.upcase} #{Addressable::URI.parse(uri).request_uri} HTTP/1.1"
  headers.each do |header, value|
    request << "\r\n%s: %s" % [header, value]
  end
  if body
    # TODO - CompositeIO if body is a stream 
    request << "\r\n\r\n"
    if body.respond_to?(:read)
      request << body.read
    else
      request << body.to_s
    end
  end
  Faraday::UploadIO.new(StringIO.new(request), 'application/http', 'ruby-api-request', 'Content-ID' => id_to_header(call_id))
end
split_headers_and_body(response) click to toggle source

Auxiliary method to split the headers from the body in an HTTP response.

@api private

@param [String] response

the response to parse.

@return [Array<Hash>, String]

the headers and the body, separately.
# File lib/google/api_client/batch.rb, line 239
def split_headers_and_body(response)
  headers = {}
  payload = response.lstrip
  while payload
    line, payload = payload.split("\n", 2)
    line.sub!(%r\s+\z/, '')
    break if line.empty?
    match = %r\A([^:]+):\s*/.match(line)
    if match
      headers[match[1]] = match.post_match
    else
      raise BatchError, 'Invalid header line in response: %s' % line
    end
  end
  return headers, payload
end