Queries the information about all objects in a bucket.
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 GetBucketV2 (ListObjectsV2) 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 element. 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 CommonPrefixes.
Default value: null |
start-after | String | No | b | The name of the object after which the list 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 list starts from the object whose name is alphabetically greater than the start-after value. Default value: null |
continuation-token | String | No | test1.txt | The token from which the list operation must start. You can obtain the token from NextContinuationToken in the GetBucketV2 (ListObjectsV2) response. |
max-keys | String | No | 100 | The maximum number of objects to return.
Valid values: 1 to 1000 Default value: 100 Note If the number of objects exceeds the value of max-keys, 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 within the directory are returned in the CommonPrefixes element. However, objects and directories within the subdirectories are not listed. For example, a bucket contains the following three 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
Default value: null |
encoding-type | String | No | url | The encoding type of the content in the response.
Default value: null 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 the 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 the returned objects.
Parent nodes: ListBucketResult |
CommonPrefixes | String | N/A | If the Delimiter parameter is specified in the request, the response contains the
CommonPrefixes element. 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
CommonPrefixes.
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 CommonPrefixes.
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.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 user 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
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 GetBucketV2 (ListObjectsV2) 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 element. |
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 the 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 element. |
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 list 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.
|
Examples
- Sample request
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 responseHTTP/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 responseHTTP/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 responseHTTP/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 responseHTTP/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 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: 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 are not authorized to access the bucket. Only
the bucket owner and RAM users who are granted the oss:ListObjects permission can access the bucket.
|
InvalidArgument | 400 |
|