You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /
  • 对象存储

ListObjectsV2

最近更新时间：2024.01.15 15:20:45

首次发布时间：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，表示对返回的内容进行 URL 编码。

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

存储桶名称。

Prefix

String

请求中带入的 prefix 参数。

Marker

String

请求中带入的 marker 参数。

MaxKeys

Integer

请求中带入的 max-keys 参数。

Delimiter

String

请求中带入的 delimiter 参数。

EncodingType

String

请求中带入的 encoding-type 参数。

IsTruncated

Bool

返回的结果是否被截断，取值如下：

  • false：已返回全部结果。
  • true：还有结果未返回。

StartAfter

String

如果请求中指定了 StartAfter 参数，则会在响应中包含 StartAfter 元素。

ContinuationToken

String

如果请求中指定了 ContinuationToken 参数，则会在响应中包含 ContinuationToken 元素。

NextContinuationToken

String

当 IsTruncated 为 true 时，返回 NextContinuationToken ，表明还可以列举出更多数据。下一次列举请求可以使用 NextContinuationToken 继续列举。

说明

NextContinuationToken 的值不是一个真正的对象名。

CommonPrefixes

Array

请求中带 delimiter 参数时，返回的响应中包含 CommonPrefixes 分组信息。该元素标识以 delimiter 结尾，并列举对象的共同前缀的名称。

Contents

Array

列举对象的信息。

说明

Contents 是 Key、LastModified、ETag、Size、StorageClass、HashCrc64ecma、Owner 参数的根节点。

Key

String

对象的名称。

LastModified

String

对象的最后修改时间。

ETag

String

在创建每个对象的时候生成的标签，用于唯一标识一个对象。

Size

Integer

对象的大小。

StorageClass

String

对象的存储类型，取值如下：

  • STANDARD：标准存储。
  • IA：低频访问存储。
  • INTELLIGENT_TIERING：智能分层存储。
  • ARCHIVE_FR：归档闪回存储。
  • ARCHIVE：归档存储。
  • COLD_ARCHIVE：冷归档存储。
  • DEEP_COLD_ARCHIVE：深度冷归档存储。

    说明

    深度冷归档目前处于邀测状态，如您需要使用该存储类型，请联系客户经理。

HashCrc64ecma

String

对象的 64 位 CRC 值。 该值根据 ECMA-182 标准计算得出。

说明

对 TOS 服务端支持 64 位 CRC 校验前创建的对象，则该消息头不会出现在响应消息中。

Owner

Object

列举对象所有者的信息。

说明

Owner 是 ID 和 DisplayName 参数的根节点。

ID

String

账号 ID。

DisplayName

String

账号名称。

请求示例

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