All Products
Search
Document Center

Object Storage Service:ListObjectsV2 (GetBucketV2)

Last Updated:Dec 18, 2023

Lists all objects in a bucket.

Usage notes

  • To list all objects in a bucket, you must have the oss:ListObjects permission.

  • The ListObjectsV2 (GetBucketV2) operation does not return user metadata of objects.

  • If logging or real-time log query is enabled for the bucket on which you call the ListObjectsV2 (GetBucketV2) operation, the value of the operation field in the access log for the call is GetBucket.

  • You are charged based on the number of PUT requests when you call the ListObjectsV2 (GetBucketV2) operation. For more information, see PUT requests.

Request syntax

GET /?list-type=2 HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request parameters

Parameter

Type

Required

Example

Description

list-type

Numeric

Yes

2

The version of the ListObjectsV2 (GetBucketV2) operation. Set the value to 2.

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. The 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 the CommonPrefixes parameter.

By default, this parameter is left empty.

start-after

String

No

b

The name of the object from which the list operation starts. If this parameter is specified, objects whose names are alphabetically after the value of the start-after parameter are returned.

The start-after parameter is used to list the returned objects by page. The value of the parameter must be less than 1,024 bytes in length.

Even if the specified start-after value does not exist during a conditional query, the ListObjectsV2 (GetBucketV2) operation starts from the object whose name is alphabetically after the start-after value.

By default, this parameter is left empty.

continuation-token

String

No

test1.txt

The token from which the ListObjectsV2 (GetBucketV2) operation starts. You can obtain the token from the NextContinuationToken parameter in the response to the ListObjectsV2 (GetBucketV2) operation.

max-keys

String

No

100

The maximum number of objects that can be returned.

Valid values: 1 to 1000

Default value: 100

Note

If an operation call does not return all matching objects in the bucket due to the max-keys configuration, the response includes the NextContinuationToken parameter, which you can use as the token for the next list operation.

prefix

String

No

a

The prefix that the names of the returned objects must contain.

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

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

For example, a bucket contains the following objects: fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi. If prefix is set to fun/, the three objects are returned. If prefix is set to fun/ and delimiter is set to a forward slash (/), fun/test.jpg and fun/movie/ are returned.

Note
  • The value of prefix must be less than 1,024 bytes in length.

  • The value of the prefix parameter cannot start with a forward slash (/). If you leave the prefix parameter empty, all objects in the bucket are listed.

  • If you specify a prefix, the names of the returned objects contain the prefix.

By default, this parameter is left empty.

encoding-type

String

No

url

The encoding type of the content in the response.

By default, this parameter is left empty.

Valid value: url.

Note

The delimiter, start-after, prefix, NextContinuationToken, and Key values are encoded in UTF-8. If the delimiter, start-after, prefix, NextContinuationToken, or Key value contains control characters that are not supported by the XML 1.0 standard, you can specify encoding-type to encode the value in the response.

fetch-owner

Boolean

No

false

Specifies whether to include information about the object owner in the response.

Valid values: true and false

  • true: The response includes the object owner information.

  • false: The response does not include the object owner information.

Default value: false

Response parameters

Parameter

Type

Example

Description

Contents

Container

N/A

The container that stores the metadata of the returned object.

Parent nodes: ListBucketResult

CommonPrefixes

String

N/A

If the delimiter parameter is specified in the request, the response contains the CommonPrefixes parameter. The 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 the CommonPrefixes parameter.

Parent nodes: ListBucketResult

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 element in the CommonPrefixes parameter.

Parent nodes: ListBucketResult

EncodingType

String

N/A

The encoding type of the content in the response. If you specify encoding-type in the request, the values of Delimiter, StartAfter, Prefix, NextContinuationToken, and Key are encoded in the response.

Parent nodes: ListBucketResult

DisplayName

String

user_example

The name of the object owner.

Parent nodes: ListBucketResult, Contents, and Owner

ETag

String

5B3C1A2E053D763E1B002CC607C5A0FE1****

The entity tag (ETag). When an object is created, an ETag is created to identify the content of the object.

Parent nodes: ListBucketResult.Contents

  • For an object that is created by calling the PutObject operation, the ETag value of the object is the MD5 hash of the object content.

  • For an object that 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.

  • The ETag of an object can be used 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.

ID

String

0022012****

The ID of the bucket owner.

Parent nodes: ListBucketResult, Contents, and Owner

IsTruncated

Enumerated string

false

Indicates whether the returned results are truncated.

Valid values: true and false

  • true indicates that not all results are returned this time.

  • false indicates that all results are returned this time.

Parent nodes: ListBucketResult

Key

