Module: Aws::PageableResponse

Defined in:
gems/aws-sdk-core/lib/aws-sdk-core/pageable_response.rb

Overview

Note:

Methods such as to_json will enumerate all of the responses before returning the full response as JSON.

Decorates a Seahorse::Client::Response with paging convenience methods. Some AWS calls provide paged responses to limit the amount of data returned with each response. To optimize for latency, some APIs may return an inconsistent number of responses per page. You should rely on the values of the next_page? method or using enumerable methods such as each rather than the number of items returned to iterate through results. See below for examples.

Paged Responses Are Enumerable

The simplest way to handle paged response data is to use the built-in enumerator in the response object, as shown in the following example.

s3 = Aws::S3::Client.new

s3.list_objects(bucket:'aws-sdk').each do |response|
  puts response.contents.map(&:key)
end

This yields one response object per API call made, and enumerates objects in the named bucket. The SDK retrieves additional pages of data to complete the request.

Handling Paged Responses Manually

To handle paging yourself, use the response’s next_page? method to verify there are more pages to retrieve, or use the last_page? method to verify there are no more pages to retrieve.

If there are more pages, use the next_page method to retrieve the next page of results, as shown in the following example.

s3 = Aws::S3::Client.new

# Get the first page of data
response = s3.list_objects(bucket:'aws-sdk')

# Get additional pages
while response.next_page? do
  response = response.next_page
  # Use the response data here...
  puts response.contents.map(&:key)
end

Defined Under Namespace

Classes: LastPageError

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#pager ⇒ Paging::Pager

Returns:

  • (Paging::Pager) 


59
60
61
 
# File 'gems/aws-sdk-core/lib/aws-sdk-core/pageable_response.rb', line 59

def pager
  @pager
end

Class Method Details

.extended(base) ⇒ Object 



51
52
53
54
55
56
 
# File 'gems/aws-sdk-core/lib/aws-sdk-core/pageable_response.rb', line 51

def self.extended(base)
  base.extend Enumerable
  base.extend UnsafeEnumerableMethods
  base.instance_variable_set("@last_page", nil)
  base.instance_variable_set("@more_results", nil)
end

Instance Method Details

#each {|response| ... } ⇒ Enumerable? Also known as: each_page

Yields the current and each following response to the given block.

Yield Parameters:

  • response (Response)

Returns:

  • (Enumerable, nil) —

    Returns a new Enumerable if no block is given.



90
91
92
93
94
95
96
97
98
 
# File 'gems/aws-sdk-core/lib/aws-sdk-core/pageable_response.rb', line 90

def each(&block)
  return enum_for(:each_page) unless block_given?
  response = self
  yield(response)
  until response.last_page?
    response = response.next_page
    yield(response)
  end
end

#last_page? ⇒ Boolean

Returns true if there are no more results. Calling #next_page when this method returns false will raise an error.

Returns:

  • (Boolean) 


64
65
66
67
68
69
 
# File 'gems/aws-sdk-core/lib/aws-sdk-core/pageable_response.rb', line 64

def last_page?
  if @last_page.nil?
    @last_page = !@pager.truncated?(self)
  end
  @last_page
end

#next_page(params = {}) ⇒ Seahorse::Client::Response

Returns:



79
80
81
82
83
84
85
 
# File 'gems/aws-sdk-core/lib/aws-sdk-core/pageable_response.rb', line 79

def next_page(params = {})
  if last_page?
    raise LastPageError.new(self)
  else
    next_response(params)
  end
end

#next_page? ⇒ Boolean

Returns true if there are more results. Calling #next_page will return the next response.

Returns:

  • (Boolean) 


74
75
76
 
# File 'gems/aws-sdk-core/lib/aws-sdk-core/pageable_response.rb', line 74

def next_page?
  !last_page?
end