GET Bucket V2 (List Objects V2)¶
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: number | 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 1,000. 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. 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 |
encoding-type | Encodes some elements in the response based on the specified type. If Delimiter, Marker (or KeyMarker), Prefix, NextMarker (or NextKeyMarker), and Key contain control characters that are not supported by XML 1.0 standards, you can configure encoding-type to encode Delimiter, Marker (or KeyMarker), Prefix (including the Prefix in CommonPrefixes), NextMarker (or NextKeyMarker), and Key in the response. Type: string Optional value: url | 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 headers. For details about common request headers, see section Common Request Headers.
Request Elements¶
This request involves no elements.
Response Syntax¶
HTTP/1.1 status_code
Date: date
x-amz-bucket-location: region
Content-Type: application/xml
Content-Length: length
<Response Body>
Response Headers¶
This response uses common headers. For details about common response headers, see section Common Response Headers.
Response Elements¶
This response lists objects in the 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 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: number 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 |
EncodingType | Encodes some elements in the response based on the specified type. If encoding-type is specified in the request, Delimiter, Marker, Prefix (including the Prefix in CommonPrefixes), NextMarker, and Key in the response will be encoded. 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 only to the object content, rather than its 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. true: Not all results are returned. false: All results have been returned. 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: enumeration Valid value: STANDARD | WARM | COLD Ancestor: ListBucketResult.Contents |
Error Responses¶
No special error responses are returned. For details about error responses, see Table 1.
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: AWS 04RZT432N80TGDF2Y2G2:QaTwEcRs5E4p/uahBMYHB+dY00k=
Sample Response¶
HTTP/1.1 200 OK
Server: OBS
x-amz-request-id: BF260000016435D34E379ABD93320CB9
x-amz-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>