ListObjectsV2 (GetBucketV2) - Object Storage Service - Alibaba Cloud Documentation Center

Queries information about all objects in a bucket.

Usage notes

To list information about all objects in a bucket, you must have the oss:ListObjects permission.
The user metadata of objects is not returned for ListObjectsV2 (GetBucketV2) requests.
If you have enabled Logging and Real-time log query, the operation field in the access logs generated by calling the ListObjects (GetBucket) operation 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	Number	Yes	2	The version of the ListObjectsV2 (GetBucketV2) operation. Set the value to 2.
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 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 after which the ListObjectsV2 (GetBucketV2) operation starts. The objects are returned in alphabetical order of their names. 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 greater than 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 must start. You can obtain the token from the NextContinuationToken parameter in the ListObjectsV2 (GetBucketV2) response.
max-keys	String	No	100	The maximum number of objects that you want to return. Valid values: 1 to 1000 Default value: 100 Note If the number of objects exceeds the value of the max-keys parameter, the response includes `<NextContinuationToken>` as the continuation 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, which includes 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 by default. If you specify a prefix to query objects, the names of the returned objects still 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 information about the object owner. false: The response does not include information about the object owner. Default value: false

Response parameters


Parameter	Type	Example	Description
Contents	Container	N/A	The container that stores the returned object metadata. 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 object name 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.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 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. The ETag value of an object can be used to check whether the object content is modified. However, we recommend that you use the MD5 hash of an object to check data integrity.
ID	String	0022012****	The ID of the bucket owner. Parent nodes: ListBucketResult.Contents.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 at this time. false indicates that all results are returned at 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 time when the object was last modified. 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 StartAfter 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 names of the returned objects. Parent nodes: ListBucketResult
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 ContinuationToken parameter is specified in the request, the response contains the ContinuationToken parameter.
KeyCount	Number	6	The number of objects 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 NextContinuationToken value is used as the ContinuationToken value 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="Thr, 24 Mon 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 requests for simple ListObjectsV2 (GetBucketV2) operations

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 responses

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 have 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 responses

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 have 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 responses

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 have the StartAfter, MaxKeys, and FetchOwner 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 responses

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 requests that are 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 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: 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="Thr, 24 Mon 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 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 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 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 value of prefix, marker, or delimiter is invalid.