List Object V2

最近更新时间:2022-05-09 11:04:27

查看PDF

描述

List Objects V2接口用于列出Bucket中的对象,每个请求最多列出1000个对象,返回的对象列表,按照各个对象名的升序排序。访问此接口时,需要有 ks3:ListBucket权限。

推荐您使用List Objects V2接口,为保证向后兼容,KS3仍然支持List Objects接口。

请求

语法

GET /?list-type=2&continuation-token={ContinuationToken}&delimiter={Delimiter}&encoding-type={EncodingType}&fetch-owner={FetchOwner}&max-keys={MaxKeys}&prefix={Prefix}&start-after={StartAfter} HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}

请求参数

名称 类型 是否必填 描述
continuation-token 字符串 指定从此token开始list,可以从ListObjectsV2响应结果中的NextContinuationToken获取此token,此token不是一个真实的对象名称。
delimiter 字符串 用于对对象名称进行分组的字符。默认值:无
encoding-type 字符串 对返回的内容进行编码的编码类型。可选值:url默认值:无
fetch-owner 布尔值 指定在响应结果中是否包含owner信息。可选值:true、false。true:表示响应结果中包含owner信息。false:表示响应结果中不包含owner信息。默认值:false
list-type 数字 取值只能为2。如果不是2,会按照Listobjects来处理
max-keys 字符串 指定返回对象的最大个数。取值:[1,1000]默认值:1000说明:如果满足查询条件的对象个数超过max-keys指定的个数,响应结果会包含NextContinuationToken,用于作为下一次list的continuation-token。
prefix 字符串 指定返回对象名的前缀。默认值:无
start-after 字符串 start-after用于指定从哪个对象开始list,start-after可以是存储空间中的任何对象名称,返回结果中不会包含start-after对应的key。若start-after在对象列表中不存在,则会从符合start-after字母排序的下一个开始打印。默认值:无

响应

响应语法

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
  <IsTruncated>boolean</IsTruncated>
  <Contents>
    <ETag>string</ETag>
    <Key>string</Key>
    <LastModified>timestamp</LastModified>
    <Owner>
      <DisplayName>string</DisplayName>
      <ID>string</ID>
    </Owner>
    <Size>integer</Size>
    <StorageClass>string</StorageClass>

  </Contents>
  ...
  <Name>string</Name>
  <Prefix>string</Prefix>
  <Delimiter>string</Delimiter>
  <MaxKeys>integer</MaxKeys>
  <CommonPrefixes>
    <Prefix>string</Prefix>
  </CommonPrefixes>
  ...
  <EncodingType>string</EncodingType>
  <KeyCount>integer</KeyCount>
  <ContinuationToken>string</ContinuationToken>
  <NextContinuationToken>string</NextContinuationToken>
  <StartAfter>string</StartAfter>

</ListBucketResult>

响应内容

名称 类型 描述
Contents 容器 每个对象的元数据信息的容器。父节点:ListBucketResult
CommonPrefixes 字符串 如果请求中指定了delimiter参数,则响应中可以包含CommonPrefixes元素。CommonPrefixes包含 prefix 和下一个由delimiter指定的字符串之间的所有对象名称。例如,如果有3个对象img/1.jpg, img/001/2.jpg, img/001/3.jpg。若指定prefix为img/, delimiter为/,那么返回的对象是img/1.jpg和CommonPrefixes img/001父节点:ListBucketResult
ContinuationToken 字符串 如果请求中指定了continuation-token参数,则会在响应中包含ContinuationToken元素。
Delimiter 字符串 指定的delimiter,即对对象名称进行分组的字符 父节点:ListBucketResult
DisplayName 字符串 对象所有者的显示名称。父节点:ListBucketResult.Contents.Owner
EncodingType 字符串 指定的编码类型。如果请求的参数中指定了encoding-type,则会对响应结果中的Delimiter、Key、Prefix(包括CommonPrefixes中的Prefix)、StartAfter这些元素进行编码。父节点:ListBucketResult
ETag 字符串 对象的实体标签,ETag在上传对象时生成,用于标识一个对象的内容。父节点:ListBucketResult.Contents
ID 字符串 Bucket拥有者的用户ID。 object拥有者的用户ID(和OSS有区别)父节点:ListBucketResult.Contents.Owner
IsTruncated 枚举字符串 响应中是否返回了所有结果。 返回值:true、false。true表示本次没有返回全部结果。false表示本次已经返回了全部结果。父节点:ListBucketResult
Key 字符串 对象名称。父节点:ListBucketResult.Contents
KeyCount 数字 响应结果中返回的对象个数。KeyCount会小于等于MaxKeys。如果指定了delimiter,则KeyCount为Key和CommonPrefixes的元素之和。
LastModified 时间 对象最后被修改的时间。父节点:ListBucketResult.Contents
ListBucketResult 容器 ListBucket结果的容器。子节点:Name、Prefix、StartAfter、MaxKeys、 Delimiter、IsTruncated、NextContinuationToken、Contents父节点:None
MaxKeys 字符串 响应中返回的最大对象个数。父节点:ListBucketResult说明:当有delimiter时,maxkeys默认为100。
Name 字符串 Bucket名称。父节点:ListBucketResult
NextContinuationToken 字符串 当 isTruncated 是true时,会返回NextContinuationToken,需要将NextContinuationToken指定为下一次ListObjectsV2操作的ContinuationToken,以继续获取结果。
Owner 容器 保存Bucket所有者信息的容器。子节点:DisplayName、ID父节点:ListBucketResult
Prefix 字符串 指定的对象名称前缀。 父节点:ListBucketResult
Size 字符串 对象大小。单位:字节。 父节点:ListBucketResult.Contents
StartAfter 字符串 如果请求中指定了start-after参数,则响应中会包含StartAfter元素
StorageClass 字符串 对象的存储类型。父节点:ListBucketResult.Contents

