This page describes how different Cloud Storage tools and libraries paginate results. Pagination is required when listing a high number of objects or buckets.
Console
The Google Cloud console automatically paginates bucket and object lists in the Buckets and Bucket details pages.
Command line
The Google Cloud CLI automatically paginates bucket and object lists.
Client libraries
C++
Client libraries perform pagination by default. When you call a function
that supports pagination, an iterator is returned in the response. For
an example of how this iterator is used, see the C++ reference
documentation for ListObjects()
.
C#
Client libraries perform pagination by default. When you call a function
that supports pagination, an iterator is returned in the response. For
an example of how this iterator is used, see the C# reference
documentation for ListObjects()
.
Go
Client libraries perform pagination by default. When you call a function
that supports pagination, an iterator is returned in the response. For
an example of how this iterator is used, see the Go reference
documentation for Bucket.Objects
.
Java
Client libraries perform pagination by default. When you call a function that supports pagination, a page token is returned in the response. For an example of how this is used, see the Java reference documentation.
Node.js
Client libraries perform pagination by default. When you call a function
that supports pagination, an iterator is returned in the response. For
an example of how this iterator is used, see the Node.js reference
documentation for getFiles()
.
PHP
Client libraries perform pagination by default. When you call a function
that supports pagination, an iterator is returned in the response. For
an example of how this iterator is used, see the PHP reference
documentation for Objects
.
Python
Client libraries perform pagination by default. When you call a function that supports pagination, an iterator is returned in the response. For an example of how this iterator is used, see the Python reference documentation for page iterators.
Ruby
Client libraries perform pagination by default. When you call a function
that supports pagination, an iterator is returned in the response. For
an example of how this iterator is used, see the Ruby reference
documentation for Google::Cloud::Storage::File::List
.
REST APIs
JSON API
When you call a function that supports pagination, the continuation
token nextPageToken
is returned in the response if the listing is
incomplete. The nextPageToken
represents the
last result that's returned. When you pass the value of nextPageToken
to the pageToken
parameter of a subsequent request, you return the
next page of results, starting after the last result.
For example, say your request to list objects in a bucket named
my-bucket
contains a nextPageToken
in the response:
{ "kind": "storage#objects", "nextPageToken": "CgtzaGliYS0yLmpwZw==", "items": [ { OBJECT_1_METADATA }, { OBJECT_2_METADATA }, … ] }
The HTTP request you would use to continue listing objects in
my-bucket
would be the following:
GET https://storage.googleapis.com/storage/v1/b/my-bucket/o?pageToken=CgtzaGliYS0yLmpwZw==
For more information on paginating results, see the JSON reference
documentation for Objects: list
or Buckets: list
.
XML API
When you call a function that supports pagination, the continuation
token NextContinuationToken
is returned in the response if the listing
is incomplete. The NextContinuationToken
represents the last result
that's returned. When you pass the value of NextContinuationToken
to
the continuation-token
parameter of a subsequent request, you return
the next page of results, starting after the last result.
For example, say your request to list objects in a bucket named
my-bucket
contains a NextContinuationToken
in the response:
<?xml version='1.0' encoding='UTF-8'?> <ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'> <Name>my-bucket</Name> <NextContinuationToken>CgtzaGliYS0yLmpwZw==</NextContinuationToken> <KeyCount>2</KeyCount> <MaxKeys>2</MaxKeys> <IsTruncated>true</IsTruncated> <Contents> ... </Contents> ... </ListBucketResult>
Note that list-type
must be set to 2
in order to return a
NextContinuationToken
when listing objects.
The HTTP request you would use to continue listing objects in
my-bucket
would include the following:
GET /?continuation-token=CgtzaGliYS0yLmpwZw==&list-type=2 HTTP/1.1 Host: my-bucket.storage.googleapis.com
For more detailed instructions on paginating through results from a
bucket, see the XML reference documentation for List Objects
.