ListObjectsV2(GetBucketV2)列举存储空间中的对象文件-对象存储-阿里云

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

请求语法

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

OSS ON云盒环境中调用该接口时，需要将Host替换为云盒Endpoint。详细信息请参考云盒Endpoint。

使用说明

执行ListObjectsV2（GetBucketV2）请求时不会返回Object中自定义的元数据。单次请求返回的文件列表默认最大100条，如需获取全量文件列表，需要借助NextContinuationToken、continuationToken等参数实现分段获取。

调用该接口列举Bucket中的所有Object信息，必须拥有oss:ListObjects权限。
开启日志转存或实时日志查询后，调用该接口产生的访问日志中对应的operation字段为GetBucket。
Bucket开启版本控制后，覆写或误删除操作会产生大量删除标记和历史版本，建议配置生命周期规则定期清理删除标记和不再需要的历史版本，避免影响List操作的性能。
调用ListObjectsV2（GetBucketV2）接口按照Put类请求次数计费。更多信息，请参见Put类API请求。

请求参数

名称	类型	是否必选	示例值	描述
list-type	数字	是	2	取值固定为2。
delimiter	字符串	否	/	对Object名字进行分组的字符。所有Object名字包含指定前缀且第一次出现delimiter字符之间的Object作为一组元素（即CommonPrefixes）。默认值：无
start-after	字符串	否	b	指定从start-after之后按字母排序开始返回Object，用于实现分页显示效果。参数长度必须小于1024字节。执行条件查询时，即使start-after在列表中不存在，也会从符合start-after字母排序的下一个Object开始返回结果。默认值：无
continuation-token	字符串	否	test1.txt	指定List操作需要从此token开始继续列举。此token可从上一次ListObjectsV2（GetBucketV2）结果中的NextContinuationToken获取。
max-keys	数字	否	100	指定返回Object的最大数量。取值：大于0小于等于1000 默认值：100 当因为max-keys设定无法一次完成列举时，返回结果会包含`NextContinuationToken`作为下次列举的`continuation-token`参数值。返回的Object数量不保证达到设定的max-keys值。出现这种情况时，需要从返回结果中获取`NextContinuationToken`作为下次列举的`continuation-token`参数值。
prefix	字符串	否	a	限定返回文件的Key必须以prefix作为前缀，将prefix设为某个文件夹名时，可列举该文件夹下递归的所有文件和子文件夹。配合delimiter参数使用时，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中包含XML 1.0标准不支持的控制字符时，通过指定encoding-type参数可对返回结果中的这些字段进行URL编码。 delimiter、start-after、prefix、NextContinuationToken以及Key使用UTF-8字符编码。
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
SealedTime	时间	2020-05-21T12:07:15.000Z	文件执行Seal操作的时间。当访问处于Sealed状态的可追加写文件（Appendable 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: Thu, 17 Apr 2025 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

返回示例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 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: Thu, 17 Apr 2025 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

返回示例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 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: Thu, 17 Apr 2025 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

返回示例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 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: Thu, 17 Apr 2025 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

返回示例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 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包含归档或冷归档类型文件

请求示例

GET /?list-type=2 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

返回示例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 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>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>

文件所处的状态说明如下：

exampleobject1.txt未提交RestoreObject请求或者RestoreObject请求已过期。
exampleobject2.txt已提交RestoreObject请求，但解冻操作未完成。
exampleobject3.txt已提交RestoreObject请求，且解冻操作已完成。

错误码

错误码	HTTP状态码	描述
NoSuchBucket	404	请求的目标Bucket不存在。请检查请求的Bucket名称是否符合命名规范。
AccessDenied	403	没有访问该Bucket的权限。只有Bucket拥有者以及被授予`oss:ListObjects`权限的用户可以访问该Bucket。
InvalidArgument	400	max-keys参数值小于0或者大于1000。 prefix、start-after、delimiter参数的长度不符合要求。

集成方式

SDK
ListObjectsV2接口所对应的各语言SDK如下：
Java
Python V2
C
Go V2
Node.js
IOS
Android
Ruby
PHP V2
.NET
命令行工具ossutil
ListObjectsV2接口所对应的ossutil命令，请参见list-objects-v2（get-bucket-v2）。