GET Bucket Object versions

After being granted the READ permission for a bucket, you can use this operation to obtain the list of objects in this bucket.

If you specify only the bucket name in the request (GET /BucketName), OBS returns descriptions of all objects (a maximum of 1000 objects) in the bucket.

If you specify one or more parameters among prefix, marker, max-keys, delimiter, and version-id-marker, OBS returns a list of objects in alphabetic order as specified. Table 1 describes the request parameters.

Request Syntax

GET /?versions HTTP/1.1
User-Agent: agent
Host: bucketname.obs.example.com
Accept: */*
Date: date
Authorization: authorization

Request Parameters

You can specify parameters in this request to list desired objects (including objects with different version IDs) in a bucket. Table 1 describes the parameters.

Table 1 Request parameters

Parameter

Description

Remarks

prefix

Limits the response to object keys that begin with the specified prefix.

Type: String

Optional

key-marker

Indicates the object key to start with when listing objects in a bucket. All objects are listed in the dictionary order.

Type: String

Optional

max-keys

Sets the maximum number of object keys returned in the response body. All objects are listed in the dictionary order. The value ranges from 1 to 1000. If the value is not in this range, 1000 is returned by default.

Type: Integer

Optional

delimiter

Indicates a character used to group object keys. All object keys that contain the same string between the prefix and the first occurrence of the delimiter after the prefix are grouped under a single result element CommonPrefixes.

Type: String

Optional

version-id-marker

Indicates the version ID to start with when listing objects in a bucket. All objects are listed in the dictionary order. This parameter is used together with key-marker.

If the value of version-id-marker is not a version ID specified by key-marker, version-id-marker is invalid.

Type: String

Valid Value: object version ID|None

Constraint: This parameter cannot be an empty string.

Optional

Request Headers

This request uses common headers. For details about common request headers, see section Common Request Headers.

If you want to obtain CORS configuration information, you must use the headers in Table 2.

Table 2 Request headers of CORS configuration

Header

Description

Remarks

Origin

Indicates an origin specified by a pre-request. Generally, it is a domain name.

Type: String

Mandatory

Access-Control-Request-Headers

Indicates the HTTP headers of a request. The request can use multiple HTTP headers.

Type: String

Optional

x-amz-security-token

Header field used to identify the request of a federated user. When the federal authentication function is enabled, users sending such requests are identified as federated users.

Type: string

Optional. This parameter must be carried in the request sent by federated users.

Request Elements

This request involves no elements.

Response Syntax

HTTP/1.1 status_code
 Server: OBS
 x-amz-request-id: request id
 x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc
 x-amz-id-2: id
 Content-Type: type
 Date: date
 Content-Length: length

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <ListVersionsResult xmlns="http://obs.example.com/doc/2015-06-30/">
 <Name>bucket</Name>
 <Prefix/>
 <KeyMarker/>
 <VersionIdMarker/>
 <NextKeyMarker>nextKeyMarker</NextKeyMarker>
 <NextVersionIdMarker>nextVersionIdMarker</NextVersionIdMarker>
 <MaxKeys>maxKeys</MaxKeys>
 <IsTruncated>boolean</IsTruncated>
 <Version>
 <Key>object</Key>
 <VersionId>versionId</VersionId>
 <IsLatest>boolean</IsLatest>
 <LastModified>date</LastModified>
 <ETag>String</ETag>
 <Size>size</Size>
 <Owner>
 <ID>ownerID</ID>
 <DisplayName>name</DisplayName>
 </Owner>
 </Version>
 <DeleteMarker>
 <Key>object</Key>
 <VersionId>versionId</VersionId>
 <IsLatest>boolean</IsLatest>
 <LastModified>date</LastModified>
 <Owner>
 <ID>ownerID</ID>
 <DisplayName>name</DisplayName>
 </Owner>
 </DeleteMarker>
 </ListVersionsResult>

Response Headers

This response uses common headers. For details about common response headers, see section Common Response Headers.

In addition to common headers, when CORS is configured for buckets, you can use the response headers in Table 3.

Table 3 Appended response headers

Header

Description

Access-Control-Allow-Origin

If Origin in the request meets the CORS configuration requirements, Origin is included in the response.

Type: String

Access-Control-Allow-Headers

If headers in the request meet the CORS configuration requirements, headers are included in the response.

Type: String

Access-Control-Max-Age

Indicates MaxAgeSeconds in the CORS configuration of a server.

Type: Integer

Access-Control-Allow-Methods

If Access-Control-Request-Method in the request meets the CORS configuration requirements, methods in the rule are included in the response.

Type: String

Valid values: GET, PUT, HEAD, POST, and DELETE

Access-Control-Expose-Headers

Indicates ExposeHeader in the CORS configuration of a server.

Type: String

Response Elements

This response contains elements to specify the objects (including objects with multiple version IDs) in a bucket. Table 4 describes the elements.

Table 4 Response elements

Element

Description

ListVersionsResult

Indicates the container for the list of objects (including objects with multiple version IDs).

Type: Container

Name

Indicates the bucket name.

Type: String

Ancestor: ListVersionsResult

Prefix

Indicates the prefix of an object key. Only objects whose keys have this prefix are listed.

Type: String

Ancestor: ListVersionsResult

KeyMarker

Indicates the object key to start with when listing objects.

Type: String

Ancestor: ListVersionsResult

VersionIdMarker

Indicates the object version ID to start with when listing objects.

Type: String

Ancestor: ListVersionsResult

NextKeyMarker

Indicates the key marker for the last returned object in the list. NextKeyMarker is returned when not all the objects are listed. You can set the KeyMarker value to list the remaining objects in follow-up requests.

Type: String

Ancestor: ListVersionsResult

NextVersionIdMarker

Indicates the version ID marker for the last returned object in the list. NextVersionIdMarker is returned when not all the objects are listed. You can set the VersionIdMarker value to list the remaining objects in follow-up requests.

Type: String

Ancestor: ListVersionsResult

MaxKeys

Indicates the maximum objects returned.

Type: String

Ancestor: ListVersionsResult

IsTruncated

Determines whether the returned list of objects is truncated. true indicates that the result is incomplete while false indicates that the result is complete.

Type: Boolean

Ancestor: ListVersionsResult

Version

Indicates the container for version information.

Type: Container

Ancestor: ListVersionsResult

DeleteMarker

Indicates the container for objects with deletion marks.

Type: Container

Ancestor: ListVersionsResult

key

Name of an object

Type: String

Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

VersionId

Indicates the object version ID.

Type: String

Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

IsLatest

Specifies whether the object is or is not of the latest version. If the element is true, the object is of the latest version.

Type: Boolean

Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

LastModified

Indicates the date and time when the last modification was made to an object.

Type: Date

Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

ETag

MD5 value of an object

Type: String

Ancestor: ListVersionsResult.Version

Size

Number of bytes of an object

Type: String

Ancestor: ListVersionsResult.Version

Owner

User information, including the DomainId and name

Type: Container

Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

ID

DomainId of an object owner

Type: String

Ancestor: ListVersionsResult.Version.Owner | ListVersionsResult.DeleteMarker.Owner

DisplayName

Name of an object owner

Type: String

Ancestor: ListVersionsResult.Version.Owner | ListVersionsResult.Version.Owner

CommonPrefixes

Grouping information. If you specify a delimiter in the request, the response contains grouping information in CommonPrefixes.

Type: Container

Ancestor: ListVersionsResult

Prefix

Indicates a different prefix in the grouping information in CommonPrefixes.

Type: String

Ancestor: ListVersionsResult.CommonPrefixes

Error Responses

No special error responses are returned. For details about error responses, see Table 1.

Sample Request

GET /?versions HTTP/1.1
 User-Agent: curl/7.19.0
 Host: bucketname.obs.example.com
 Accept: */*
 Date: Thu, 16 Jan 2014 03:31:26 +0000
 Authorization: AWS C9590CEB8EC051BDEC9D:KfF0yCAt+LAE/AE0YTxQS7IzQ8U=

