List Object

2023-02-19 18:32:09

List Object

返回存储桶中的部分或全部(最多 1,000 个)对象。

请求语法

GET /?delimiter=Delimiter&marker=Marker&max-keys=MaxKeys&prefix=Prefix HTTP/1.1
Host: Bucket.s3-us-east-1.ossfiles.com

URI 请求参数

名称 描述 类型
Bucket 存储桶名称 字符串
prefix 列举以指定的字符串prefix开头的对象。 字符串
marker 列举桶内对象列表时,指定一个标识符,从该标识符以后按字典顺序返回对象列表。该字段仅用于非多版本列举。 字符串
max-keys 指定返回的最大对象数,返回的对象列表将是按照字典顺序的最多前max-keys个对象,范围是[1,1000],超出范围时,按照默认的1000进行处理。 整数型
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。 字符串
key-marker 列举对象时的起始位置。该字段仅用于多版本列举。类型:上次请求返回体的NextKeyMarker值 字符串

请求消息头

该请求没有请求消息头。


请求正文

该请求没有请求正文。


请求元素

该请求没有请求元素。


响应语法

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
   <IsTruncated>boolean</IsTruncated>
   <Marker>string</Marker>
   <NextMarker>string</NextMarker>
   <Contents>
      <ETag>string</ETag>
      <Key>string</Key>
      <LastModified>timestamp</LastModified>
      <Owner>
         <DisplayName>string</DisplayName>
         <ID>string</ID>
      </Owner>
      <Size>integer</Size>
      <StorageClass>string</StorageClass>
   </Contents>
   <Name>string</Name>
   <Prefix>string</Prefix>
   <Delimiter>string</Delimiter>
   <MaxKeys>integer</MaxKeys>
   <CommonPrefixes>
      <Prefix>string</Prefix>
   </CommonPrefixes>
</ListBucketResult>

响应元素

名称 描述 类型
IsTruncated 表明是否本次返回的ListBucketResult结果列表被截断。“true”表示本次没有返回全部结果;“false”表示本次已经返回了全部结果。 逻辑型
Marker 列举对象时的起始位置标识符。 字符串
NextMarker 如果本次没有返回全部结果,响应请求中将包含此字段,用于标明本次请求列举到的最后一个对象。后续请求可以指定Marker等于该值来列举剩余的对象。 字符串
Contents 对象的元数据信息。 容器
Contents.ETag 对象的base64编码的128位MD5摘要。ETag是对象内容的唯一标识,可以通过该值识别对象内容是否有变化。比如上传对象时ETag为A,下载对象时ETag为B,则说明对象内容发生了变化。实际的ETag是对象的哈希值。ETag只反映变化的内容,而不是其元数据。上传的对象或拷贝操作创建的对象,通过MD5加密后都有唯一的ETag。(当对象是服务端加密的对象时,ETag值不是对象的MD5值,而是通过服务端加密计算出的唯一标识。) 字符串
Contents.Key 对象名 字符串
Contents.LastModified 对象最近一次被修改的时间(UTC时间) 时间
Contents.Owner 所有者信息 容器
Contents.Owner.DisplayName 所有者ID 字符串
Contents.Owner.ID 所有者ID 字符串
Contents.Size 对象的字节数。 整数型
Contents.StorageClass 对象的存储类型 字符串
Name 桶名称 字符串
Prefix 对象名的前缀,表示本次请求只列举对象名能匹配该前缀的所有对象。 字符串
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。
字符串
MaxKeys 列举时最多返回的对象个数。 字符串
CommonPrefixes 请求中带delimiter参数时,返回消息带CommonPrefixes分组信息。 字符串
CommonPrefixes.Prefix 公共前缀 字符串

响应消息头

该请求没有响应消息头。


示例

请求示例

GET / HTTP/1.1
Authorization: AWS4-HMAC-SHA256 Credential=2421a691b4ed625de19f6f92677b6459/20230117/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=ae1fa0bdf20c00cf943df38c21f7a2fbd2ba6a84bf036b68ffa1cb30b8e6d3ed
Content-length: 0
Host: bucket.s3-us-east-1.ossfiles.com
X-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-amz-date: 20230117T063615Z

返回示例

HTTP/1.1 200 OK
Content-type: application/xml
Date: Tue, 17 Jan 2023 06:36:17 GMT
x-amz-id-2: fcbd0de4913e4b8a9e3fc62fc595ca43
x-amz-request-id: ded7dde00b584aad80ee13f13df5c483

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>aatest</Name>
    <Prefix/>
    <KeyCount>3</KeyCount>
    <Marker/>
    <MaxKeys/>
    <IsTruncated>false</IsTruncated>
    <NextMarker/>
    <Contents>
        <Key>1.mp4</Key>
        <LastModified>2022-06-08T20:53:44.000Z</LastModified>
        <ETag>e8a80902e1030e40f8b8e744293e34e9</ETag>
        <Size>1977942016</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>c2287ffd54231d96dfdfe69e798965ca</ID>
            <DisplayName>c2287ffd54231d96dfdfe69e798965ca</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>测试文件夹/</Key>
        <LastModified>2022-06-22T18:08:03.000Z</LastModified>
        <ETag>da437080e6ece71e5490681568e54ec2</ETag>
        <Size>0</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>c2287ffd54231d96dfdfe69e798965ca</ID>
            <DisplayName>c2287ffd54231d96dfdfe69e798965ca</DisplayName>
        </Owner>
    </Contents>
</ListBucketResult>