列举桶内对象_对象存储服务 OBS

功能介绍

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

如果用户在请求中只指定了桶名，则返回信息中会包含桶内部分或所有对象的描述信息（一次最多返回1000个对象信息）；如果用户还指定了prefix、marker、max-keys、delimiter参数中的一个或多个，则返回的对象列表将按照如表1所示规定的语义返回指定的对象。

用户也可以请求参数中添加versions参数来执行列举桶内多版本对象的操作。

请求消息样式

GET / HTTP/1.1 
 
Host: bucketname.obs.region.example.com
Date: date
Authorization: authorization

请求消息样式（多版本）

GET /?versions HTTP/1.1  
Host: bucketname.obs.region.example.com
Date: date
Authorization: authorization

请求消息参数

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

表1 请求消息参数
参数名称	描述	是否必选
prefix	列举以指定的字符串prefix开头的对象。类型：String	否
marker	列举桶内对象列表时，指定一个标识符，从该标识符以后按字典顺序返回对象列表。该字段仅用于非多版本列举。类型：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=/]，只列举当前目录下的内容，不列举子目录，提高列举效率。类型：String	否
key-marker	列举对象时的起始位置。该字段仅用于多版本列举。类型：String 有效值：上次请求返回体的NextKeyMarker值	否
version-id-marker	本参数只适用于多版本列举场景与请求中的key-marker配合使用，返回的对象列表将是按照字典顺序排序后在该标识符以后的对象(单次返回最大为1000个)。如果version-id-marker不是key-marker对应的一个版本号，则该参数无效。类型：String 有效值：对象的版本号，即上次请求返回体的NextVersionIdMarker值	否

请求消息头

该请求使用公共的请求消息头，具体如表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
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	对象拥有者的DomainId。类型：String 父节点：ListBucketResult.Contents.Owner
IsTruncated	表明是否本次返回的ListBucketResult结果列表被截断。“true”表示本次没有返回全部结果；“false”表示本次已经返回了全部结果。类型：Boolean 父节点：ListBucketResult
Key	对象名。类型：String 父节点：ListBucketResult.Contents
LastModified	对象最近一次被修改的时间（UTC时间）。类型：Date 父节点：ListBucketResult.Contents
Marker	列举对象时的起始位置标识符。类型：String 父节点：ListBucketResult
NextMarker	如果本次没有返回全部结果，响应请求中将包含此字段，用于标明本次请求列举到的最后一个对象。后续请求可以指定Marker等于该值来列举剩余的对象。类型：String 父节点：ListBucketResult
MaxKeys	列举时最多返回的对象个数。类型：String 父节点：ListBucketResult
Name	本次请求的桶名。类型：String 父节点：ListBucketResult
Owner	用户信息，包含对象拥有者DomainId和对象拥有者名称。类型：XML 父节点：ListBucketResult.Contents
DisplayName	对象拥有者名称。类型：String 父节点：ListBucketResult.Contents.Owner
Prefix	对象名的前缀，表示本次请求只列举对象名能匹配该前缀的所有对象。类型：String 父节点：ListBucketResult
Size	对象的字节数。类型：String 父节点：ListBucketResult.Contents
StorageClass	对象的存储类型。类型：String 有效值：STANDARD \| WARM \| COLD 父节点：ListBucketResult.Contents

