返回存储桶中的部分或全部(最多 1,000 个)对象。
GET /?delimiter=Delimiter&marker=Marker&max-keys=MaxKeys&prefix=Prefix HTTP/1.1
Host: Bucket.s3-us-east-1.ossfiles.com
名称 | 描述 | 类型 |
---|---|---|
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>