ListObjectsV2--对象存储-火山引擎

文档中心

立即注册

导航

对象存储

ListObjectsV2

最近更新时间：2025.01.07 10:14:00首次发布时间：2023.04.13 14:38:22

功能描述

调用 ListObjectsV2 接口列举桶中的对象。

说明

相比 ListObjects ，ListObjectsV2 是一个升级版本的接口，调用参数更全面，优化了 ListObjects 存在的超时问题。

注意事项

调用此接口，您需要拥有存储桶的读访问权限。
单次请求存储桶，最多返回的 1000 个对象。您可以使用 max-keys 参数设置返回对象的数量。

请求消息样式

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

请求参数和消息头

使用公共请求消息头，更多信息，请参见公共参数。

参数名称	位置	参数类型	是否必选	示例值	说明
list-type	Query	Integer	是	2	取值为 `2`，表示使用 ListObjectsV2 接口列举桶中的对象。
delimiter	Query	String	否	-	设置对对象名称进行分组的字符。通常使用正斜线（/）作为分组字符。
encoding-type	Query	String	否	url	指定对返回的内容进行编码的编码类型，取值说明如下： `url`：进行 URLEncode，遵循 application/x-www-form-urlencoded 标准。
max-keys	Query	Integer	否	100	设置返回对象的最大数量。最大值为 1000，即一次请求最多返回 1000 个对象。
prefix	Query	String	否	abc	列举指定前缀的对象。
start-after	Query	String	否	test.txt	列举对象的起始位置。您可以通过指定对象的起始位置分页列举对象。
fetch-owner	Query	Bool	否	false	是否返回对象所有者信息，取值如下： `true`：返回对象所有者信息。 `false`：不返回对象所有者信息，默认为 `false`。
continuation-token	Query	String	否	whvFnl2rE5vm9cWvQScxwTuNm0***	指定列举操作从该 Token 开始，通常从上次请求返回的 `NextContinuationToken` 中获取此 Token 。

请求元素

该请求无请求消息元素。

响应消息头

返回公共响应消息头，更多信息，请参见公共参数。

响应元素

参数名称	参数类型	示例值	说明
Name	String	test-bucket	存储桶名称。
Prefix	String	abc	请求中带入的 `prefix` 参数。
Marker	String	abc	请求中带入的 `marker` 参数。
MaxKeys	Integer	100	请求中带入的 `max-keys` 参数。
Delimiter	String	d	请求中带入的 `delimiter` 参数。
EncodingType	String	url	请求中带入的 `encoding-type` 参数。
IsTruncated	Bool	true	返回的结果是否被截断，取值如下： `false`：已返回全部结果。 `true`：还有结果未返回。
StartAfter	String	abcd	如果请求中指定了 `start-after` 参数，则会在响应中包含 `StartAfter` 元素。
ContinuationToken	String	whvFnl2rE5vm9cWvQScxwTuv***	如果请求中指定了 `continuation-token` 参数，则会在响应中包含 `ContinuationToken` 元素。
NextContinuationToken	String	whvFnl2rE5vm9cWvQSg0xfckv***	当 `IsTruncated` 为 `true` 时，返回 `NextContinuationToken` ，表明还可以列举出更多数据。下一次列举请求可以使用 `NextContinuationToken` 继续列举。说明 `NextContinuationToken` 的值不是一个真正的对象名。
CommonPrefixes	Array	[{"Prefix": "abcd"}]	请求中带 `delimiter` 参数时，返回的响应中包含 `CommonPrefixes` 分组信息。该元素标识以 `delimiter` 结尾，并列举对象的共同前缀的名称。
Contents	Array	-	列举对象的信息。说明 `Contents` 是 `Key`、`LastModified`、`ETag`、`Size`、`StorageClass`、`Type`、`HashCrc64ecma`、`Owner` 参数的根节点。
Key	String	abcde	对象的名称。
LastModified	String	2024-06-06T07:15:20.000Z	对象的最后修改时间。
ETag	String	"32185e15494ca8e0eedf12bd218787f6"	在创建每个对象的时候生成的标签，用于唯一标识一个对象。
Size	Integer	4813	对象的大小。
StorageClass	String	STANDARD	对象的存储类型，取值如下： `STANDARD`：标准存储。 `IA`：低频访问存储。 `INTELLIGENT_TIERING`：智能分层存储。 `ARCHIVE_FR`：归档闪回存储。 `ARCHIVE`：归档存储。 `COLD_ARCHIVE`：冷归档存储。 `DEEP_COLD_ARCHIVE`：深度冷归档存储。
Type	String	Appendable	对象为非 Normal 对象时，会返回该元素，取值说明如下： `Appendable`：该对象为追加写接口上传的对象。 `Symlink`：该对象为软链接对象。父节点为 Contents。
HashCrc64ecma	String	2217460101204276403	对象的 64 位 CRC 值。该值根据 ECMA-182 标准计算得出。说明对 TOS 服务端支持 64 位 CRC 校验前创建的对象，则该消息头不会出现在响应消息中。
Owner	Object	-	列举对象所有者的信息。说明 `Owner` 是 `ID` 和 `DisplayName` 参数的根节点。
ID	String	1234567890	账号 ID。
DisplayName	String	test-owner-name	账号名称。

请求示例

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

响应示例

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"
        }
    ]
}