全部产品
Search

搜索本产品

    对象存储 OSS：调用GetBucketV2列举存储空间

    文档中心

    对象存储 OSS：调用GetBucketV2列举存储空间

    更新时间：Dec 06, 2024

    ListObjectsV2（GetBucketV2）接口用于列举存储空间（Bucket）中的文件（Object）的信息。

    注意事项

    • 要列举Bucket中的所有Object信息，您必须拥有oss:ListObjects权限。

    • 执行ListObjectsV2（GetBucketV2）请求时不会返回Object中自定义的元数据。

    • 如果您开启了日志转存或者实时日志查询，则调用该接口产生的访问日志中对应的operation字段为GetBucket。

    • 调用ListObjectsV2（GetBucketV2）接口按照Put类请求次数计费。更多信息，请参见Put类请求。

    • 一次返回的文件列表存在数量上限，默认最大展示100条。如需拉取全量文件，需要借助NextContinuationToken、continuationToken等参数分段获取。

    请求语法

    GET /?list-type=2 HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

    请求参数

    名称

    类型

    是否必选

    示例值

    描述

    list-type

    数字

    是

    2

    取值只能为2。

    delimiter

    字符串

    否

    /

    对Object名字进行分组的字符。所有Object名字包含指定的前缀，第一次出现delimiter字符之间的Object作为一组元素（即CommonPrefixes）。

    默认值：无

    start-after

    字符串

    否

    b

    设定从start-after之后按字母排序开始返回Object。

    start-after用来实现分页显示效果，参数的长度必须小于1024字节。

    做条件查询时，即使start-after在列表中不存在，也会从符合start-after字母排序的下一个开始打印。

    默认值：无

    continuation-token

    字符串

    否

    test1.txt

    指定List操作需要从此token开始。您可从ListObjectsV2（GetBucketV2）结果中的NextContinuationToken获取此token。

    max-keys

    字符串

    否

    100

    指定返回Object的最大数。

    取值：大于0小于等于1000

    默认值：100

    说明

    • 如果因为max-keys的设定无法一次完成列举，返回结果会附加NextContinuationToken作为下一次列举的continuation-token。

    • 返回的Object数量不保证达到设定的max-keys。出现这种情况时，需要从返回结果中获取NextContinuationToken作为下一次列举的continuation-token。

    prefix

    字符串

    否

    a

    限定返回文件的Key必须以prefix作为前缀。

    如果把prefix设为某个文件夹名，则列举以此prefix开头的文件，即该文件夹下递归的所有文件和子文件夹。

    在设置prefix的基础上，将delimiter设置为正斜线（/）时，返回值就只列举该文件夹下的文件，文件夹下的子文件夹名返回在CommonPrefixes中，子文件夹下递归的所有文件和文件夹不显示。

    例如，一个Bucket中有三个Object，分别为fun/test.jpg、fun/movie/001.avi和fun/movie/007.avi。如果设定prefix为fun/，则返回三个Object；如果在prefix设置为fun/的基础上，将delimiter设置为正斜线（/），则返回fun/test.jpg和fun/movie/。

    说明

    • 参数的长度必须小于1024字节。

    • 设置prefix参数时，不能以正斜线（/）开头。如果prefix参数置空，则默认列举Bucket内的所有Object。

    • 使用prefix查询时，返回的Key中仍会包含prefix。

    默认值：无

    encoding-type

    字符串

    否

    url

    对返回的内容进行编码并指定编码的类型。

    默认值：无

    可选值：url

    说明

    delimiter、start-after、prefix、NextContinuationToken以及Key使用UTF-8字符。如果delimiter、start-after、prefix、NextContinuationToken以及Key中包含XML 1.0标准不支持的控制字符，您可以通过指定encoding-type对返回结果中的delimiter、start-after、prefix、NextContinuationToken以及Key进行编码。

    fetch-owner

    布尔值

    否

    false

    指定是否在返回结果中包含owner信息。

    合法值：true、false

    • true：表示返回结果中包含owner信息。

    • false：表示返回结果中不包含owner信息。

    默认值：false

    响应元素

    名称

    类型

    示例值

    描述

    Contents

    容器

    不涉及

    保存每个返回Object元数据的容器。

    父节点：ListBucketResult

    CommonPrefixes

    字符串

    不涉及

    如果请求中指定了Delimiter参数，则会在返回的响应中包含CommonPrefixes元素。该元素表明以Delimiter结尾，并有共同前缀的Object名称的集合。

    父节点：ListBucketResult

    子节点：Prefix

    Delimiter

    字符串

    /

    对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现Delimiter字符之间的Object作为一组元素CommonPrefixes。

    父节点：ListBucketResult

    EncodingType

    字符串

    不涉及

    指明返回结果中编码使用的类型。如果请求的参数中指定了Encoding-type，则会对返回结果中的Delimiter、StartAfter、Prefix、NextContinuationToken和Key这些元素进行编码。

    父节点：ListBucketResult

    DisplayName

    字符串

    user_example

    Object拥有者名称。

    父节点：ListBucketResult.Contents.Owner

    ETag

    字符串

    5B3C1A2E053D763E1B002CC607C5A0FE1****

    ETag在每个Object生成时创建，用于标识一个Object的内容。

    父节点：ListBucketResult.Contents

    • 对于PutObject请求创建的Object，ETag值是其内容的MD5值。

    • 对于其他方式创建的Object，ETag值是基于一定计算规则生成的唯一值，但不是其内容的MD5值。

    • ETag值可以用于检查Object内容是否发生变化。不建议使用ETag值作为Object内容的MD5校验数据完整性的依据。

    ID

    字符串

    0022012****

    Bucket拥有者的用户ID。

    父节点：ListBucketResult.Contents.Owner

    IsTruncated

    枚举字符串

    false

    请求中返回的结果是否被截断。

    返回值：true、false

    • true表示本次没有返回全部结果。

    • false表示本次已经返回了全部结果。

    父节点：ListBucketResult

    Key

    字符串

    fun/test.jpg

    Object的Key。

    父节点：ListBucketResult.Contents

    LastModified

    时间

    2012-02-24T08:42:32.000Z

    Object最后被修改的时间。

    父节点：ListBucketResult.Contents

    ListBucketResult

    容器

    不涉及

    保存GetBucket请求结果的容器。

    子节点：Name、Prefix、StartAfter、MaxKeys、 Delimiter、IsTruncated、NextContinuationToken、Contents

    父节点：None

    StartAfter

    字符串

    test1.txt

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

    MaxKeys

    字符串

    100

    响应请求内返回结果的最大数目。

    父节点：ListBucketResult

    Name

    字符串

    examplebucket

    Bucket名称。

    父节点：ListBucketResult

    Owner

    容器

    不涉及

    保存Bucket拥有者信息的容器。

    子节点：DisplayName、ID

    父节点：ListBucketResult.Contents

    Prefix

    字符串

    fun/

    本次查询结果的前缀。

    父节点：ListBucketResult

    Type

    字符串

    Normal

    文件类型。

    取值：Normal，Multipart，Appendable，Symlink。

    父节点：ListBucketResult.Contents

    Size

    字符串

    344606

    返回Object大小，单位为字节。

    父节点：ListBucketResult.Contents

    StorageClass

    字符串

    Standard

    Object的存储类型。

    父节点：ListBucketResult.Contents

    ContinuationToken

    字符串

    test1.txt

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

    父节点：ListBucketResult

    KeyCount

    数字

    6

    此次请求返回的Key的个数。如果指定了Delimiter，则KeyCount为Key和CommonPrefixes的元素之和。

    父节点：ListBucketResult

    NextContinuationToken

    字符串

    CgJiYw--

    表明此次ListObjectsV2（GetBucketV2）请求包含后续结果，需要将NextContinuationToken指定为ContinuationToken继续获取结果。

    父节点：ListBucketResult

    RestoreInfo

    字符串

    ongoing-request="true"

    Object的解冻状态。

    • 如果没有提交RestoreObject请求或者RestoreObject请求已过期，则不返回该字段。

    • 如果已经提交RestoreObject请求，但解冻操作未完成，则返回的RestoreInfo值为ongoing-request="true"。

    • 如果已经提交RestoreObject请求，且解冻操作已完成，则返回的RestoreInfo值为ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"。其中，expiry-date字段表示解冻完成后Object进入可读状态的过期时间。

    父节点：ListBucketResult.Contents

    示例

    • 简单请求示例 

      GET /?list-type=2 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6q**************:77Dv****************

      返回示例 

      HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 1866
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Name>examplebucket</Name>
    <Prefix></Prefix>
    <MaxKeys>100</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a</Key>
        <LastModified>2020-05-18T05:45:43.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>b</Key>
        <LastModified>2020-05-18T05:45:50.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>b/c</Key>
        <LastModified>2020-05-18T05:45:54.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>bc</Key>
        <LastModified>2020-05-18T05:45:59.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>c</Key>
        <LastModified>2020-05-18T05:45:57.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <KeyCount>6</KeyCount>
