GET Bucket Object versions
Description
You can use the versions
sub-resource to list metadata about
all of the versions of objects in a bucket. You can also use request parameters as
selection criteria to return metadata about a subset of all the object versions. For
more information, see
To use this operation, you must have READ
access to the bucket.
Requests
Syntax
GET /?versions HTTP/1.1 Host:BucketName
.s3.amazonaws.com Date:date
Authorization:signatureValue
Request Parameters
This implementation of GET
uses the parameters in the
following table to return a subset of the objects in a bucket.
Parameter | Description | Required |
---|---|---|
delimiter |
A delimiter is a character that you specify to group keys. All
keys that contain the same string between the Type: String Default: None |
No |
key-marker |
Specifies the key in the bucket that you want to start listing
from. Also, see Type: String Default: None |
No |
max-keys |
Sets the maximum number of keys returned in the response body.
The response might contain fewer keys, but will never contain
more. If additional keys satisfy the search criteria, but were
not returned because Type: String Default: 1000 |
No |
prefix |
Use this parameter to select only those keys that begin with
the specified prefix. You can use prefixes to separate a bucket
into different groupings of keys. (You can think of using
Type: String Default: None |
No |
version-id-marker |
Specifies the object version you want to start listing from.
Also, see Type: String Default: None Valid Values: Valid version ID | Default Constraint: May not be an empty string |
No |
Request Headers
This implementation of the operation only uses request headers common to all operations. For more information, see Common Request Headers.
Responses
Response Headers
This implementation of the operation uses only response headers that are common to most responses. For more information, see Common Response Headers.
Response Elements
Name | Description |
---|---|
DeleteMarker
|
Container for an object that is a Delete Marker. Type: Container Children: Key, VersionId, IsLatest, LastModified, Owner Ancestor: ListVersionsResult |
DisplayName
|
Object owner's name. Type: String Ancestor: ListVersionsResult.Version.Owner | ListVersionsResult.DeleteMarker.Owner |
ETag
|
The entity tag is an MD5 hash of the object. The ETag only reflects changes to the contents of an object, not its metadata. Type: String Ancestor: ListVersionsResult.Version |
ID
|
Object owner's ID. Type: Boolean Ancestor: ListVersionsResult.Version.Owner | ListVersionsResult.DeleteMarker.Owner |
IsLatest
|
Specifies whether the object is ( Type: Boolean Valid Values: Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker |
IsTruncated
|
A flag that indicates whether ( Type: Boolean Valid Values: Ancestor: ListVersionsResult |
Key
|
The object's key. Type: String Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker |
KeyMarker
|
Marks the last Type: String Ancestor: ListVersionsResult |
LastModified
|
Date and time the object was last modified. Type: Date Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker |
ListVersionsResult
|
Container for the result. Type: Container Children: All elements in the response Ancestor: ListVersionsResult |
MaxKeys
|
Specifies the maximum number of objects to return. Type: String Default: 1000 Valid Values: Integers from 1 to 1000, inclusive Ancestor: ListVersionsResult |
Name
|
Bucket owner's name. Type: String Ancestor: ListVersionsResult |
NextKeyMarker
|
When the number of responses exceeds the value of
Type: String Ancestor: ListVersionsResult |
NextVersionIdMarker
|
When the number of responses exceeds the value of
Type: String Ancestor: ListVersionsResult |
Owner
|
Bucket owner. Type: String Children: DisplayName, ID Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker |
Prefix
|
Selects objects that start with the value supplied by this parameter. Type: String Ancestor: ListVersionsResult |
Size
|
Size in bytes of the object. Type: String Ancestor: ListVersionsResult.Version |
StorageClass
|
Always STANDARD. Type: String Ancestor: ListVersionsResult.Version |
Version
|
Container for version information. Type: Container Ancestor: ListVersionsResult |
VersionId
|
Version ID of an object Type: String Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker |
VersionIdMarker
|
Marks the last version of the Type: String Ancestor: ListVersionsResult |
Special Errors
This implementation of the operation does not return special errors. For general information about Amazon S3 errors and a list of error codes, see Error Responses.
Examples
Sample Request
The following request returns all of the versions of all of the objects in the specified bucket.
GET /?versions HTTP/1.1 Host: BucketName.s3.amazonaws.com Date: Wed, 28 Oct 2009 22:32:00 +0000 Authorization: AWS 02236Q3V0WHVSRW0EXG2:0RQf4/cRonhpaBX5sCYVf1bNRuU=
Sample Response to GET Versions
<?xml version="1.0" encoding="UTF-8"?> <ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01"> <Name>bucket</Name> <Prefix>my</Prefix> <KeyMarker/> <VersionIdMarker/> <MaxKeys>5</MaxKeys> <IsTruncated>false</IsTruncated> <Version> <Key>my-image.jpg</Key> <VersionId>3/L4kqtJl40Nr8X8gdRQBpUMLUo</VersionId> <IsLatest>true</IsLatest> <LastModified>2009-10-12T17:50:30.000Z</LastModified> <ETag>"fba9dede5f27731c9771645a39863328"</ETag> <Size>434234</Size> <StorageClass>STANDARD</StorageClass> <Owner> <ID>8a6925ce4adf58897f21c32aa379004fef</ID> <DisplayName>[email protected]</DisplayName> </Owner> </Version> <DeleteMarker> <Key>my-second-image.jpg</Key> <VersionId>03jpff543dhffds434rfdsFDN943fdsFkdmqnh892</VersionId> <IsLatest>true</IsLatest> <LastModified>2009-11-12T17:50:30.000Z</LastModified> <Owner> <ID>8a6925ce4adf7f21c32aa379004fef</ID> <DisplayName>[email protected]</DisplayName> </Owner> </DeleteMarker> <Version> <Key>my-second-image.jpg</Key> <VersionId>QUpfdndhfd8438MNFDN93jdnJFkdmqnh893</VersionId> <IsLatest>false</IsLatest> <LastModified>2009-10-10T17:50:30.000Z</LastModified> <ETag>"9b2cf535f27731c974343645a3985328"</ETag> <Size>166434</Size> <StorageClass>STANDARD</StorageClass> <Owner> <ID>8a6925ce421c32aa379004fef</ID> <DisplayName>[email protected]</DisplayName> </Owner> </Version> <DeleteMarker> <Key>my-third-image.jpg</Key> <VersionId>03jpff543dhffds434rfdsFDN943fdsFkdmqnh892</VersionId> <IsLatest>true</IsLatest> <LastModified>2009-10-15T17:50:30.000Z</LastModified> <Owner> <ID>8a6925ce4adf532aa379004fef</ID> <DisplayName>[email protected]</DisplayName> </Owner> </DeleteMarker> <Version> <Key>my-third-image.jpg</Key> <VersionId>UIORUnfndfhnw89493jJFJ</VersionId> <IsLatest>false</IsLatest> <LastModified>2009-10-11T12:50:30.000Z</LastModified> <ETag>"772cf535f27731c974343645a3985328"</ETag> <Size>64</Size> <StorageClass>STANDARD</StorageClass> <Owner> <ID>8a6925ce4adf5887f21c32aa379004fef</ID> <DisplayName>[email protected]</DisplayName> </Owner> </Version> </ListVersionsResult>
Sample Request
The following request returns objects in the order they were stored, returning the
most recently stored object first starting with the value for key-marker
.
GET /?versions&key-marker=key2 HTTP/1.1 User-Agent: curl/7.10.6 (i386-redhat-linux-gnu) libcurl/7.10.6 OpenSSL/0.9.7a ipv6 zlib/1.1.4 Host: s3.integ.amazon.com Pragma: no-cache Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */* Date: Thu, 10 Dec 2009 22:46:32 +0000 Authorization: AWS 0A1N5HNJ7ZX40NG0KT02:U1j5vNnJfzmiv3c1GnlG6MLVeZU=
Sample Response
<?xml version="1.0" encoding="UTF-8"?> <ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Name>mtp-versioning-fresh</Name> <Prefix/> <KeyMarker>key2</KeyMarker> <VersionIdMarker/> <MaxKeys>1000</MaxKeys> <IsTruncated>false</IsTruncated> <Version> <Key>key3</Key> <VersionId>I5VhmK6CDDdQ5Pwfe1gcHZWmHDpcv7gfmfc29UBxsKU.</VersionId> <IsLatest>true</IsLatest> <LastModified>2009-12-09T00:19:04.000Z</LastModified> <ETag>"396fefef536d5ce46c7537ecf978a360"</ETag> <Size>217</Size> <Owner> <ID>0fa3c2dd7e785a220ab556f8a401610b750c0b6d62ef87663dd1667a1e068364</ID> </Owner> <StorageClass>STANDARD</StorageClass> </Version> <DeleteMarker> <Key>sourcekey</Key> <VersionId>qDhprLU80sAlCFLu2DWgXAEDgKzWarn-HS_JU0TvYqs.</VersionId> <IsLatest>true</IsLatest> <LastModified>2009-12-10T16:38:11.000Z</LastModified> <Owner> <ID>0fa3c2dd7e785a2d1667a1e068364</ID> </Owner> </DeleteMarker> <Version> <Key>sourcekey</Key> <VersionId>wxxQ7ezLaL5JN2Sislq66Syxxo0k7uHTUpb9qiiMxNg.</VersionId> <IsLatest>false</IsLatest> <LastModified>2009-12-10T16:37:44.000Z</LastModified> <ETag>"396fefef536d5ce46c7537ecf978a360"</ETag> <Size>217</Size> <Owner> <ID>0fa3c2dd7e785a220ab556f8a401610b750c0b6d62ef87663dd1667a1e068364</ID> </Owner> <StorageClass>STANDARD</StorageClass> </Version> </ListVersionsResult>
Sample Request Using prefix
This example returns objects whose keys begin with source
.
GET /?versions&prefix=source HTTP/1.1 Host: bucket.s3.amazonaws.com Date: Wed, 28 Oct 2009 22:32:00 +0000 Authorization: AWS 02236Q3V0WHVSRW0EXG2:0RQf4/cRonhpaBX5sCYVf1bNRuU=
Sample Response
<?xml version="1.0" encoding="UTF-8"?> <ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Name>mtp-versioning-fresh</Name> <Prefix>source</Prefix> <KeyMarker/> <VersionIdMarker/> <MaxKeys>1000</MaxKeys> <IsTruncated>false</IsTruncated> <DeleteMarker> <Key>sourcekey</Key> <VersionId>qDhprLU80sAlCFLu2DWgXAEDgKzWarn-HS_JU0TvYqs.</VersionId> <IsLatest>true</IsLatest> <LastModified>2009-12-10T16:38:11.000Z</LastModified> <Owner> <ID>0fa3c2dd7e78dd1667a1e068364</ID> </Owner> </DeleteMarker> <Version> <Key>sourcekey</Key> <VersionId>wxxQ7ezLaL5JN2Sislq66Syxxo0k7uHTUpb9qiiMxNg.</VersionId> <IsLatest>false</IsLatest> <LastModified>2009-12-10T16:37:44.000Z</LastModified> <ETag>"396fefef536d5ce46c7537ecf978a360"</ETag> <Size>217</Size> <Owner> <ID>0fa3c2d87663dd1667a1e068364</ID> </Owner> <StorageClass>STANDARD</StorageClass> </Version> </ListVersionsResult>
Sample Request Using key-marker and version-id-marker Parameters
The following example returns objects starting at the specified key (key-marker
) and version ID (version-id-marker
).
GET /?versions&key-marker=key3&version-id-marker=t46ZenlYTZBnj HTTP/1.1 Host: bucket.s3.amazonaws.com Date: Wed, 28 Oct 2009 22:32:00 +0000 Authorization: AWS 02236Q3V0WHVSRW0EXG2:0RQf4/cRonhpaBX5sCYVf1bNRuU=
Sample Response
<?xml version="1.0" encoding="UTF-8"?> <ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Name>mtp-versioning-fresh</Name> <Prefix/> <KeyMarker>key3</KeyMarker> <VersionIdMarker>t46ZenlYTZBnj</VersionIdMarker> <MaxKeys>1000</MaxKeys> <IsTruncated>false</IsTruncated> <DeleteMarker> <Key>sourcekey</Key> <VersionId>qDhprLU80sAlCFLu2DWgXAEDgKzWarn-HS_JU0TvYqs.</VersionId> <IsLatest>true</IsLatest> <LastModified>2009-12-10T16:38:11.000Z</LastModified> <Owner> <ID>0fa3c2dd7e785a2201667a1e068364</ID> </Owner> </DeleteMarker> <Version> <Key>sourcekey</Key> <VersionId>wxxQ7ezLaL5JN2Sislq66Syxxo0k7uHTUpb9qiiMxNg.</VersionId> <IsLatest>false</IsLatest> <LastModified>2009-12-10T16:37:44.000Z</LastModified> <ETag>"396fefef536d5ce46c7537ecf978a360"</ETag> <Size>217</Size> <Owner> <ID>0fa3c2dd7e785a663dd1667a1e068364</ID> </Owner> <StorageClass>STANDARD</StorageClass> </Version> </ListVersionsResult>
Sample Request Using key-marker, version-id-marker and max-keys
The following request returns up to three (the value of max-keys
) objects starting with the key specified by key-marker
and the version ID specified by version-id-marker
.
GET /?versions&key-marker=key3&version-id-marker=t46Z0menlYTZBnj HTTP/1.1 Host: bucket.s3.amazonaws.com Date: Wed, 28 Oct 2009 22:32:00 +0000 Authorization: AWS 02236Q3V0WHVSRW0EXG2:0RQf4/cRonhpaBX5sCYVf1bNRuU=
Sample Response
<?xml version="1.0" encoding="UTF-8"?> <ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Name>mtp-versioning-fresh</Name> <Prefix/> <KeyMarker>key3</KeyMarker> <VersionIdMarker>null</VersionIdMarker> <NextKeyMarker>key3</NextKeyMarker> <NextVersionIdMarker>d-d309mfjFrUmoQ0DBsVqmcMV15OI.</NextVersionIdMarker> <MaxKeys>2</MaxKeys> <IsTruncated>true</IsTruncated> <Version> <Key>key3</Key> <VersionId>8XECiENpj8pydEDJdd-_VRrvaGKAHOaGMNW7tg6UViI.</VersionId> <IsLatest>false</IsLatest> <LastModified>2009-12-09T00:18:23.000Z</LastModified> <ETag>"396fefef536d5ce46c7537ecf978a360"</ETag> <Size>217</Size> <Owner> <ID>0fa3c2dd7e785a220ab667a1e068364</ID> </Owner> <StorageClass>STANDARD</StorageClass> </Version> <Version> <Key>key3</Key> <VersionId>d-d309mfjFri40QYukDozqBt3UmoQ0DBsVqmcMV15OI.</VersionId> <IsLatest>false</IsLatest> <LastModified>2009-12-09T00:18:08.000Z</LastModified> <ETag>"396fefef536d5ce46c7537ecf978a360"</ETag> <Size>217</Size> <Owner> <ID>0fa3c2dd7e785a220ad1667a1e068364</ID> </Owner> <StorageClass>STANDARD</StorageClass> </Version> </ListVersionsResult>
Sample Request Using prefix and delimiter
The following request groups under CommonPrefixes object versions whose name
starts with the value of prefix (photos) and ends with the value for the delimiter
(/), in this example. The resposne includes photos/January/
,
photos/February
, and photos/March
.
GET /?versions&prefix=photos&delimiter=/ HTTP/1.1 Host: bucket.s3.amazonaws.com Date: Wed, 28 Oct 2009 22:32:00 +0000 Authorization: AWS 02236Q3V0WHVSRW0EXG2:0RQf4/cRonhpaBX5sCYVf1bNRuU=
Sample Response
<?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01"> <Name>johnsmith</Name> Prefix>photos/</Prefix> Marker/> <MaxKeys>1000</MaxKeys> <Delimiter>/</Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>photos/index.html</Key> <LastModified>2009-01-01T12:00:00.000Z</LastModified> <ETag>"ce1acdafcc879d7eee54cf4e97334078"</ETag> <Size>1234</Size> <Owner> <ID>214153b66967d86f031c7249d1d9a80249109428335cd08f1cdc487b4566cb1b</ ID> <DisplayName>John Smith</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Contents> <CommonPrefixes> <Prefix>photos/January/</Prefix> </CommonPrefixes> </ListBucketResult>