Lists the versions of all objects and delete markers in a bucket.

Usage notes

If you call the GetBucketVersions(ListObjectVersions) and GetBucket(ListObjects) operations on a versioned bucket, the following different results are returned:

  • In the response to a GetBucket(ListObjects) request, the current versions of objects in the bucket are returned, excluding delete markers.
  • In the response to a GetBucketVersions(ListObjectVersions) request, all versions of objects in the bucket are returned, including delete markers.

    Objects are returned in alphabetic order, but the versions of each object are returned by creation time in descending order.

Request headers

A GetBucketVersions(ListObjectVersions) request contains only common request headers such as Authorization and Host. For more information about common request headers, see Common request headers.

Request parameters

When you call the GetBucketVersions(ListObjectVersions) operation, you can specify the following parameters to filter the returned results: prefix, key-marker, version-id-marker, delimiter, and max-keys.

Parameter Type Required Example Description
delimiter String No / The character that is used to group objects by name. If you specify the delimiter parameter in the request, the response contains the CommonPrefixes element. Objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in CommonPrefixes.

If you set prefix to a directory name and delimiter to a forward slash (/), only objects in the directory are returned. The names of the subdirectories within the directory are returned in the CommonPrefixes element. However, objects and directories within the subdirectories are not listed.

This parameter is empty by default.

key-marker String The key-marker parameter is required if the version-id-marker parameter is specified. example Specifies that objects whose names are alphabetically greater than the key-marker value are returned. This parameter can be specified together with version-id-marker.

The key-marker value must be less than 1,024 bytes in length.

This parameter is empty by default.

version-id-marker String No CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1**** Specifies that the versions created before the version specified by version-id-marker for the object whose name is specified by key-marker are returned by creation time in descending order. By default, if this parameter is not specified, the results are returned from the latest version of the object whose name is alphabetically greater than the key-marker value.

This parameter is empty by default.

Valid values: version IDs

max-keys String No 100 The maximum number of objects to return.

If the number of returned objects exceeds the max-keys value, the response contains the NextKeyMarker and NextVersionIdMarker elements as the markers for the next GetBucketVersions(ListObjectVersions) request. The NextKeyMarker and NextVersionIdMarker values are included in the response.

Valid values: 1 to 1000

Default value: 100

prefix String No fun The prefix that the names of returned objects must contain.
  • The prefix value must be less than 1,024 bytes in length.
  • If you specify a prefix in the request, the names of the returned objects contain the prefix.

If you set prefix to a directory name in the request, the objects whose names contain the prefix are listed, including all objects and subdirectories within the directory.

This parameter is empty by default.

encoding-type String No URL The encoding type of the content in the response.

This parameter is empty by default.

Valid value: URL

Notice The delimiter, marker, prefix, NextMarker, and Key values are UTF-8 encoded. If the delimiter, marker, prefix, NextMarker, or Key value contains a control character that is not supported by the XML 1.0 standard, you can specify encoding-type to encode the value in the response.

Response elements

Element Type Example Description
ListVersionsResult Container N/A The container that stores the results of the GetBucketVersions(ListObjectVersions) request.

Child nodes: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, NextMarker, Version, and DeleteMarker

Parent nodes: none

CommonPrefixes String N/A If the delimiter parameter is specified in the request, the response contains the CommonPrefixes element. Objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in CommonPrefixes.

Parent nodes: ListVersionsResult

Delimiter String / The character that is used to group objects by name. If you specify the delimiter parameter in the request, the response contains the CommonPrefixes element. Objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in CommonPrefixes.

Parent nodes: ListVersionsResult

EncodingType String URL The encoding type of the content in the response. If you specify encoding-type in the request, the Delimiter, Marker, Prefix, NextMarker, and Key values are encoded in the response.

Parent nodes: ListVersionsResult

IsTruncated String true Indicates whether the returned results are truncated.
  • true: indicates that not all of the results are returned this time.
  • false: indicates that all of the results are returned this time.

Valid values: true and false

Parent nodes: ListVersionsResult

KeyMarker String example Indicates the object from which the GetBucketVersions(ListObjectVersions) operation starts.

Parent nodes: ListVersionsResult

VersionIdMarker String CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1**** This element is returned together with KeyMarker to indicate the version from which the GetBucketVersions(ListObjectVersions) operation starts.

Parent nodes: ListVersionsResult

