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¶
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.
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 | Specifies the maximum number (from 1 to 1000) of objects returned (in alphabetical order) in the response. If the value is beyond this range, 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 Value options: true, false | No |
Request Headers¶
This request uses common request headers. For details, see Table 3.
Request Elements¶
This request contains no elements.
Response Syntax¶
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListBucketResult xmlns="http://obs.otc.t-systems.com/doc/2016-01-01/">
<Name>bucket_name</Name>
<Prefix></Prefix>
<KeyCount>1</KeyCount>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>object_name</Key>
<LastModified>2022-11-11T11:11:11.111Z</LastModified>
<ETag>"37f80ab36f7c19abe8250e5e00123456"</ETag>
<Size>55555</Size>
<StorageClass>STANDARD</StorageClass>
</Contents>
</ListBucketResult>
Response Headers¶
The response to the request uses common headers. For details, see Table 1.
Response Elements¶
This response lists objects in XML format. Specific elements are described in Table 2.
Element | Description |
|---|---|
ListBucketResult | A list of objects in a bucket Type: XML |
Contents | Object metadata Type: XML Parent: ListBucketResult |
CommonPrefixes | Group information. If you specify a delimiter in the request, the response contains group information in CommonPrefixes. Type: XML Parent: ListBucketResult |
ContinuationToken | Parameter ContinuationToken specified in a request Type: string Parent: ListBucketResult |
KeyCount | Number of objects returned Type: integer Parent: ListBucketResult |
NextContinuationToken | ContinuationToken is returned when not all the objects are listed. The next list requests can be continued with this ContinuationToken. Type: string Parent: ListVersionsResult |
StartAfter | Parameter StartAfter specified in a request |
Delimiter | Parameter delimiter specified in a request Type: string Parent: 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 Parent: ListBucketResult.Contents |
Type | Object type. This parameter is returned when the object type is not Normal. Type: string Parent: ListBucketResult.Contents |
ID | Tenant ID of the object owner Type: string Parent: 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 Parent: ListBucketResult |
Key | Object name Type: string Parent: ListBucketResult.Contents |
LastModified | Time (UTC) when an object was last modified Type: date Parent: ListBucketResult.Contents |
MaxKeys | Maximum number of objects returned Type: string Parent: ListBucketResult |
Name | Name of the requested bucket Type: string Parent: ListBucketResult |
Owner | User information, including the domain ID and username Type: XML Parent: ListBucketResult.Contents |
Prefix | Prefix of an object name. Only objects whose names have this prefix are listed. Type: string Parent: ListBucketResult |
Size | Object size in bytes Type: string Parent: ListBucketResult.Contents |
StorageClass | Storage class of an object Type: string Value options: STANDARD, WARM, COLD Parent: ListBucketResult.Contents |
Error Responses¶
No special error responses are returned. For details about error responses, see Table 2.
Sample Request¶
List all objects.
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¶
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>