Sample Response

HTTP/1.1 200 OK
 Server: OBS
 x-amz-request-id: DCD2FC9CAB7800000143991A7DEECBF4
 x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc
 x-amz-id-2: 00QkPL575tIUmU8kth0zA16DlRzzdDiVDHK4OaGeujayXCfdD7phC21ZZYmVqx3W
 Content-Type: application/xml
 Date: Thu, 16 Jan 2014 03:31:26 GMT
 Content-Length: 1275

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <ListVersionsResult xmlns="http://obs.example.com/doc/2015-06-30/">
<Name>bucket</Name>
 <Prefix/>
 <KeyMarker/>
 <VersionIdMarker/>
 <MaxKeys>1000</MaxKeys>
 <IsTruncated>false</IsTruncated>
 <DeleteMarker>
 <Key>key0</Key>
 <VersionId>AAABQ5kabBnc0vycq3gAAABCVURTRkha</VersionId>
 <IsLatest>true</IsLatest>
 <LastModified>2014-01-16T03:31:22.265Z</LastModified>
 <Owner>
 <ID>DCD2FC9CAB78000001438EC051BD0002</ID>
 <DisplayName>user</DisplayName>
 </Owner>
 </DeleteMarker>
 <Version>
 <Key>key0</Key>
 <VersionId>AAABQ5kZxWTc0vycq3gAAABBVURTRkha</VersionId>
 <IsLatest>false</IsLatest>
 <LastModified>2014-01-16T03:30:39.575Z</LastModified>
 <ETag>"6b0e1cad9fd2eff22004e28aa8073420"</ETag>
 <Size>80</Size>
 <Owner>
 <ID>DCD2FC9CAB78000001438EC051BD0002</ID>
 <DisplayName>user</DisplayName>
 </Owner>
 </Version>
 <Version>
 <Key>suspend</Key>
 <VersionId>null</VersionId>
 <IsLatest>true</IsLatest>
 <LastModified>2014-01-16T03:25:58.443Z</LastModified>
 <ETag>"a65d3be0857de44e470e0c069e4b04e3"</ETag>
 <Size>80</Size>
 <Owner>
 <ID>DCD2FC9CAB78000001438EC051BD0002</ID>
 <DisplayName>user</DisplayName>
 </Owner>
 </Version>
 </ListVersionsResult>

