文档

ListObjectsV2(GetBucketV2)

更新时间:

ListObjectsV2(GetBucketV2)接口用于列举存储空间(Bucket)中所有文件(Object)的信息。

注意事项

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

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

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

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

请求语法

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

当您在OSS ON云盒中调用该接口时,您需要将Host替换为云盒Endpoint。更多信息,请参见云盒Endpoint

请求参数

名称

类型

是否必选

示例值

描述

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信息。

合法值:truefalse

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

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

默认值:false

响应元素

名称

类型

示例值

描述

Contents

容器

不涉及

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

父节点:ListBucketResult

CommonPrefixes

字符串

不涉及

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

父节点:ListBucketResult

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

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

返回值:truefalse

  • 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

父节点: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元素。

KeyCount

数字

6

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

NextContinuationToken

字符串

CgJiYw--

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

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进入可读状态的过期时间。

示例

  • 简单请求示例

    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.txtexampleobject2.txtexampleobject3.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参数的长度不符合要求。