示例

列出所有对象

请求示例
GET /?list-type=2 HTTP/1.1
Host: examplebucket.ks3-cn-beijing.ksyuncs.com
Authorization: authorization string
Date: Wed, 10 Nov 2021 01:25:02 GMT
响应示例
HTTP/1.1 200 OK
x-kss-request-id:c6526eb1ea90415cbc467bd2a51a7d41
Date: Wed, 10 Nov 2021 01:25:02 GMT
Content-Type: application/xml
Server: Tengine
Content-Length: 365224

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>examplebucket</Name>
    <Prefix></Prefix>
    <KeyCount>5</KeyCount>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a.jpg</Key>
        <LastModified>2021-11-10T01:33:04.000Z</LastModified>
        <ETag>"1eb8c473d5617650835ab8f235cb030c"</ETag>
        <Size>787</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>img/001/2.jpg</Key>
        <LastModified>2021-11-10T01:33:59.000Z</LastModified>
        <ETag>"1eb8c473d5617650835ab8f235cb030c"</ETag>
        <Size>787</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>img/001/3.jpg</Key>
        <LastModified>2021-11-10T01:34:07.000Z</LastModified>
        <ETag>"1eb8c473d5617650835ab8f235cb030c"</ETag>
        <Size>787</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>img/1.jpg</Key>
        <LastModified>2021-11-10T01:33:50.000Z</LastModified>
        <ETag>"1eb8c473d5617650835ab8f235cb030c"</ETag>
        <Size>787</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>imgabc.jpg</Key>
        <LastModified>2021-11-10T01:33:39.000Z</LastModified>
        <ETag>"1eb8c473d5617650835ab8f235cb030c"</ETag>
        <Size>787</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
</ListBucketResult>

带prefix和delimiter参数的示例

请求示例
GET /?list-type=2&prefix=img&delimiter=/ HTTP/1.1
Host: examplebucket.ks3-cn-beijing.ksyuncs.com
Authorization: authorization string
Date: Wed, 10 Nov 2021 01:25:02 GMT
响应示例
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>examplebucket</Name>
    <Prefix>img</Prefix>
    <KeyCount>2</KeyCount>
    <MaxKeys>1000</MaxKeys>
    <Delimiter>/</Delimiter>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>imgabc.jpg</Key>
        <LastModified>2021-11-10T01:33:39.000Z</LastModified>
        <ETag>"1eb8c473d5617650835ab8f235cb030c"</ETag>
        <Size>787</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <CommonPrefixes>
        <Prefix>img/</Prefix>
    </CommonPrefixes>
</ListBucketResult>

带encoding-type, start-after, max-keys参数的示例

请求示例
GET /?list-type=2&prefix=img/测试&encoding-type=url&start-after=img/测试.txt&max-keys=1 HTTP/1.1
Host: examplebucket.ks3-cn-beijing.ksyuncs.com
Authorization: authorization string
Date: Wed, 10 Nov 2021 01:25:02 GMT
响应示例
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>examplebucket</Name>
    <Prefix>img/%E6%B5%8B%E8%AF%95</Prefix>
    <StartAfter>img/%E6%B5%8B%E8%AF%95.txt</StartAfter>
    <KeyCount>1</KeyCount>
    <MaxKeys>1</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>img/%E6%B5%8B%E8%AF%95/test.txt</Key>
        <LastModified>2021-11-10T03:26:28.000Z</LastModified>
        <ETag>"bbb8aae57c104cda40c93843ad5e6db8"</ETag>
        <Size>9</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
</ListBucketResult>

文档内容是否对您有帮助?

根本没帮助
文档较差
文档一般
文档不错
文档很好

在文档使用中是否遇到以下问题

内容不全,不深入
内容更新不及时
描述不清晰,比较混乱
系统或功能太复杂,缺乏足够的引导
内容冗长

更多建议

0/200

评价建议不能为空

提交成功!

非常感谢您的反馈,我们会继续努力做到更好!

问题反馈