更新时间:2024-03-05 GMT+08:00

列举桶内对象

功能介绍

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

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

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

请求消息样式

1
2
3
4
5
GET / HTTP/1.1 
 
Host: bucketname.obs.region.example.com
Date: date
Authorization: authorization

请求消息样式(多版本)

1
2
3
4
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所示。

请求消息元素

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

响应消息样式

1
2
3
4
5
6
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中。

请求示例:列举所有对象

1
2
3
4
5
6
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=

响应示例:列举所有对象

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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=

响应示例:筛选对象

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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>

请求示例:多版本

1
2
3
4
5
6
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=

响应示例:多版本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
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>