GET Bucket

最近更新时间:2019-06-18 20:06:16

GET Bucket (List Objects)


描述

此 GET 操作将指定罗列空间中的部分或全部(上限1000)的对象。
用户可以设定请求参数来选择指定空间中所要列出的对象。

用户使用此接口,需要具有对空间的 READ 权限。

注意 如果想要列举用户空间,可以使用 GET Service 接口。

请求

语法

GET / HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}

注意:

请求参数

参数 描述 必需
delimiter 分隔符,用于对一组参数进行分割的字符。
类型: String
默认值: 无
encoding-type 指明请求KS3与KS3响应使用的编码方式。object key 可以包含任意Unicode字符。然而,XML 1.0解析器无法解析某些字符,如ASCII码中的0到10。对于这些不能被解析的字符可以添加到请求中,KS3会在响应中对他们进行编码。
类型: String
默认值: 无
有效值: url
marker 指定列举指定空间中对象的起始位置。KS3按照字母排序方式返回结果,将从给定的 marker 开始返回列表。
类型: String
默认值: 无
max-keys 设置响应体中返回的最大记录数(最后实际返回可能小于该值)。默认为1000。如果你想要的结果在1000条以后,你可以设定 marker 的值来调整起始位置。
类型: String
默认值: 1000
prefix 限定响应结果列表使用的前缀,正如你在电脑中使用的文件夹一样。
类型: String
默认值: 无

请求头部

该接口只使用常用请求头部。获取更多信息,请点击常用请求头部

请求内容

该接口不使用请求内容。

响应

响应头部

该接口可以使用所有常用响应头部。获取更多信息,常用响应头部

响应内容

名称 描述
Contents 每一个对象返回的元数据。
类型: XML metadata
父节点: ListBucketResult
CommonPrefixes 当用户指定分隔符后,KS3会返回他们的公共前缀。实际上,公共前缀包括的值类似于文件目录中的同一个目录下的子目录。值的数量不能超过最大数量。例如:指定分隔符为 /,对于notes/summer/a.txtnotes/summer/b.xml,其公共前缀为 notes/summer/
类型: String
父节点: ListBucketResult
Delimiter 分隔符,用于分割参数。分割后便于确定公共前缀。
类型: String
父节点: ListBucketResult
DisplayName 对象的名称。
类型: String
父节点: ListBucketResult.Contents.Owner
Encoding-Type KS3响应中对对象名称的编码方式。
类型: String
父节点: ListBucketResult
ETag 使用对象MD5摘要的实体标签。仅取决于对象的内容。
类型: String
父节点: ListBucketResult.Contents
ID 对象拥有者的用户ID。
类型: String
父节点: ListBucketResult.Contents.Owner
IsTruncated 是否被截断。如果对象列表记录数超过了设定的最大值,那么将会被截断。
类型: BooleanAncestor: ListBucketResult
Key 对象的 key
类型: String
父节点: ListBucketResult.Contents
LastModified 最后一次被改动的时间和日期。
类型: DateAncestor: ListBucketResult.Contents
Marker 指定列举指定空间中对象的起始位置。KS3按照字母排序方式返回结果,将从给定的 marker 开始返回列表。
类型: String
父节点: ListBucketResult
MaxKeys 响应体中返回的最大记录数。默认为1000。
类型: String
父节点: ListBucketResult
Name 用户空间的名称。
类型: String
父节点: ListBucketResult
NextMarker 当用户空间中对象列表记录数超过了最大值,会标记列表被截断(IsTruncated=true),同时返回下个记录的位置信息。用户在下次list objects的时候,可以使用该值作为marker参数。注意:当不提供delimiter参数的时候,KS3将不会返回NextMarker,如果IsTruncated为true,则可以使用返回的Contents中的最后一个key作为下次list的marker参数
类型: String
父节点: ListBucketResult
Owner 用户空间拥有者信息。
类型: String
子节点: DisplayName, ID
: ListBucketResult.Contents &##124; CommonPrefixes
Prefix 该list请求时指定的key前缀
类型: String
父节点: ListBucketResult
Size 对象的大小,按字节统计。
类型: String
父节点: ListBucketResult.Contents
StorageClass 存储类型,包括: STANDARD/STANDARD_IA/ARCHIVE
类型: String
父节点: ListBucketResult.Contents

特殊错误

该接口不返回任何特殊错误。

示例

请求示例

GET / HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyun.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain

响应示例

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>ks3-example</Name>
    <Prefix/>
    <Marker/>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>my-image.jpg</Key>
        <LastModified>2009-10-12T17:50:30.000Z</LastModified>
        <ETag>fba9dede5f27731c9771645a39863328</ETag>
        <Size>434234</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>73410125</ID>
            <DisplayName>ks3@kingsoft.com</DisplayName>
        </Owner>
    </Contents>
    <Contents>
       <Key>my-third-image.jpg</Key>
         <LastModified>2009-10-12T17:50:30.000Z</LastModified>
        <ETag>1b2cf535f27731c974343645a3985328</ETag>
        <Size>64994</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>73410125</ID>
            <DisplayName>ks3@kingsoft.com</DisplayName>
        </Owner>
    </Contents>
</ListBucketResult>

接口细节分析

  • 由于max-keys最大只能是1000,所以一次list不一定可以把所有文件都罗列出来。当返回的IsTruncated为true时,表示返回的结果被截断,也就是说这这次list还没有把所有的object都list出来,若请求参数中包含delimiter,则可以使用返回的NextMarker做为下次list的marker参数,若请求参数中不包含delimiter,则可以使用返回的Contents中的最后一个做为下次list的marker参数。

  • 通过使用prefix、delimiter可以模拟目录结构。如果设定了max-keys和delimiter,返回的文件列表数量不一定等于max-keys,有可能会小于max-keys。假设bucket下有以下几个object,
    分别是:
    movie/action/1.mp4
    movie/fun/2.mp4 movie/fun/3.mp4
    photo/1.jpg
    4.txt
    当只提供prefix=movie/fun/时,返回的结果为movie/fun/2.mp4、movie/fun/3.mp4
    当提供delimiter=/时,返回的结果为CommonPrefixes:movie/、photo/ Contents:4.txt
    当提供prefix=movie/,delimiter=/时,返回的结果为CommonPrefixes:movie/action/、movie/fun/

对不可见字符处理的说明

1、由于部分不可见字符转换xml时有异常,ks3对接口的不可见字符进行了转码

2、转码的规则

对不可见字符的十六进制数值进行转换,转换为#x{dd};如,对不可见字符0x00(空字符)转换为#x00;

具体转换列表如下:

原不可见字符(十六进制) 转换后字符
0x00 #x00;
0x01 #x01;
0x02 #x02;
0x03 #x03;
0x04 #x04;
0x05 #x05;
0x06 #x06;
0x07 #x07;
0x08 #x08;
0x0b #x0b;
0x0c #x0c;
0x0e #x0e;
0x0f #x0f;
0x10 #x10;
0x11 #x11;
0x12 #x12;
0x13 #x13;
0x14 #x14;
0x15 #x15;
0x16 #x16;
0x17 #x17;
0x18 #x18;
0x19 #x19;
0x1a #x1a;
0x1b #x1b;
0x1c #x1c;
0x1d #x1d;
0x1e #x1e;
0x1f #x1f;
0xfffe #xfffe;
0xffff #xffff;

金山云,开启您的云计算之旅

立即注册