列表空间 (List Objects)
客户端可以使用该接口获取空间 (Bucket) 包含的对象 (Object) 列表。
请求定义
GET /<BucketName> HTTP/1.1
Host: api-s3.qiniu.com
Date: <date>
Content-Length: <integer>
Authorization: <YourAuthenticatingString>
请求参数
该接口定义以下请求参数:
名称 | 描述 | 要求 |
---|---|---|
delimiter | 对象名称 (Object Key) 分隔符,其效果是根据分隔符将对象名称按照前缀分组,所有返回的字段包含在 CommonPrefixes 元素下 | N |
encoding-type | 请求响应数据的编码方式,默认为 url,即使用 URL-Encoding 编码对象名称 | N |
marker | 指定分页的对象名称 (Object Key),服务器端只返回按字母序排序后指定对象名称以后的对象列表 | N |
max-keys | 指定分页的最大返回对象数量,默认服务器端返回最多 1000 个对象;如果客户端需要控制返回对象的最大数量,可以通过指定该值实现 | N |
prefix | 对象名称 (Object Key) 前缀,其效果是只返回包含指定前缀的对象 | N |
请求头
请求数据
该接口未定义请求数据
响应定义
该接口正确处理请求时返回如下 XML 数据
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>BucketName</Name>
<Delimiter>/</Delimiter>
<Prefix/>
<Marker/>
<MaxKeys>1000</MaxKeys>
<IsTruncated>true</IsTruncated>
<NextMarker>1000-object.png</NextMarker>
<Contents>
<Key>my-object.png</Key>
<LastModified>2006-01-02T15:04:05.000Z</LastModified>
<ETag>1c977fba9d86ede5f27731645a393328</ETag>
<Size>10240</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>1234567890</ID>
<DisplayName>s3@qiniu.com</DisplayName>
</Owner>
</Contents>
...
<CommonPrefixes>
<Prefix>my-folder/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>my-subfolder/</Prefix>
</CommonPrefixes>
...
</ListBucketResult>
IsTruncated
表明空间 (Bucket) 下是否包含更多对象,如果该值为 true,客户端可以使用分页请求获取更多数据NextMarker
指定分页的下一页开始的对象名称,如果响应数据不包含该值但 IsTruncated 为 true,客户端可以使用响应数据中的最后一个对象名称的值作为分页请求的 marker 值StorageClass
对象存储的类型,目前该值只能为 STANDARDOwner
指定对象 (Object) 的所有者,通常为空间 (Bucket) 创建者CommonPrefixes
当请求参数 delimiter 不为空时,该值包括所有对象名称包含 delimiter 值的前缀列表;列表可能超过返回的最大值 MaxKeys,客户端可以使用 Marker 参数获取更多列表数据