Lists information about all objects in a bucket.
Usage notes
- The ListObjects (GetBucket) operation is updated to ListObjectsV2 (GetBucketV2). We recommend that you use the ListObjectsV2 (GetBucketV2) operation to develop applications. To provide backward compatibility, Object Storage Service (OSS) continues to support the ListObjects (GetBucket) operation. For more information about the ListObjectsV2 (GetBucketV2) operation, see GetBucketV2 (ListObjectsV2).
- 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 ListObjects (GetBucket) 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 ListObjects (GetBucket) operation. For more information, see API operation calling fees.
Request syntax
GET / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Request headers
A ListObjects (GetBucket) request contains only common request headers such as Authorization
and Host
. For more information about common request headers, see Common request headers.
Request parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
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 CommonPrefixes.
By default, this header is left empty. |
marker | String | No | test1.txt | The name of the object after which the ListObjects (GetBucket) operation starts. If
this parameter is specified, objects whose names are alphabetically greater than the
marker value are returned.
The marker parameter is used to list the returned objects by page, and the marker value must be smaller than 1,024 bytes in length. Even if the specified marker does not exist in the list during a conditional query, the list starts from the object whose name is alphabetically greater than the marker value. By default, this header is left empty. |
max-keys | String | No | 200 | The maximum number of objects that you want to return. If the list operation cannot
be complete at a time because the max-keys parameter is specified, the NextMarker
element is included in the response as the marker for the next list operation.
Valid values: 1 to 1000 Default value: 100 |
prefix | String | No | fun | 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. By default, this header is left empty. |
encoding-type | String | No | URL | The encoding type of the content in the response.
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 the encoding-type parameter
to encode the value in the response.
|
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 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 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 the encoding-type
parameter in the request, the following parameters in the response are encoded: Delimiter,
Marker, Prefix, NextMarker, and Key.
Parent nodes: ListBucketResult |
DisplayName | String | user_example | The name of the object owner.
Parent nodes: Owner |
ETag | String | 5B3C1A2E053D763E1B002CC607C5A0FE1**** | The entity tag (ETag). An ETag is created when an object is created to identify the
content of the object.
Parent nodes: Contents |
ID | String | 0022012**** | The user ID of the bucket owner.
Parent nodes: 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: Contents |
LastModified | Time | 2012-02-24T08:42:32.000Z | The time when the returned objects were last modified.
Parent nodes: Contents |
ListBucketResult | Container | N/A | The container that stores the result of the ListObjects (GetBucket) request.
Child nodes: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, NextMarker, and Contents Parent node: none |
Marker | String | test1.txt | The name of the object after which the ListObjects (GetBucket) operation starts.
Parent nodes: ListBucketResult |
MaxKeys | String | 100 | The maximum number of returned objects in the response.
Parent nodes: ListBucketResult |
Name | String | oss-example | 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: Contents |
StorageClass | String | Standard | The storage class of the object.
Parent nodes: Contents |
RestoreInfo | String | ongoing-request="true" | The restoration status of the object.
Parent nodes: Contents |
For more information about the common response headers such as x-oss-request-id
and Content-Type
included in the response to a ListObjects (GetBucket) request, see Common response headers.
Examples
- Sample requests for the simple ListObjects (GetBucket) operation
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: 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>100</MaxKeys> <Delimiter></Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>fun/movie/001.avi</Key> <LastModified>2012-02-24T08:43:07.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> <Contents> <Key>fun/movie/007.avi</Key> <LastModified>2012-02-24T08:43:27.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> <Contents> <Key>fun/test.jpg</Key> <LastModified>2012-02-24T08:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> <Contents> <Key>oss.jpg</Key> <LastModified>2012-02-24T06:07:48.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> </ListBucketResult>
- Sample requests that have the prefix parameter specified
GET /?prefix=fun 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>fun</Prefix> <Marker></Marker> <MaxKeys>100</MaxKeys> <Delimiter></Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>fun/movie/001.avi</Key> <LastModified>2012-02-24T08:43:07.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user_example</DisplayName> </Owner> </Contents> <Contents> <Key>fun/movie/007.avi</Key> <LastModified>2012-02-24T08:43:27.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user_example</DisplayName> </Owner> </Contents> <Contents> <Key>fun/test.jpg</Key> <LastModified>2012-02-24T08:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user_example</DisplayName> </Owner> </Contents> </ListBucketResult>
- Sample requests that have the prefix and delimiter parameters specified
GET /?prefix=fun/&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>fun/</Prefix> <Marker></Marker> <MaxKeys>100</MaxKeys> <Delimiter>/</Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>fun/test.jpg</Key> <LastModified>2012-02-24T08:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user_example</DisplayName> </Owner> </Contents> <CommonPrefixes> <Prefix>fun/movie/</Prefix> </CommonPrefixes> </ListBucketResult>
- Sample requests that have the marker parameter specified
In this example, the max-keys parameter is set to 2, which indicates that the maximum number of objects to return is 2.
GET /?max-keys=2&marker=test1.txt HTTP/1.1 Host: examplebucket.oss-cn-shenzhen.aliyuncs.com Accept-Encoding: identity Accept: */* Connection: keep-alive User-Agent: aliyun-sdk-python/2.11.0(Darwin/18.2.0/x86_64;3.4.1) date: Tue, 26 May 2020 08:39:48 GMT authorization: OSS LTAIB1VW9VqPS****:MmY11jLlO8UlAqjqHK3Ckp****
Sample responses
The NextMarker element in the response indicates the marker for the next list operation.
HTTP/1.1 200 OK Server: AliyunOSS Date: Tue, 26 May 2020 08:39:48 GMT Content-Type: application/xml Content-Length: 1032 Connection: keep-alive x-oss-request-id: 5ECCD5D4881816373582xxx x-oss-server-time: 3 <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult> <Name>examplebucket</Name> <Prefix></Prefix> <Marker>test1.txt</Marker> <MaxKeys>2</MaxKeys> <Delimiter></Delimiter> <EncodingType>url</EncodingType> <IsTruncated>true</IsTruncated> <NextMarker>test100.txt</NextMarker> <Contents> <Key>test10.txt</Key> <LastModified>2020-05-26T07:50:18.000Z</LastModified> <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag> <Type>Normal</Type> <Size>1</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>1305433xxx</ID> <DisplayName>1305433xxx</DisplayName> </Owner> </Contents> <Contents> <Key>test100.txt</Key> <LastModified>2020-05-26T07:50:20.000Z</LastModified> <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag> <Type>Normal</Type> <Size>1</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>1305433xxx</ID> <DisplayName>1305433xxx</DisplayName> </Owner> </Contents> </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>
OSS SDKs
You can use OSS SDKs for the following programming languages to call the ListObjects (GetBucket) 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 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 |
|
FAQ
Can I filter response parameters when I call the ListObjects (GetBucket) operation?
No. By default, all response parameters are returned when you call the ListObjects (GetBucket) operation. You cannot specify a response parameter as a filter condition. For example, only objects whose storage class is Infrequent Access (IA) cannot be returned.