NextKeyMarker String test If not all results are returned for the request, the NextKeyMarker element is contained in the response to indicate the key-marker value of the next GetBucketVersions(ListObjectVersions) request.

Parent nodes: ListVersionsResult

NextVersionIdMarker String CAEQGBiBgIC_jq7P9xYiIDRiZWJkNjY2Y2Q4NDQ5ZTI5ZGE5ODIxMTIyZThl**** If not all of the results are returned for the request, the NextVersionIdMarker element is contained in the response to indicate the version-id-marker value of the next GetBucketVersions(ListObjectVersions) request.

Parent nodes: ListVersionsResult

MaxKeys String 1000 The maximum number of returned objects in the response.

Parent nodes: ListVersionsResult

Name String examplebucket-1250000000 The name of the bucket.

Parent nodes: ListVersionsResult

Owner Container N/A The container that stores the information about the bucket owner.

Parent nodes: ListVersionsResult

Prefix String fun The prefix that must be included in the names of the listed objects.

Parent nodes: ListVersionsResult

Version Container N/A The container that stores the versions of objects, excluding delete markers.

Parent nodes: ListVersionsResult

DeleteMarker Container N/A The container that stores delete markers.

Parent nodes: ListVersionsResult

ETag String 250F8A0AE989679A22926A875F0A2**** The entity tag (ETag) that is generated when an object is created. ETags are used to identify the content of objects.
  • If an object is created by calling the PutObject operation, the ETag value of the object is the MD5 hash of the object content.
  • If an object is created by using another method, the ETag value is not the MD5 hash of the object content but a unique value calculated based on a specific rule.
Note The ETag value of an object can be used only to check whether the object content is modified. We recommend that you use the MD5 hash of an object rather than the ETag value of the object to verify data integrity.

Parent nodes: ListVersionsResult.Version

Key String example The name of the object.

Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker

LastModified Time 2019-04-09T07:27:28.000Z The last modified time of the object.

Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker

VersionId String CAEQMxiBgMDNoP2D0BYiIDE3MWUxNzgxZDQxNTRiODI5OGYwZGMwNGY3MzZjN**** The version ID of the object.

Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker

IsLatest String true Indicates whether the version is the current version.
Valid values:
  • true: The version is the current version.
  • false: The version is a previous version.

Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker

Size String 93731 The size of the returned object. Unit: bytes.

Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker

StorageClass String Standard The storage class of the object.

Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker

DisplayName String 12345125285864390 The name of the object owner.

Parent nodes: ListVersionsResult.Version.Owner and ListVersionsResult.DeleteMarker.Owner

ID String 1234512528586**** The user ID of the bucket owner.

Parent nodes: ListVersionsResult.Version.Owner and ListVersionsResult.DeleteMarker.Owner

RestoreInfo String ongoing-request="true" The restoration status of the object.
  • If no RestoreObject requests are sent or the requests expire, this field is not included in the response.
  • If a RestoreObject request is sent and the object is still being restored, the returned RestoreInfo value is ongoing-request="true".
  • If a RestoreObject request is sent and the object is restored, the returned RestoreInfo value is in the following format: ongoing-request="false”, expiry-date="Thr, 24 Mon 2020 12:40:33 GMT". In this returned RestoreInfo value, the expiry-date field indicates the time before which the restored object can be read.

For more information about the common response headers such as x-oss-request-id and Content-Type contained in the response to a GetBucketVersions(ListObjectVersions) request, see Common response headers.

