All Products
Search
Document Center

Object Storage Service:ListObjectVersions (GetBucketVersions)

Last Updated:Sep 21, 2023

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

Usage notes

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

  • When you call the ListObjectVersions (GetBucketVersions) operation, objects are returned in alphabetic order, but the versions of each object are returned by creation time in descending order.

  • If you have enabled Logging and Real-time log query, the operation field in the access logs generated by calling the ListObjectVersions (GetBucketVersions) operation is GetBucket.

  • You are charged based on the number of PUT requests when you call the ListObjectVersions (GetBucketVersions) operation. For more information, see API operation calling fees.

Request syntax

GET /?versions HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

This request contains only common request headers. For more information, see Common HTTP headers.

Request parameters

When you call the ListObjectVersions (GetBucketVersions) 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 you want to use to group objects by name. If you specify the delimiter parameter in the request, the response contains the CommonPrefixes parameter. Objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result parameter 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 in the directory are returned in the CommonPrefixes parameter. However, objects and directories in the subdirectories are not listed.

By default, this header is left empty.

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 after the value of the key-marker parameter are returned. This parameter can be specified together with version-id-marker.

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

By default, this header is left empty.

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 after the value of key-marker.

By default, this header is left empty.

Valid values: version IDs

max-keys

String

No

100

The maximum number of objects to return.

If the number of returned objects exceeds the value of the max-keys parameter, the response contains the NextKeyMarker parameter and NextVersionIdMarker parameter as the markers for the next ListObjectVersions (GetBucketVersions) request. The values of NextKeyMarker and NextVersionIdMarker 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 value of the prefix parameter 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 in the directory.

By default, this header is left empty.

encoding-type

String

No

URL

The encoding type of the content to return.

By default, this header is left empty.

Valid value: URL

Important

The values of delimiter, marker, prefix, NextMarker, and Key are UTF-8 encoded. If the value of delimiter, marker, prefix, NextMarker, or Key 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 parameters

Parameter

Type

Example

Description

ListVersionsResult

Container

N/A

The container that stores the results of the ListObjectVersions (GetBucketVersions) 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 parameter. Objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result parameter in CommonPrefixes.

Parent nodes: ListVersionsResult

Delimiter

String

/

The character that is used to group objects by name. The objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result parameter 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 values of Delimiter, Marker, Prefix, NextMarker, and Key are encoded in the response.

Parent nodes: ListVersionsResult

IsTruncated

String

true

Indicates whether the returned results are truncated.

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

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

Valid values: true and false

Parent nodes: ListVersionsResult

KeyMarker

String

example

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

Parent nodes: ListVersionsResult

VersionIdMarker

String

CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****

The version from which the ListObjectVersions (GetBucketVersions) operation starts. This parameter is used together with KeyMarker.

Parent nodes: ListVersionsResult

NextKeyMarker

String

test

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

Parent nodes: ListVersionsResult

NextVersionIdMarker

String

CAEQGBiBgIC_jq7P9xYiIDRiZWJkNjY2Y2Q4NDQ5ZTI5ZGE5ODIxMTIyZThl****

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

Parent nodes: ListVersionsResult

MaxKeys

String

1000

The maximum number of objects that can be returned 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 information about the bucket owner.

Parent nodes: ListVersionsResult

Prefix

String

fun

The prefix contained in the names of the returned 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 that is 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 time when the returned objects were last modified.

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="Thu, 24 Sep 2020 12:40:33 GMT". In the 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 included in the response of a ListObjectVersions (GetBucketVersions) 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-oss-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 that 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 Cold Archive objects: exampleobject1.txt, exampleobject2.txt, and exampleobject3.txt. The three objects are in the following 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 and the object is being restored.

    • A RestoreObject request is sent to restore exampleobject3.txt and the object is restored.

    Sample request

    GET / HTTP/1.1
    Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otf****:DNrnx7xHk3sgysx7I8U9I9IY****

    Sample response

    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>

OSS SDKs

You can use OSS SDKs for the following programming languages to call the ListObjectVersions (GetBucketVersions) 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 max-keys value is less than 0 or greater than 1,000.

  • The length of the value of prefix, marker, or delimiter is invalid.