文档首页/ 对象存储服务 OBS/ API参考（安卡拉区域）/ API/ 桶的基础操作/ 列举桶内对象
更新时间：2024-04-15 GMT+08:00
查看PDF
分享

列举桶内对象

功能介绍

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

如果用户在请求中只指定了桶名，则返回信息中会包含桶内部分或所有对象的描述信息（一次最多返回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。

类型：String

否

key-marker

列举对象时的起始位置。该字段仅用于多版本列举。

类型：String

有效值：上次请求返回体的NextKeyMarker值

否

version-id-marker

本参数只适用于多版本列举场景

与请求中的key-marker配合使用，返回的对象列表将是按照字典顺序排序后在该标识符以后的对象(单次返回最大为1000个)。如果version-id-marker不是key-marker对应的一个版本号，则该参数无效。

类型：String

有效值：对象的版本号，即上次请求返回体的NextVersionIdMarker值

否

请求消息头

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

请求消息元素

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

响应消息样式

1
2
3
4
5
 
HTTP/1.1 status_code
Date: date
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
表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

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
 
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>
  </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
 
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>
  </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
 
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>
  </Version>
</ListVersionsResult>
父主题： 桶的基础操作