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 API operation calling fees for 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
|
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
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
Default value: false |
Response parameters
Parameter | Type | Example | Description |
Contents | Container | N/A | The container that stores the metadata of each 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 Child nodes: Prefix |
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
|
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
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: ListBucketResult.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. Parent nodes: ListBucketResult |
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. Parent nodes: ListBucketResult |
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. Parent nodes: ListBucketResult |
RestoreInfo | String | ongoing-request="true" | The restoration status of the object.
Parent nodes: ListBucketResult.Contents |
Examples
Sample request for the simple ListObjects (GetBucket) 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 qn6q**************:77Dv****************
Sample success 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 qn6q**************:77Dv****************
Sample success 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 qn6q**************:77Dv****************
Sample success 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 qn6q**************:77Dv****************
Sample success 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 lists all objects in a bucket, including Archive or Cold Archive objects
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 have expired.
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 qn6q**************:77Dv****************
Sample success 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 are granted the |
InvalidArgument | 400 |
|