Examples

  • List the versions of objects in an unversioned bucket

    Sample requests

    GET /?versions HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 07:27:48 GMT
    Authorization: OSS ami4tq0x76ov9cu:WFx4****+e7Rc0jawCsh7hlk****

    Sample responses

    HTTP/1.1 200 OK
    Content-Type: application/xml
    Content-Length: 1262
    Connection: keep-alive
    Date: Thu, Tue, 09 Apr 2019 07:27:48 GMT
    Server: AliyunOSS
    x-cos-request-id: 534B371674E88A4D8906****
    
    <ListVersionsResult>
        <Name>examplebucket-1250000000</Name>
        <Prefix/>
        <KeyMarker/>
        <VersionIdMarker/>
        <MaxKeys>1000</MaxKeys>
        <IsTruncated>false</IsTruncated>
        <Version>
            <Key>example-object-1.jpg</Key>
            <VersionId/>
            <IsLatest>true</IsLatest>
            <LastModified>2019-08-5T12:03:10.000Z</LastModified>
            <ETag>5B3C1A2E053D763E1B669CC607C5A0FE1****</ETag>
            <Size>20</Size>
            <StorageClass>STANDARD</StorageClass>
            <Owner>
                <ID>1250000000</ID>
                <DisplayName>1250000000</DisplayName>
            </Owner>
        </Version>
        <Version>
            <Key>example-object-2.jpg</Key>
            <VersionId/>
            <IsLatest>true</IsLatest>
            <LastModified>2019-08-9T12:03:09.000Z</LastModified>
            <ETag>5B3C1A2E053D763E1B002CC607C5A0FE1****</ETag>
            <Size>20</Size>
            <StorageClass>STANDARD</StorageClass>
            <Owner>
                <ID>1250000000</ID>
                <DisplayName>1250000000</DisplayName>
            </Owner>
        </Version>
        <Version>
            <Key>example-object-3.jpg</Key>
            <VersionId/>
            <IsLatest>true</IsLatest>
            <LastModified>2019-08-10T12:03:08.000Z</LastModified>
            <ETag>4B3F1A2E053D763E1B002CC607C5AGTRF****</ETag>
            <Size>20</Size>
            <StorageClass>STANDARD</StorageClass>
            <Owner>
                <ID>1250000000</ID>
                <DisplayName>1250000000</DisplayName>
            </Owner>
        </Version>
    </ListVersionsResult>
  • List the versions of objects in a versioned bucket

    In this example, two objects named example and pic.jpg are stored in a bucket named oss-example. The object named example has the following three versions which are displayed by creation time in descending order: 111222, 000123 (delete marker), and 222333. The object named pic.jpg has only one version whose ID is 232323.

    If you set key-marker to example and version-id-marker to 111222, the following three versions are returned in sequence: 000123 of example, 222333 of example, and 232323 of pic.jpg.

    Sample requests

    GET /?versions&key-marker=example&version-id-marker=CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1**** HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 07:27:48 GMT
    Authorization: OSS ami4tq0x76o****:WFx4kLpx+e7Rc0jawCsh7hlk****

    Sample responses

    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>
  • Archive objects and Cold Archive objects stored in the requested bucket
    In this example,the examplebucket bucket contains the following three Cold Archive objects: exampleobject1.txt, exampleobject2.txt, and exampleobject3.txt. The three objects are in the following different states:
    • No RestoreObject requests are sent to restore exampleobject1.txt or the RestoreObject requests sent to restore the object expire.
    • A RestoreObject request is sent to restore exampleobject2.txt. The object is still being restored.
    • A RestoreObject request is sent to restore exampleobject3.txt and the object is restored.

    Sample requests

    GET / HTTP/1.1
    Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykbo****

    Sample responses

    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>
        <Version>
            <Key>exampleobject1.txt</Key>
            <VersionId>CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****</VersionId>
            <IsLatest>false</IsLatest>
            <LastModified>2019-04-09T07:27:28.000Z</LastModified>
            <Owner>
              <ID>1234512528586****</ID>
              <DisplayName>12345125285864390</DisplayName>
            </Owner>
         </Version>
        <Version>
            <Key>exampleobject2.txt</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>
            <RestoreInfo>ongoing-request="true"</RestoreInfo>
            <Owner>
              <ID>1234512528586****</ID>
              <DisplayName>12345125285864390</DisplayName>
            </Owner>
         </Version>
        <Version>
            <Key>exampleobject3.txt</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>
            <RestoreInfo>ongoing-request="false", expiry-date="Thr, 24 Mon 2020 12:40:33 GMT"</RestoreInfo>
            <Owner>
              <ID>1234512528586****</ID>
              <DisplayName>12345125285864390</DisplayName>
            </Owner>
         </Version>
    </ListVersionsResult>

SDK

You can use OSS SDKs for the following programming languages to call the GetBucketVersions(ListObjectVersions) operation:

Error codes

Error code HTTP status code Description
NoSuchBucket 404 The error message returned because the requested bucket does not exist. Check whether the name of the requested bucket complies with the naming rules.
AccessDenied 403 The error message returned because you are not authorized to access the bucket. Only the bucket owner and RAM users who are granted the oss:ListObjectVersions permission can access the bucket.
InvalidArgument 400
  • The error message returned because the max-keys value is less than 0 or greater than 1,000.
  • The error message returned because the length of the prefix, marker, or delimiter value is invalid.