String

fun/test.jpg

The name of the object.

Parent nodes: ListBucketResult.Contents

LastModified

Time

2012-02-24T08:42:32.000Z

The last modified time of the object.

Parent nodes: ListBucketResult.Contents

ListBucketResult

Container

N/A

The container that stores the result of the ListObjectsV2 (GetBucketV2) request.

Child nodes: Name, Prefix, StartAfter, MaxKeys, Delimiter, IsTruncated, NextContinuationToken, and Contents

Parent nodes: none

StartAfter

String

test1.txt

If the start-after parameter is specified in the request, the response contains the StartAfter parameter.

MaxKeys

String

100

The maximum number of returned objects in the response.

Parent nodes: ListBucketResult

Name

String

examplebucket

The name of the bucket.

Parent nodes: ListBucketResult

Owner

Container

N/A

The container that stores information about the bucket owner.

Child nodes: DisplayName and ID

Parent nodes: Contents

Prefix

String

fun/

The prefix contained in the returned object names.

Parent nodes: ListBucketResult

Type

String

Normal

The type of the object.

Valid values: Normal, Multipart, Appendable, and Symlink.

Parent nodes: ListBucketResult.Contents

Size

String

344606

The size of the returned object. Unit: bytes.

Parent nodes: ListBucketResult.Contents

StorageClass

String

Standard

The storage class of the object.

Parent nodes: ListBucketResult.Contents

ContinuationToken

String

test1.txt

If the continuation-token parameter is specified in the request, the response contains the ContinuationToken parameter.

KeyCount

Numeric

6

The number of object names returned for this request. If delimiter is specified, KeyCount is the sum of the values of Key and CommonPrefixes.

NextContinuationToken

String

CgJiYw--

The name of the object from which the next ListObjectsV2 (GetBucketV2) operation starts. The value of the NextContinuationToken parameter is used to query subsequent results.

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.