表3 列举多版本对象响应消息元素
元素名称	描述
ListVersionsResult	保存列举桶中对象列表（含多版本）请求结果的容器。类型：Container
Name	桶名。类型：String 父节点：ListVersionsResult
Prefix	对象名的前缀，表示本次请求只列举对象名能匹配该前缀的所有对象。类型：String 父节点：ListVersionsResult
KeyMarker	列举对象时对象的起始位置标识符。类型：String 父节点：ListVersionsResult
VersionIdMarker	列举对象时对象版本号的起始位置。类型：String 父节点：ListVersionsResult
NextKeyMarker	如果本次没有返回全部结果，响应请求中将包含该元素，用于标明接下来请求的KeyMarker值。类型：String 父节点: ListVersionsResult。
NextVersionIdMarker	如果本次没有返回全部结果，响应请求中将包含该元素，用于标明接下来请求的VersionIdMarker值。类型：String 父节点: ListVersionsResult。
MaxKeys	列举时最多返回的对象个数。类型：String 父节点：ListVersionsResult
IsTruncated	表明是否本次返回的ListVersionsResult结果列表被截断。“true”表示本次没有返回全部结果；“false”表示本次已经返回了全部结果。类型：Boolean 父节点：ListVersionsResult
Version	保存版本信息的容器类型：Container 父节点：ListVersionsResult
DeleteMarker	保存删除标记的容器类型：Container 父节点：ListVersionsResult
Key	对象名。类型：String 父节点：ListVersionsResult.Version \| ListVersionsResult.DeleteMarker
VersionId	对象的版本号。类型：String 父节点：ListVersionsResult.Version \| ListVersionsResult.DeleteMarker
IsLatest	标识对象是否是最新的版本，true代表是最新的版本。类型：Boolean 父节点：ListVersionsResult.Version \| ListVersionsResult.DeleteMarker
LastModified	对象最近一次被修改的时间（UTC时间）。类型：Date 父节点：ListVersionsResult.Version \| ListVersionsResult.DeleteMarker
ETag	对象的base64编码的128位MD5摘要。ETag是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。实际标签是对象的哈希。比如上传对象时ETag为A，下载对象时ETag为B，则说明对象内容发生了变化。ETag只反映变化的内容，而不是其元数据。上传的对象或拷贝操作创建的对象，通过MD5加密后都有唯一的ETag。类型：String 父节点：ListVersionsResult.Version
Type	对象类型，非Normal对象时返回。类型：String 父节点：ListVersionsResult.Version
Size	对象的字节数。类型：String 父节点：ListVersionsResult.Version
Owner	用户信息，包含对象拥有者DomainId和对象拥有者名称。类型：Container 父节点：ListVersionsResult.Version \| ListVersionsResult.DeleteMarker
ID	对象拥有者的DomainId。类型：String 父节点：ListVersionsResult.Version.Owner \| ListVersionsResult.DeleteMarker.Owner
DisplayName	对象拥有者名称。类型：String 父节点：ListVersionsResult.Version.Owner \| ListVersionsResult.DeleteMarker.Owner
StorageClass	对象的存储类型。类型：String 有效值：STANDARD \| WARM \| COLD 父节点：ListVersionsResult.Version
CommonPrefixes	请求中带delimiter参数时，返回消息带CommonPrefixes分组信息。类型：Container 父节点: ListVersionsResult。
Prefix	CommonPrefixes分组信息中，表明不同的Prefix。类型：String 父节点: ListVersionsResult.CommonPrefixes。

错误响应消息

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

请求示例：列举所有对象

GET / 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>examplebucket</Name>
  <Prefix/>
  <Marker/>
  <MaxKeys>1000</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>object001</Key>
    <LastModified>2015-07-01T00:32:16.482Z</LastModified>
    <ETag>"2fa3bcaaec668adc5da177e67a122d7c"</ETag>
    <Size>12041</Size>
    <Owner>
      <ID>b4bf1b36d9ca43d984fbcb9491b6fce9</ID>
      <DisplayName>ObjectOwnerName</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>

请求示例：筛选对象

用户有桶名为examplebucket，桶内共有四个名为newfile，obj001，obj002，obs001的对象，如果只需要列出对象名为obj002的对象，请求消息格式为：

GET /?marker=obj001&prefix=obj 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: BF260000016435D758FBA857E0801874
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCShn/xAyk/xHBX6qgGSB36WXrbco0X80
Content-Type: application/xml
Date: WED, 01 Jul 2015 02:29:48 GMT
Content-Length: 707

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListBucketResult xmlns="http://obs.example.com/doc/2015-06-30/">
<Name>examplebucket</Name>
<Prefix>obj</Prefix>
<Marker>obj001</Marker>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
  <Contents>
    <Key>obj002</Key>
    <LastModified>2015-07-01T02:11:19.775Z</LastModified>
    <ETag>"a72e382246ac83e86bd203389849e71d"</ETag>
    <Size>9</Size>
    <Owner>
      <ID>b4bf1b36d9ca43d984fbcb9491b6fce9</ID>
      <DisplayName>ObjectOwnerName</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>

请求示例：多版本

GET /?versions HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 02:29:45 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iZeDESIMxBK2YODk7vIeVpyO8DI=

响应示例：多版本

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF260000016435D758FBA857E0801874
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCShn/xAyk/xHBX6qgGSB36WXrbco0X80
Content-Type: application/xml
Date: WED, 01 Jul 2015 02:29:48 GMT
Content-Length: 707

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListVersionsResult xmlns="http://obs.example.com/doc/2015-06-30/">
 <Name>bucket02</Name>
  <Prefix/>
  <KeyMarker/>
  <VersionIdMarker/>
  <MaxKeys>1000</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Version>
    <Key>object001</Key>
    <VersionId>00011000000000013F16000001643A22E476FFFF9046024ECA3655445346485a</VersionId>
    <IsLatest>true</IsLatest>
    <LastModified>2015-07-01T00:32:16.482Z</LastModified>
    <ETag>"2fa3bcaaec668adc5da177e67a122d7c"</ETag>
    <Size>12041</Size>
    <Owner>
      <ID>b4bf1b36d9ca43d984fbcb9491b6fce9</ID>
      <DisplayName>ObjectOwnerName</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Version>
</ListVersionsResult>

列举桶内对象