全部文档
当前文档

热搜词推荐

云服务器 虚拟私有网络 边缘节点计算 对等连接

共搜索到 0 条结果

暂无内容

如果没有找到您期望的内容，请尝试其他搜索词

文档中心

对象存储(KS3)

查看更多结果
未找到含当前关键字的文档标题
页面目录
全部展开全部收起
未找到含该关键词的产品
文档中心 对象存储(KS3) API文档 Bucket相关 基本操作 List Objects V2

List Objects V2

最近更新时间：2023-10-30 10:16:13

描述

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 字符串 否 对Object名字进行分组的字符。将第一次出现Delimiter字符之间的Object作为一组元素CommonPrefixes。
默认值：无
encoding-type 字符串 否 对返回的内容进行编码的编码类型。
可选值：url
默认值：无
fetch-owner 布尔值 否 指定在响应结果中是否包含owner信息。
可选值：true/false。
    * true：表示响应结果中包含owner信息。
    * false：表示响应结果中不包含owner信息。
默认值：false
list-type 数字 是 取值只能为2。如果不是2，会按照Listobjects来处理
max-keys 字符串 否 指定返回对象的最大个数。如果满足查询条件的对象个数超过max-keys指定的个数，响应结果会包含NextContinuationToken，用于作为下一次list的continuation-token。
取值：[1,1000]。当大于1000时，最多返回1000条记录
默认值: 1000。如果请求参数包含delimiter，则默认值为100
prefix 字符串 否 指定返回对象名的前缀。
默认值：无
start-after 字符串 否 start-after用于指定从哪个对象开始list，start-after可以是存储空间中的任何对象名称，返回结果中不会包含start-after对应的key。若start-after在对象列表中不存在，则会从符合start-after字母排序的下一个开始打印。
默认值：无

响应

响应语法

HTTP/1.1 200 OK
<?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 字符串 对象拥有者的用户ID。
父节点：ListBucketResult.Contents.Owner
EncodingType 字符串 指定的编码类型。如果请求的参数中指定了encoding-type，则会对响应结果中的Delimiter、Key、Prefix（包括CommonPrefixes中的Prefix）、StartAfter这些元素进行编码。
父节点：ListBucketResult
ETag 字符串 对象的实体标签，ETag在上传对象时生成，用于标识一个对象的内容。
父节点：ListBucketResult.Contents
ID 字符串 对象拥有者的用户ID。
父节点：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
Name 字符串 Bucket名称。
父节点：ListBucketResult
NextContinuationToken 字符串 当 isTruncated 是true时，会返回NextContinuationToken，需要将NextContinuationToken指定为下一次ListObjectsV2操作的ContinuationToken，以继续获取结果。
Owner 容器 保存对象所有者信息的容器。
子节点：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:c6526eb1ea90415cbc467bd2a51a****
Date: Wed, 10 Nov 2021 01:25:02 GMT
Content-Type: application/xml
Server: KS3

<?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参数的示例

请求示例
GET /?list-type=2&prefix=img 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:f9ofst80harobs6oc1ib5no5llv0****
Date: Wed, 10 Nov 2021 01:25:02 GMT
Content-Type: application/xml
Server: KS3

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>examplebucket</Name>
    <Prefix>img</Prefix>
    <KeyCount>4</KeyCount>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <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
响应示例
HTTP/1.1 200 OK
x-kss-request-id:c6526eb1ea90415cbc467bd2a51a****
Date: Wed, 10 Nov 2021 01:25:02 GMT
Content-Type: application/xml
Server: KS3

<?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>100</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
响应示例
HTTP/1.1 200 OK
x-kss-request-id:c6526eb1ea90415cbc467bd2a51a****
Date: Wed, 10 Nov 2021 01:25:02 GMT
Content-Type: application/xml
Server: KS3

<?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>

错误码

错误码 HTTP状态码 描述
Invalid Argument 400 Bad Request max-keys小于1。
SignatureDoesNotMatch 403 使用Postman时，一些参数涉及到的特殊字符（如/）没有进行转义。
文档导读
上一篇：Head Bucket
下一篇：DELETE Bucket
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