列举桶内对象V2

功能介绍

对桶拥有读权限的用户可以执行获取桶内对象列表的操作。

如果用户在请求的URI里指定了桶名，且显式指定了list-type=2，即GET /?list-type=2，则以V2接口的形式返回桶内部分或所有对象的描述信息（一次最多返回1000个对象信息）；如果用户还指定了prefix、encoding-type、max-keys、delimiter、fetch-owner、start-after、continuation-token参数中的一个或多个，则返回的对象列表将按照如表1所示规定的语义返回指定的对象。

请求消息样式

     GET /?list-type=2 HTTP/1.1 
Host: bucketname.obs.region.example.com
Date: date
Authorization: authorization

请求消息参数

该请求可以通过带参数，列举出桶内的一部分对象，参数的具体含义如下表所示。

表1 请求消息参数
参数名称	描述	是否必选
list-type	只能取值为2，表明采用ListObjectV2接口。类型：Integer	是
prefix	列举以指定的字符串prefix开头的对象。类型：String	否
start-after	列举桶内对象列表时，指定一个标识符，从该标识符以后按字典顺序返回对象列表。类型：String	否
max-keys	指定返回的最大对象数，返回的对象列表将是按照字典顺序的最多前max-keys个对象，范围是[1，1000]，超出范围时，按照默认的1000进行处理。类型：Integer	否
delimiter	将对象名进行分组的分隔符。如果指定了prefix，从prefix到第一次出现delimiter间具有相同字符串的对象名会被分成一组，形成一条CommonPrefixes；如果没有指定prefix，从对象名的首字符到第一次出现delimiter间具有相同字符串的对象名会被分成一组，形成一条CommonPrefixes。例如，桶中有3个对象，分别为abcd、abcde、bbcde。如果指定delimiter为d，prefix为a，abcd、abcde会被分成一组，形成一条前缀为abcd的CommonPrefixes；如果只指定delimiter为d，abcd、abcde会被分成一组，形成一条前缀为abcd的CommonPrefixes，而bbcde会被单独分成一组，形成一条前缀为bbcd的CommonPrefixes。对于并行文件系统，不携带此参数时默认列举是递归列举此目录下所有内容，会列举子目录。在大数据场景下（目录层级深、目录下文件多）的列举，建议设置[delimiter=/]，只列举当前目录下的内容，不列举子目录，提高列举效率。类型：字符。	否
continuation-token	列举桶内对象列表时，从该token以后按字典顺序返回对象列表。类型：String 有效值：上次请求返回体的NextContinuationToken值	否
fetch-owner	结果是否返回对象拥有者信息。类型：Boolean 可选值：true、false	否

请求消息头

该请求使用公共的请求消息头，具体如表3所示。

请求消息元素

该请求消息头中不带消息元素。

响应消息样式

     HTTP/1.1 status_code
Date: date
x-obs-bucket-location: region
Content-Type: application/xml 
Content-Length: length
<Response Body>
 
 
  

响应消息头

该请求的响应消息使用公共消息头，具体请参考表1。

响应消息元素

该请求的响应消息中，会以XML形式将桶中的对象列出来，元素的具体含义如表2所示。

表2 响应消息元素
元素名称	描述
ListBucketResult	桶中对象列表。类型：XML
Contents	对象的元数据信息。类型：XML 父节点：ListBucketResult
CommonPrefixes	请求中带delimiter参数时，返回消息带CommonPrefixes分组信息。类型：XML 父节点：ListBucketResult
ContinuationToken	请求中携带的ContinuationToken参数。类型：String 父节点：ListBucketResult
KeyCount	返回对象个数。类型：Integer 父节点：ListBucketResult
NextContinuationToken	如果本次没有返回全部结果，响应请求中将包含该元素，用于标明接下来请求的ContinuationToken值。类型：String 父节点: ListVersionsResult。
StartAfter	请求中携带的StartAfter参数。
Delimiter	请求中携带的delimiter参数。类型：String 父节点：ListBucketResult
ETag	对象的base64编码的128位MD5摘要。ETag是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。比如上传对象时ETag为A，下载对象时ETag为B，则说明对象内容发生了变化。实际的ETag是对象的哈希值。ETag只反映变化的内容，而不是其元数据。上传的对象或拷贝操作创建的对象，通过MD5加密后都有唯一的ETag。（当对象是服务端加密的对象时，ETag值不是对象的MD5值，而是通过服务端加密计算出的唯一标识。）类型：String 父节点：ListBucketResult.Contents
Type	对象类型，非Normal对象时返回。类型：String 父节点：ListBucketResult.Contents
ID	对象拥有者的租户ID。类型：String 父节点：ListBucketResult.Contents.Owner
IsTruncated	表明是否本次返回的ListBucketResult结果列表被截断。“true”表示本次没有返回全部结果；“false”表示本次已经返回了全部结果。类型：Boolean 父节点：ListBucketResult
Key	对象名。类型：String 父节点：ListBucketResult.Contents
LastModified	对象最近一次被修改的时间（UTC时间）。类型：Date 父节点：ListBucketResult.Contents
MaxKeys	列举时最多返回的对象个数。类型：String 父节点：ListBucketResult
Name	本次请求的桶名。类型：String 父节点：ListBucketResult
Owner	用户信息，包含用户DomainId和用户名。类型：XML 父节点：ListBucketResult.Contents
Prefix	对象名的前缀，表示本次请求只列举对象名能匹配该前缀的所有对象。类型：String 父节点：ListBucketResult
Size	对象的字节数。类型：String 父节点：ListBucketResult.Contents
StorageClass	对象的存储类型。类型：String 有效值：STANDARD \| WARM \| COLD 父节点：ListBucketResult.Contents

错误响应消息

无特殊错误，所有错误已经包含在表2中。

请求示例

列举所有对象

     GET /?list-type=2 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 02:28:25 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:KiyoYze4pmRNPYfmlXBfRTVxt8c=
 
 
  

响应示例

     HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF260000016435D34E379ABD93320CB9
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSXiN7GPL/yXM6OSBaYCUV1zcY5OelWp
Content-Type: application/xml
Date: WED, 01 Jul 2015 02:23:30 GMT
Content-Length: 586

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListBucketResult xmlns="http://obs.example.com/doc/2015-06-30/">
<Name>name</Name>
  <Prefix/>
  <KeyCount>1</KeyCount>
  <MaxKeys>1000</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>obj</Key>
    <LastModified>2021-11-08T11:03:04.236Z</LastModified>
    <ETag>"42648685023dcae595357d91a0936104"</ETag>
    <Size>4939</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>
 
 
  

父主题： 桶的基础操作

上一篇：列举桶内对象

下一篇：获取桶元数据