Lists the information about all versions (including delete markers) of all objects in a bucket.

Note If you perform the GetBucket (ListObjects) operation on a bucket with versioning enabled, only the current versions of the objects (which are not delete markers) in the bucket are returned. To list all versions of all objects in the bucket, you must call the GetBucketVersions interface.

Request parameters

When calling GetBucketVersions, you can limit the information included in the returned list by setting the following parameters: Prefix, Key-marker, Version-id-marker, Delimiter and Max-keys.
Parameter Type Required? Description
Delimiter String No

Specifies a character used to group object names. All the names of the objects that contain a specified prefix and after which the delimiter occurs for the first time, act as a group of elements, that is, CommonPrefixes.

Default value: None
Key-marker String Required if the version-id-marker is not null.

Specifies that the results after the Key-marker are returned in alphabetical order. This parameter must be configured together with Version-id-marker. The size of this parameter must be less than 1,024 bytes.

Default value: None
Version-id-marker String No Specifies that the results after the Version-id-marker of the Key-marker are returned in the creation time order of the versions. However, the version specified in this parameter is not returned. If this parameter is not specified, the results are returned from the version after Key-marker in alphabetical order by default.

Default value: None

Valid value: Valid version IDs
Max-keys String No

Limits the maximum number of objects returned for one request. The max-keys value cannot exceed 1000.

Default value: 100

Note If the results cannot be completely listed because of the setting of Max-keys, the NextKeyMarker and NextVersionIdMarker are added in the results as the Marker for the next ListObjectVersions operation.
Prefix String No

Limits that the returned object key must be prefixed accordingly.

Default value: None

Note
  • The size of this parameter must be less than 1,024 bytes.
  • The keys returned for requests using a prefix still contain the prefix.
Encoding-type String No

Encodes the returned results and specifies the encoding type.

Default value: None

Valid value: url

Note Parameters Delimiter, Key-Marker, Prefix, NextKeyMarker, and Key use UTF-8 characters, but the XML 1.0 Standard does not support parsing certain control characters. If some parameters in the returned results contain characters that are not supported by the XML 1.0 Standard, encoding-type can be specified to encode these parameters, such as Delimiter, Key-Marker, Prefix, NextKeyMarker, and Key.

Response elements

Element Type Description
ListVersionsResult Container

Indicates the container used to store the results returned for the GetBucketVersions request.

Sub-nodes: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, Nextmarker, Version, DeleteMarker

Parent node: None
CommonPrefixes String

If the delimiter parameter is specified in the request, the response returned by OSS contains the CommonPrefixes element. This element indicates the set of objects which ends with a delimiter and have a common prefix.

Parent node: ListVersionsResult
Delimiter String

Indicates a character used to group object names. All those objects whose names contain the specified prefix and after which the delimiter occurs for the first time, act as a group of elements, that is, CommonPrefixes.

Parent node: ListVersionsResult
EncodingType String

Indicates the encoding type for the returned results. If encoding-type is specified in a request, the following elements in the returned results are encoded: Delimiter, Marker, Prefix, NextMarker, and Key.

Parent node: ListVersionsResult
IsTruncated String

Indicates whether all results are returned.

  • true: indicates that not all results are returned for the request.
  • false: indicates that all results are returned for the request.

Valid value: true, false

Parent node: ListVersionsResult
KeyMarker String

Marks the object where the current GetBucketVersions operation starts.

Parent node: ListVersionsResult
VersionIdMarker String

Used together with KeyMarker to specify the version of the object where the GetBucketVersions operation starts.

Parent node: ListVersionsResult
NextKeyMarker String

If not all results are returned, this element is included in the response to indicate the Key-marker for the next request.

Parent node: ListVersionsResult
NextVersionIdMarker String

If not all results are returned, this element is included in the response to indicate the Version-id-marker for the next request.

Parent node: ListVersionsResult
MaxKeys String

Indicates the maximum number of returned results in the response to the request.

Parent node: ListVersionsResult
Name String

Indicates the name of the bucket.

Parent node: ListVersionsResult
Owner Container

Indicates the container used to store the information about the bucket owner.

Parent node: ListVersionsResult
Prefix String

Indicates the prefix of results returned for the request.

Parent node: ListVersionsResult
Version Container

Indicates the container used to store object versions rather than delete markers.

Parent node: ListVersionsResult
DeleteMarker Container

Indicates the container used to store delete markers.

Parent node: ListVersionsResult
ETag String
Indicates the ETag (entity tag) which is created when an object is generated to indicate the content of the object.
  • For an object created by a PutObject request, the value of ETag is the MD5 value of the content of the object.
  • For an object created in other ways, the value of ETag is the UUID of the content of the object.
Note The value of ETag can be used to check whether the content of the object is changed. We recommend that the ETag should not be used as the MD5 value of the object content to verify data integrity.

Parent node: ListVersionsResult.Version
Key String

Indicates the key of an object.

Parent node: ListVersionsResult.Version | ListVersionsResult.DeleteMarker
LastModified Time

Indicates the time when the object is last modified.

Parent node: ListVersionsResult.Version | ListVersionsResult.DeleteMarker
VersionId String

Indicates the version ID of an object.

Parent node: ListVersionsResult.Version | ListVersionsResult.DeleteMarker
IsLatest String

Indicates whether a version is the current version.

  • true: The version is the current version.
  • false: The version is not the current version.