Examples

  • Sample request for a simple ListObjectsV2 (GetBucketV2) operation

    GET /?list-type=2 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 response

    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906****
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Content-Type: application/xml
    Content-Length: 1866
    Connection: keep-alive
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
        <Name>examplebucket</Name>
        <Prefix></Prefix>
        <MaxKeys>100</MaxKeys>
        <EncodingType>url</EncodingType>
        <IsTruncated>false</IsTruncated>
        <Contents>
            <Key>a</Key>
            <LastModified>2020-05-18T05:45:43.000Z</LastModified>
            <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
            <Size>25</Size>
            <StorageClass>STANDARD</StorageClass>
        </Contents>
        <Contents>
            <Key>a/b</Key>
            <LastModified>2020-05-18T05:45:47.000Z</LastModified>
            <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
            <Size>25</Size>
            <StorageClass>STANDARD</StorageClass>
        </Contents>
        <Contents>
            <Key>b</Key>
            <LastModified>2020-05-18T05:45:50.000Z</LastModified>
            <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
            <Size>25</Size>
            <StorageClass>STANDARD</StorageClass>
        </Contents>
        <Contents>
            <Key>b/c</Key>
            <LastModified>2020-05-18T05:45:54.000Z</LastModified>
            <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
            <Size>25</Size>
            <StorageClass>STANDARD</StorageClass>
        </Contents>
        <Contents>
            <Key>bc</Key>
            <LastModified>2020-05-18T05:45:59.000Z</LastModified>
            <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
            <Size>25</Size>
            <StorageClass>STANDARD</StorageClass>
        </Contents>
        <Contents>
            <Key>c</Key>
            <LastModified>2020-05-18T05:45:57.000Z</LastModified>
            <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
            <Size>25</Size>
            <StorageClass>STANDARD</StorageClass>
        </Contents>
        <KeyCount>6</KeyCount>
    </ListBucketResult>
  • Sample request that has the prefix parameter specified

    GET /?list-type=2&prefix=a 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 response

    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906****
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Content-Type: application/xml
    Content-Length: 1464
    Connection: keep-alive
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
        <Name>examplebucket</Name>
        <Prefix>a</Prefix>
        <MaxKeys>100</MaxKeys>
        <EncodingType>url</EncodingType>
        <IsTruncated>false</IsTruncated>
        <Contents>
            <Key>a</Key>
            <LastModified>2020-05-18T05:45:43.000Z</LastModified>
            <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
            <Size>25</Size>
            <StorageClass>STANDARD</StorageClass>
        </Contents>
        <Contents>
            <Key>a/b</Key>
            <LastModified>2020-05-18T05:45:47.000Z</LastModified>
            <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
            <Size>25</Size>
            <StorageClass>STANDARD</StorageClass>
        </Contents>
        <KeyCount>2</KeyCount>
    </ListBucketResult>
  • Sample request that has the prefix and delimiter parameters specified

    GET /?list-type=2&prefix=a/&delimiter=/ HTTP/1.1
    Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:DNrnx7xHk3sgysx7I8U9I9IY****

    Sample response

    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906****
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Content-Type: application/xml
    Content-Length: 712
    Connection: keep-alive
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
        <Name>examplebucket</Name>
        <Prefix>a/</Prefix>
        <MaxKeys>100</MaxKeys>
        <Delimiter>/</Delimiter>
        <EncodingType>url</EncodingType>
        <IsTruncated>false</IsTruncated>
        <Contents>
            <Key>a/b</Key>
            <LastModified>2020-05-18T05:45:47.000Z</LastModified>
            <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
            <Size>25</Size>
            <StorageClass>STANDARD</StorageClass>
        </Contents>
        <CommonPrefixes>
            <Prefix>a/b/</Prefix>
        </CommonPrefixes>
        <KeyCount>2</KeyCount>
    </ListBucketResult>
  • Sample request that has the start-after, max-keys, and fetch-owner parameters specified

    GET /?list-type=2&start-after=b&max-keys=3&fetch-owner=true HTTP/1.1
    Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:DNrnx7xHk3sgysx7I8U9I9IY****

    Sample response

    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906****
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Content-Type: application/xml
    Content-Length: 712
    Connection: keep-alive
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
        <Name>examplebucket</Name>
        <Prefix></Prefix>
        <StartAfter>b</StartAfter>
        <MaxKeys>3</MaxKeys>
        <EncodingType>url</EncodingType>
        <IsTruncated>true</IsTruncated>
        <NextContinuationToken>CgJiYw--</NextContinuationToken>
        <Contents>
            <Key>b/c</Key>
            <LastModified>2020-05-18T05:45:54.000Z</LastModified>
            <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
            <Size>25</Size>
            <StorageClass>STANDARD</StorageClass>
            <Owner>
                <ID>1686240967192623</ID>
                <DisplayName>1686240967192623</DisplayName>
            </Owner>
        </Contents>
        <Contents>
            <Key>ba</Key>
            <LastModified>2020-05-18T11:17:58.000Z</LastModified>
            <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
            <Size>25</Size>
            <StorageClass>STANDARD</StorageClass>
            <Owner>
                <ID>1686240967192623</ID>
                <DisplayName>1686240967192623</DisplayName>
            </Owner>
        </Contents>
        <Contents>
            <Key>bc</Key>
            <LastModified>2020-05-18T05:45:59.000Z</LastModified>
            <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
            <Size>25</Size>
            <StorageClass>STANDARD</StorageClass>
            <Owner>
                <ID>1686240967192623</ID>
                <DisplayName>1686240967192623</DisplayName>
            </Owner>
        </Contents>
        <KeyCount>3</KeyCount>
    </ListBucketResult>
  • Sample request that is sent to list all objects, including Archive or Cold Archive objects in a 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: 534B371674E88A4D8906****
    Date: Date: Fri, 24 Feb 2012 08:43:27 GMT
    Content-Type: application/xml
    Content-Length: 1866
    Connection: keep-alive
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
      <Name>examplebucket</Name>
      <Prefix></Prefix>
      <Marker></Marker>
      <MaxKeys></MaxKeys>
      <Delimiter></Delimiter>
      <IsTruncated>false</IsTruncated>
      <Contents>
            <Key>exampleobject1.txt</Key>
            <LastModified>2020-06-22T11:42:32.000Z</LastModified>
            <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>ColdArchive</StorageClass>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user-example</DisplayName>
            </Owner>
      </Contents>
      <Contents>
            <Key>exampleobject2.txt</Key>
            <LastModified>2020-06-22T11:42:32.000Z</LastModified>
            <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>Standard</StorageClass>
            <RestoreInfo>ongoing-request="true"</RestoreInfo>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user-example</DisplayName>
            </Owner>
      </Contents>
      <Contents>
            <Key>exampleobject3.txt</Key>
            <LastModified>2020-06-22T11:42:32.000Z</LastModified>
            <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>Standard</StorageClass>
            <RestoreInfo>ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"</RestoreInfo>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user-example</DisplayName>
            </Owner>
      </Contents>
    </ListBucketResult>

Error code

HTTP status code

Description

NoSuchBucket

404

The requested bucket does not exist. Check whether the name of the requested bucket complies with the naming rules.

AccessDenied

403

You do not have the permissions to access the bucket. Only the bucket owner and RAM users who have the oss:ListObjects 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.