doc-exports/docs/obs/api-ref/obs_04_0160.html

Listing Objects in a Bucket (V2)

Functions

This operation lists objects in a bucket. To use this operation, you must have the permission to read the bucket.

If the bucket name is specified in a request URI and list-type is explicitly set to 2, that is, GET /?list-type is set to 2, descriptions of some or all objects in the bucket is returned in the format of the V2 API. Information about a maximum of 1000 objects can be returned at a time. If one or more of the prefix, encoding-type, max-keys, delimiter, fetch-owner, start-after, and continuation-token parameters are also specified, the specified objects are returned based on the syntax described in Table 1.

Request Syntax

1 2 3 4

GET /?list-type=2 HTTP/1.1 Host: bucketname.obs.region.example.com Date: date Authorization: authorization

Request Parameters

This request uses parameters to list some objects in a bucket. Specific parameters are described in the following table.

Table 1 Request parameters

Parameter	Description	Mandatory
list-type	It can be set to 2 only, indicating that the ListObjectV2 API is used. Type: integer	Yes
prefix	Lists objects that begin with the specified prefix. Type: string	No
start-after	Specifies a marker when listing objects in a bucket. With a marker configured, objects after this marker will be returned in alphabetical order. Type: string	No
max-keys	Sets the maximum number of objects returned (in alphabetical order) in the response. The value ranges from 1 to 1000. If there are over 1,000 objects, only 1,000 objects are returned by default. Type: integer	No
delimiter	Separator used to group object names. If a prefix is specified, objects with the same string from the prefix to the first delimiter are grouped into one CommonPrefixes. If no prefix is specified, objects with the same string from the first character to the first delimiter are grouped into one CommonPrefixes. For example, there are three objects (abcd, abcde, and bbcde) in a bucket. If delimiter is set to d and prefix is set to a, objects abcd and abcde are grouped into a CommonPrefixes with abcd as the prefix. If only delimiter is set to d, objects abcd and abcde are grouped into a CommonPrefixes with abcd as the prefix, and bbcde is grouped separately into another CommonPrefixes with bbcd as the prefix. For a parallel file system, if this parameter is not specified, all the content in the directory is recursively listed by default, and subdirectories are also listed. In big data scenarios, parallel file systems usually have deep directory levels and each directory has a large number of files. In such case, you are advised to configure [delimiter=/] to list the content in the current directory, but not list subdirectories, thereby improving the listing efficiency. Type: string	No
continuation-token	Specifies the token after which objects are returned in alphabetical order. Type: string Valid value: value of NextContinuationToken in the response body of the last request	No
fetch-owner	Specifies whether to return the object owner information. Type: boolean Optional value: true or false	No

Request Headers

This request uses common request headers. For details, see Table 3.

Request Elements

This request contains no elements.

Response Syntax

1 2 3 4 5 6

HTTP/1.1 status_code Date: date x-obs-bucket-location: region Content-Type: application/xml Content-Length: length <Response Body>

Response Headers

The response to the request uses common headers. For details, see Table 1.

Response Elements

This response lists objects in the XML format. Specific elements are described in Table 2.

Table 2 Response elements

Element	Description
ListBucketResult	A list of objects in a bucket Type: XML
Contents	Object metadata Type: XML Ancestor: ListBucketResult
CommonPrefixes	Group information. If you specify a delimiter in the request, the response contains group information in CommonPrefixes. Type: XML Ancestor: ListBucketResult
ContinuationToken	Parameter ContinuationToken specified in a request Type: string Ancestor: ListBucketResult
KeyCount	Number of objects returned Type: integer Ancestor: ListBucketResult
NextContinuationToken	ContinuationToken is returned when not all the objects are listed. The next list requests can be continued with this ContinuationToken. Type: string Ancestor: ListVersionsResult
StartAfter	Parameter StartAfter specified in a request
Delimiter	Parameter delimiter specified in a request Type: string Ancestor: ListBucketResult
ETag	Base64-encoded 128-bit MD5 digest of an object. ETag is the unique identifier of the object content. It can be used to determine whether the object content is changed. For example, if the ETag value is A when an object is uploaded, but this value has changed to B when the object is downloaded, it indicates that the object content has been changed. The ETag value is a hash of the object. The ETag reflects changes to the object content, rather than the object metadata. An uploaded object or copied object has a unique ETag after being encrypted using MD5. (If the object is encrypted on the server side, the ETag value is not the MD5 digest of the object, but the unique identifier calculated through server-side encryption.) Type: string Ancestor: ListBucketResult.Contents
Type	Object type. This parameter is returned when the object type is not Normal. Type: string Ancestor: ListBucketResult.Contents
ID	Tenant ID of the object owner Type: string Ancestor: ListBucketResult.Contents.Owner
IsTruncated	Determines whether the returned list of objects is truncated. The value true indicates that the list was truncated and false indicates that the list was not truncated. Type: boolean Ancestor: ListBucketResult
Key	Object name Type: string Ancestor: ListBucketResult.Contents
LastModified	Time (UTC) when an object was last modified Type: date Ancestor: ListBucketResult.Contents
MaxKeys	Maximum number of objects returned Type: string Ancestor: ListBucketResult
Name	Name of the requested bucket Type: string Ancestor: ListBucketResult
Owner	User information, including the domain ID and username Type: XML Ancestor: ListBucketResult.Contents
Prefix	Prefix of an object name. Only objects whose names have this prefix are listed. Type: string Ancestor: ListBucketResult
Size	Object size in bytes Type: string Ancestor: ListBucketResult.Contents
StorageClass	Storage class of an object Type: string Value options: STANDARD, WARM, COLD Ancestor: ListBucketResult.Contents

Error Responses

No special error responses are returned. For details about error responses, see Table 2.

Sample Request

List all objects.

1 2 3 4 5 6

GET /?list-type=2 HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.region.example.com Accept: */* Date: WED, 01 Jul 2015 02:28:25 GMT Authorization: OBS H4IPJX0TQTHTHEBQQCEC:KiyoYze4pmRNPYfmlXBfRTVxt8c=

Sample Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

HTTP/1.1 200 OK Server: OBS x-obs-request-id: BF260000016435D34E379ABD93320CB9 x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSXiN7GPL/yXM6OSBaYCUV1zcY5OelWp Content-Type: application/xml Date: WED, 01 Jul 2015 02:23:30 GMT Content-Length: 586 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ListBucketResult xmlns="http://obs.example.com/doc/2015-06-30/"> <Name>name</Name> <Prefix/> <KeyCount>1</KeyCount> <MaxKeys>1000</MaxKeys> <IsTruncated>false</IsTruncated> <Contents> <Key>obj</Key> <LastModified>2021-11-08T11:03:04.236Z</LastModified> <ETag>"42648685023dcae595357d91a0936104"</ETag> <Size>4939</Size> <StorageClass>STANDARD</StorageClass> </Contents> </ListBucketResult>

Parent topic: Operations on Buckets