ListObjectsV2--Torch Object Storage-Volcengine

Docs

Torch Object Storage

Basic Bucket Operations

ListObjectsV2

Function description

Call the ListObjectsV2 API to list objects in a bucket.

tip

Compared with ListObjects, ListObjectsV2 is an upgraded API with more comprehensive parameters and resolves the timeout issues present in ListObjects.

Precautions

Calling this API requires read access permission to the bucket.
A single bucket request returns up to 1,000 objects. You can use the max-keys parameter to set the number of objects returned.

Request syntax

GET /?list-type=2 HTTP/1.1 
Host: bucketname.tos-cn-beijing.volces.com 
Date: GMT Date 
Authorization: authorization string

Request parameters and headers

Use the public request header, see Common parameters for more information.

Name	Location	Type	Required	Sample Value	Description
list-type	Query	Integer	Yes	2	The value 2 means using the ListObjectsV2 interface to list objects in the bucket.
delimiter	Query	String	No	-	Set the character for grouping object names. The forward slash (/) is usually used as the grouping character.
encoding-type	Query	String	No	url	Specify the encoding type for the returned content. The options are as follows: url: Perform URLEncode following the application/x-www-form-urlencoded standard.
max-keys	Query	Integer	No	100	Set the maximum number of returned objects. The maximum value is 1000, meaning up to 1000 objects can be returned per request.
prefix	Query	String	No	abc	List objects with the specified prefix.
start-after	Query	String	No	test.txt	Specify the starting position of the objects listed. You can paginate the object listing by specifying the starting position of the objects.
fetch-owner	Query	Bool	No	false	Whether to return object owner information, values are as follows: true: return object owner information. false: do not return object owner information, default is false.
continuation-token	Query	String	No	whvFnl2rE5vm9cWvQScxwTuNm0***	Specify to start the listing operation from this token, usually obtained from NextContinuationToken returned in the previous request.

Request body elements

There is no request message element in this request.

Response headers

Return the common response message headers. For more information, see common parameters.

Response body elements

Name	Type	Sample Value	Description
Name	String	test-bucket	Bucket name.
Prefix	String	abc	The prefix parameter included in the request.
Marker	String	abc	The marker parameter included in the request.
MaxKeys	Integer	100	The max-keys parameter included in the request.
Delimiter	String	d	The delimiter parameter passed in the request.
EncodingType	String	url	The encoding-type parameter passed in the request.
IsTruncated	Bool	true	Whether the returned result is truncated, the values are as follows: false: all results have been returned. true: there are still results not returned.
StartAfter	String	abcd	If the start-after parameter is specified in the request, the response will include the StartAfter element.
ContinuationToken	String	whvFnl2rE5vm9cWvQScxwTuv***	If the request includes the continuation-token parameter, the response contains the ContinuationToken element.
NextContinuationToken	String	whvFnl2rE5vm9cWvQSg0xfckv***	When IsTruncated is true, NextContinuationToken is returned, indicating more data can be listed. The next listing request can use NextContinuationToken to continue listing. NextContinuationToken value is not a valid object name.
CommonPrefixes	Array	[{"Prefix": "abcd"}]	When the request includes the delimiter parameter, the response contains the CommonPrefixes group information. This element identifies names ending with delimiter and lists common prefixes of objects.
Contents	Array	-	List object information. Contents is the root node for the parameters Key, LastModified, ETag, Size, StorageClass, Type, HashCrc64ecma, and Owner.
Key	String	abcde	Object name.
LastModified	String	2024-06-06T07:15:20.000Z	Last modification time of the object.
ETag	String	"32185e15494ca8e0eedf12bd218787f6"	Tag generated when each object is created, used to uniquely identify an object.
Size	Integer	4813	Object size.
StorageClass	String	STANDARD	Object storage types,For detailed information, please refer to Storage type.
Type	String	Appendable	If the object is not a Normal object, it returns this element. The value description is as follows: Appendable: This object is uploaded with the append-write interface. Symlink: This object is a symbolic link. The parent node is Contents.
HashCrc64ecma	String	2217460101204276403	Represents the 64-bit CRC value of the object. This value is calculated according to the ECMA-182 standard. If the object was created before the TOS server supported 64-bit CRC checks, this message header will not appear in the response.
Owner	Object	-	List information about the object owner. Owner is the root node for the parameters ID and DisplayName.
ID	String	1234567890	Account ID.
DisplayName	String	test-owner-name	Account name.

Sample request

GET /?list-type=2 HTTP/1.1 
Host: bucketname.tos-cn-beijing.volces.com 
Date: Fri, 30 Jul 2021 08:05:36 GMT 
Authorization: authorization string

Sample response

HTTP/1.1 200 OK 
x-tos-id-2: dc13a2093d620014-a444ed0 
x-tos-request-id: dc13a2093d620014-a444ed0 
Date: Fri, 30 Jul 2021 06:45:39 GMT 
server: TosServer 
Content-Length: 622 

{ 
    "Name": "bucketName", 
    "Prefix": "", 
    "Marker": "", 
    "MaxKeys": 1000, 
    "IsTruncated": false, 
    "Contents": [ 
        { 
            "Key": "obj1", 
            "LastModified": "2021-08-20T03:10:02.000Z", 
            "ETag": ""8a36be0d764367db4eea2deb16b71543"", 
            "Size": 109, 
            "StorageClass": "STANDARD" 
        }, 
        { 
            "Key": "obj2", 
            "LastModified": "2021-08-20T03:10:06.000Z", 
            "ETag": ""8a36be0d764367db4eea2deb16b71543"", 
            "Size": 109, 
            "StorageClass": "STANDARD" 
        }, 
        { 
            "Key": "obj3", 
            "LastModified": "2021-08-20T03:10:10.000Z", 
            "ETag": ""8a36be0d764367db4eea2deb16b71543"", 
            "Size": 109, 
            "StorageClass": "STANDARD" 
        } 
    ] 
}

Last updated: 2025.06.30 17:27:07

Torch Object Storage

Function description #

Precautions #

Request syntax #

Request parameters and headers #

Request body elements #

Response headers #

Response body elements #

Sample request #

Sample response #