</ListBucketResult>

    • 带prefix参数的请求示例 

      GET /?list-type=2&prefix=a HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6q**************:77Dv****************

      返回示例 

      HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 1464
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Name>examplebucket</Name>
    <Prefix>a</Prefix>
    <MaxKeys>100</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a</Key>
        <LastModified>2020-05-18T05:45:43.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <KeyCount>2</KeyCount>
</ListBucketResult>

    • 带prefix和delimiter参数的请求示例 

      GET /?list-type=2&prefix=a/&delimiter=/ HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6q**************:77Dv****************

      返回示例 

      HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 712
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Name>examplebucket</Name>
    <Prefix>a/</Prefix>
    <MaxKeys>100</MaxKeys>
    <Delimiter>/</Delimiter>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <CommonPrefixes>
        <Prefix>a/b/</Prefix>
    </CommonPrefixes>
    <KeyCount>2</KeyCount>
</ListBucketResult>

    • 带start-after、max-keys和fetch-owner参数的请求示例 

      GET /?list-type=2&start-after=b&max-keys=3&fetch-owner=true HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6q**************:77Dv****************

      返回示例 

      HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 712
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Name>examplebucket</Name>
    <Prefix></Prefix>
    <StartAfter>b</StartAfter>
    <MaxKeys>3</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>true</IsTruncated>
    <NextContinuationToken>CgJiYw--</NextContinuationToken>
    <Contents>
        <Key>b/c</Key>
        <LastModified>2020-05-18T05:45:54.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>ba</Key>
        <LastModified>2020-05-18T11:17:58.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>bc</Key>
        <LastModified>2020-05-18T05:45:59.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <KeyCount>3</KeyCount>