Sample Request (Example of getting bucket object versions by using key-marker and version-id-marker)

GET /?versions&key-marker=key0&version-id-marker=AAABQ5kabBnc0vycq3gAAABCVURTRkha HTTP/1.1
 User-Agent: curl/7.19.0
 Host: bucketname.obs.example.com
 Accept: */*
 Date: Thu, 16 Jan 2014 04:48:20 +0000
 Authorization: AWS C9590CEB8EC051BDEC9D:iw+nTJEMO5KLMoE66sqzkRF3ik0=

Sample Response (Example of getting bucket object versions by using key-marker and version-id-marker)

HTTP/1.1 200 OK
 Server: OBS
 x-amz-request-id: DCD2FC9CAB78000001439960E2F3F18A
 x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc
 x-amz-id-2: P1j6zAy1GOP9KoRUWgJt3mJGKNLlAU4dn7BfL16VXpeWCX/25cZpshp5mTbu1kyw
 Content-Type: application/xml
 Date: Thu, 16 Jan 2014 04:48:20 GMT
 Content-Length: 1051

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <ListVersionsResult xmlns="http://obs.example.com/doc/2015-06-30/">
 <Name>bucket</Name>
 <Prefix/>
 <KeyMarker>key0</KeyMarker>
 <VersionIdMarker>AAABQ5kabBnc0vycq3gAAABCVURTRkha</VersionIdMarker>
 <MaxKeys>1000</MaxKeys>
 <IsTruncated>false</IsTruncated>
 <Version>
 <Key>key0</Key>
 <VersionId>AAABQ5kZxWTc0vycq3gAAABBVURTRkha</VersionId>
 <IsLatest>false</IsLatest>
 <LastModified>2014-01-16T03:30:39.575Z</LastModified>
 <ETag>"6b0e1cad9fd2eff22004e28aa8073420"</ETag>
 <Size>80</Size>
 <Owner>
 <ID>DCD2FC9CAB78000001438EC051BD0002</ID>
 <DisplayName>user</DisplayName>
 </Owner>
 </Version>
 <Version>
 <Key>suspend</Key>
 <VersionId>null</VersionId>
 <IsLatest>true</IsLatest>
 <LastModified>2014-01-16T03:25:58.443Z</LastModified>
 <ETag>"a65d3be0857de44e470e0c069e4b04e3"</ETag>
 <Size>80</Size>
 <Owner>
 <ID>DCD2FC9CAB78000001438EC051BD0002</ID>
 <DisplayName>user</DisplayName>
 </Owner>
 </Version>
 </ListVersionsResult>