Parent node: ListVersionsResult.Version | ListVersionsResult.DeleteMarker
Size String

Indicates the size of an object in bytes.

Parent node: ListVersionsResult.Version | ListVersionsResult.DeleteMarker
StorageClass String

Indicates the storage class of an object.

Parent node: ListVersionsResult.Version | ListVersionsResult.DeleteMarker
DisplayName String

Indicates the name of the object owner.

Parent node: ListVersionsResult.Version.Owner | ListVersionsResult.DeleteMarker.Owner
ID String

Indicates the user ID of the bucket owner.

Parent node: ListVersionsResult.Version.Owner | ListVersionsResult.DeleteMarker.Owner

Detail analysis

  • Different objects are returned in alphabetical order. Different version of an object is returned in the creation time order.
  • The custom metadata of objects are not returned in the response for the GetBucketVersions request.
  • If the results cannot be completely listed because of the setting of Max-keys, the values of NextKeyMarker and NextVersionIdMarker are added in the results as the Marker for the next ListObjectVersions operation.
  • The Prefix and Marker parameters are set to display results in multiple pages. The size of these two parameters must be less than 1,024 bytes.
  • If you set the value of Prefix to a folder name, all objects prefixed with the folder name, that is, all objects and sub-folders under the folder are recursively listed.

    If you set the value of Prefix to a folder name and the value of Delimiter to a forward slash (/), only the objects in the folder are returned. Names of the sub-folders under the folder is returned in CommonPrefixes. Objects and folders in the sub-folders are not displayed.

    Assume that the following three objects are stored in a bucket: fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi, in which:
    • fun/test.jpg has two versions: V111111 and V222222.
    • fun/movie/001.avi has only one version: V121212.
    • fun/movie/007.avi has only one version: V212121.

    If you set the value of Prefix to fun/, the following four results are returned: fun/test.jpg (V111111), fun/test.jpg (V222222), fun/movie/001.avi (V121212), and fun/movie/007.avi (V212121). If you further set the value of Delimiter to a forward slash (/), fun/test.jpg (V111111), fun/test.jpg (V222222), and fun/movie/ are returned.

Examples

Assume that the following two objects are stored in a bucket named oss example: example and pic.jpg. The object named example has three versions (in the creation time order): 111222, 000123 (delete marker), and 222333. The object named pic.jpg only has one version: 232323.

If you set the value of Key-Marker to example and the value of Version-id-marker to 111222, the results are returned in the following order: example (000123), example (222333), and pic.jpg (232323).

Request example: 
GET /?versions&key-marker=example&version-id-marker=CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1YmMy HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 07:27:48 GMT
Authorization: OSS ami4tq0x76ov9cu:WFx4kLpx+e7Rc0jawCsh7hlk****
Response example: 
HTTP/1.1 200 OK
x-oss-request-id: 5CAC4974B7AEADE01700****
Date: Tue, 09 Apr 2019 07:27:48 GMT
Content-Type: application/xml
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListVersionsResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Name>oss-example</Name>
    <Prefix></Prefix>
    <KeyMarker>example</KeyMarker>
    <VersionIdMarker>CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****</VersionIdMarker>
    <MaxKeys>100</MaxKeys>
    <Delimiter></Delimiter>
    <IsTruncated>false</IsTruncated>
    <DeleteMarker>
        <Key>example</Key>
        <VersionId>CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****</VersionId>
        <IsLatest>false</IsLatest>
        <LastModified>2019-04-09T07:27:28.000Z</LastModified>
        <Owner>
          <ID>1234512528586****</ID>
          <DisplayName>12345125285864390</DisplayName>
        </Owner>
    </DeleteMarker>
    <Version>
        <Key>example</Key>
        <VersionId>CAEQMxiBgMDNoP2D0BYiIDE3MWUxNzgxZDQxNTRiODI5OGYwZGMwNGY3MzZjN****</VersionId>
        <IsLatest>false</IsLatest>
        <LastModified>2019-04-09T07:27:28.000Z</LastModified>
        <ETag>"250F8A0AE989679A22926A875F0A2****"</ETag>
        <Type>Normal</Type>
        <Size>93731</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
          <ID>1234512528586****</ID>
          <DisplayName>12345125285864390</DisplayName>
        </Owner>
    </Version>
    <Version>
        <Key>pic.jpg</Key>
        <VersionId>CAEQMxiBgMCZov2D0BYiIDY4MDllOTc2YmY5MjQxMzdiOGI3OTlhNTU0ODIx****</VersionId>
        <IsLatest>true</IsLatest>
        <LastModified>2019-04-09T07:27:28.000Z</LastModified>
        <ETag>"3663F7B0B9D3153F884C821E7CF4****"</ETag>
        <Type>Normal</Type>
        <Size>574768</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
          <ID>1234512528586****</ID>
          <DisplayName>12345125285864390</DisplayName>
        </Owner>
    </Version>
</ListVersionsResult>

Error codes

Error code HTTP status code Description
NoSuchBucket 404 The target bucket does not exist. The bucket that you access may cannot be created because of the invalid name.
AccessDenied 403 You do not have the permission to access the bucket.
InvalidArgument 400
  • The value of Max-keys is smaller than 0 or larger than 1000.
  • The size of Prefix, Marker, or Delimiter is invalid.
  • The value of Version-id-marker is an invalid version ID.