</ListBucketResult>

    • 请求的Bucket包含归档或冷归档类型文件

      假设examplebucket中包含文件exampleobject1.txt、exampleobject2.txt和exampleobject3.txt，其存储类型均为冷归档存储类型（ColdArchive）。这三个文件所处的状态说明如下：

      • exampleobject1.txt未提交RestoreObject请求或者RestoreObject请求已过期。

      • exampleobject2.txt已提交RestoreObject请求，但解冻操作未完成。

      • exampleobject3.txt已提交RestoreObject请求，并且解冻操作已完成。

      请求示例

      GET / HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6q**************:77Dv****************

      返回示例

      HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 1866
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
  <Name>examplebucket</Name>
  <Prefix></Prefix>
  <Marker></Marker>
  <MaxKeys></MaxKeys>
  <Delimiter></Delimiter>
  <IsTruncated>false</IsTruncated>
  <Contents>
        <Key>exampleobject1.txt</Key>
        <LastModified>2020-06-22T11:42:32.000Z</LastModified>
        <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>ColdArchive</StorageClass>
        <Owner>
            <ID>0022012****</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
  </Contents>
  <Contents>
        <Key>exampleobject2.txt</Key>
        <LastModified>2020-06-22T11:42:32.000Z</LastModified>
        <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <RestoreInfo>ongoing-request="true"</RestoreInfo>
        <Owner>
            <ID>0022012****</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
  </Contents>
  <Contents>
        <Key>exampleobject3.txt</Key>
        <LastModified>2020-06-22T11:42:32.000Z</LastModified>
        <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <RestoreInfo>ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"</RestoreInfo>
        <Owner>
            <ID>0022012****</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
  </Contents>
</ListBucketResult>

    错误码

    HTTP状态码

    描述

    NoSuchBucket

    404

    请求的目标Bucket不存在。请检查请求的Bucket名称是否符合规范。

    AccessDenied

    403

    没有访问该Bucket的权限。只有Bucket拥有者以及被授予oss:ListObjects权限的用户可以访问该Bucket。

    InvalidArgument

    400

    • max-keys小于0或者大于1000。

    • prefix、marker、delimiter参数的长度不符合要求。