Listing objects in a versioning-enabled bucket
This section provides examples of listing object versions from a versioning-enabled
bucket. Amazon S3 stores object version information in the versions
subresource that is associated with the bucket. For more information, see Bucket configuration options.
In order to list the objects in a versioning-enabled bucket, you need the
ListBucketVersions
permission.
Follow these steps to use the Amazon S3 console to see the different versions of an object.
To see multiple versions of an object
Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/
. -
In the Buckets list, choose the name of the bucket that contains the object.
-
To see a list of the versions of the objects in the bucket, choose the Show versions switch.
For each object version, the console shows a unique version ID, the date and time the object version was created, and other properties. (Objects stored in your bucket before you set the versioning state have a version ID of null.)
To list the objects without the versions, choose the List versions switch.
You also can view, download, and delete object versions in the object overview pane on the console. For more information, see Viewing object properties in the Amazon S3 console.
Note
To access object versions older than 300 versions, you must use the AWS CLI or the object's URL.
Important
You can undelete an object only if it was deleted as the latest (current) version. You can't undelete a previous version of an object that was deleted. For more information, see Retaining multiple versions of objects with S3 Versioning.
The examples in this section show how to retrieve an object listing from a versioning-enabled bucket. Each request returns up to 1,000 versions, unless you specify a lower number. If the bucket contains more versions than this limit, you send a series of requests to retrieve the list of all versions. This process of returning results in "pages" is called pagination.
To show how pagination works, the examples limit each response to two object versions. After retrieving the first page of results, each example checks to determine whether the version list was truncated. If it was, the example continues retrieving pages until all versions have been retrieved.
Note
The following examples also work with a bucket that isn't
versioning-enabled, or for objects that don't have individual versions. In
those cases, Amazon S3 returns the object listing with a version ID of
null
.
For information about using other AWS SDKs, see the AWS Developer Center
Example — Listing all object versions in a bucket
To list all the versions of all the objects in a bucket, you use the
versions
subresource in a GET Bucket
request.
Amazon S3 can retrieve a maximum of 1,000 objects, and each object version counts
fully as an object. Therefore, if a bucket contains two keys (for example,
photo.gif
and picture.jpg
),
and the first key has 990 versions and the second key has 400 versions, a
single request would retrieve all 990 versions of
photo.gif
and only the most recent 10 versions of
picture.jpg
.
Amazon S3 returns object versions in the order in which they were stored, with the most recently stored returned first.
In a GET Bucket
request, include the versions
subresource.
GET /?versions HTTP/1.1 Host:
bucketName
.s3.amazonaws.com Date: Wed, 28 Oct 2009 22:32:00 +0000 Authorization: AWSAKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=
Example — Retrieving all versions of a key
To retrieve a subset of object versions, you use the request parameters for GET
Bucket
. For more information, see GET Bucket.
-
Set the
prefix
parameter to the key of the object that you want to retrieve. -
Send a
GET Bucket
request using theversions
subresource andprefix
.GET /?versions&prefix=objectName HTTP/1.1
Example — Retrieving objects using a prefix
The following example retrieves objects whose key is or begins with
myObject
.
GET /?versions&prefix=myObject HTTP/1.1 Host: bucket.s3.amazonaws.com Date: Wed, 28 Oct 2009 22:32:00 GMT Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=
You can use the other request parameters to retrieve a subset of all versions of the object. For more information, see GET Bucket in the Amazon Simple Storage Service API Reference.
Example — Retrieving a listing of additional objects if the response is truncated
If the number of objects that could be returned in a GET
request exceeds the value of max-keys
, the response contains
<isTruncated>true</isTruncated>
, and includes
the first key (in NextKeyMarker
) and the first version ID (in
NextVersionIdMarker
) that satisfy the request, but were not
returned. You use those returned values as the starting position in a
subsequent request to retrieve the additional objects that satisfy the
GET
request.
Use the following process to retrieve additional objects that satisfy the original
GET Bucket versions
request from a bucket. For more
information about key-marker
, version-id-marker
,
NextKeyMarker
, and NextVersionIdMarker
, see
GET
Bucket in the Amazon Simple Storage Service API Reference.
The following are additional responses that satisfy the original GET
request:
-
Set the value of
key-marker
to the key returned inNextKeyMarker
in the previous response. -
Set the value of
version-id-marker
to the version ID returned inNextVersionIdMarker
in the previous response. -
Send a
GET Bucket versions
request usingkey-marker
andversion-id-marker
.
Example — Retrieving objects starting with a specified key and version ID
GET /?versions&key-marker=myObject&version-id-marker=298459348571 HTTP/1.1 Host: bucket.s3.amazonaws.com Date: Wed, 28 Oct 2009 22:32:00 GMT Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=
The following command returns metadata about all versions of the objects in a bucket.
aws s3api list-object-versions --bucket
amzn-s3-demo-bucket1
For more information about list-object-versions
see list-object-versions in the
AWS CLI Command Reference.