金山云-文档中心-GET Bucket（ListObjects）

对象存储(KS3)

查看更多结果

未找到含当前关键字的文档标题

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

API文档

Bucket相关

基本操作

GET Bucket（List Objects）

最近更新时间：2023-10-30 15:36:17

描述

此GET操作将列举存储空间中的部分或全部（上限1000）对象。用户可以设置请求参数来指定所要列出的对象。

注意事项

GetBucket（List Objects）接口已修订为List Objects V2，推荐您使用新版本接口List Objects V2。
为保证向后兼容，KS3仍然支持Get Bucket（List Objects）接口。
用户使用此接口，需要具有对空间的ks3:ListBucket权限。
如果想要列举用户空间，可以使用List Buckets（GET Service）接口。

请求

语法

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

注意：

endpoint与Region对应关系

SignatureValue签名算法

请求参数

参数	描述	必需
delimiter	对Object名字进行分组的字符。将第一次出现Delimiter字符之间的Object作为一组元素CommonPrefixes。类型: String 默认值: 无示例：`/`	否
marker	指定列举空间对象的起始对象。KS3按照字母排序方式返回结果，将返回大于指定的 `marker` 的文件列表。类型: String 默认值: 无示例：1.txt	否
max-keys	指定返回`Object`的最大数（最后实际返回可能小于该值）。如果你想要的结果在1000条以后，你可以设定 `marker` 的值来调整起始位置。取值：[1,1000]。当大于1000时，最多返回1000条记录类型: String 默认值: 1000。如果请求参数包含delimiter，则默认值与最大值均为100	否
prefix	限定响应结果列表使用的前缀，正如你在电脑中使用的文件夹一样。类型: String 默认值: 无	否

请求头部

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

请求内容

该接口不使用请求内容。

响应

响应头部

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

响应内容

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

特殊错误

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

示例

列出所有对象

请求示例

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

响应示例

HTTP/1.1 200 OK
x-kss-request-id:f7rcat80molobs77l9ib7npolmpg****
Date: Fri, 12 Aug 2022 08:07:21 GMT
Content-Type: application/xml
Server: KS3
              
<?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>7341****</ID>
            <DisplayName>7341****</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>7341****</ID>
            <DisplayName>7341****</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>myks3</Key>
        <LastModified>2009-10-12T17:50:30.000Z</LastModified>
        <ETag>d41d8cd98f00b204e9800998ecf8427e</ETag>
        <Size>58772</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>7341****</ID>
            <DisplayName>7341****</DisplayName>
        </Owner>
    </Contents>
</ListBucketResult>

带prefix参数的示例

请求示例

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

响应示例

HTTP/1.1 200 OK
x-kss-request-id:f7rcat80molobs77l9ib7npolmpg****
Date: Fri, 12 Aug 2022 08:07:21 GMT
Content-Type: application/xml
Server: KS3
              
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>ks3-example</Name>
    <Prefix>my/</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>7341****</ID>
            <DisplayName>7341****</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>7341****</ID>
            <DisplayName>7341****</DisplayName>
        </Owner>
    </Contents>
</ListBucketResult>

带prefix和delimiter参数的示例

请求示例

GET /?prefix=my&delimiter=/ HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain

响应示例

HTTP/1.1 200 OK
x-kss-request-id:f7rcat80molobs77l9ib7npolmpg****
Date: Fri, 12 Aug 2022 08:07:21 GMT
Content-Type: application/xml
Server: KS3
              
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>ks3-example</Name>
    <Prefix>my</Prefix>
    <Marker/>
    <MaxKeys>1000</MaxKeys>
    <Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
    <Contents>
        <Key>myks3</Key>
        <LastModified>2009-10-12T17:50:30.000Z</LastModified>
        <ETag>d41d8cd98f00b204e9800998ecf8427e</ETag>
        <Size>58772</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>7341****</ID>
            <DisplayName>7341****</DisplayName>
        </Owner>
    </Contents>
    <CommonPrefixes>
        <Prefix>my/</Prefix>
    </CommonPrefixes>
</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/

对不可见字符处理的说明

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

对不可见字符的十六进制数值进行转换，转换为#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;

转码示例

import java.util.ArrayList;
import java.util.List;

public class DecodeInvalidStr {

	public static void main(String[] args) {
		String str = decodeInvalidStr("test#x1f;char#x1e;hello#xfffe;transfer");
		System.out.println(str);

	}
	
	 public static String decodeInvalidStr(String str) { 
         if(str == null) { 
             return null; 
         }
           List<Character> newChar = new ArrayList<Character>();
         char[] array = str.toCharArray(); 
         int skipIndex = -1;
         for (int i = 0, length = array.length; i < length; i++) { 
           if(i <= skipIndex){
                 continue;
           }
             if(array[i] == (char)'#'
                       && (i+1) < array.length
                       && array[i+1] == (char)'x'){
                 StringBuffer strChar = new StringBuffer();
                 for(int j = i+2;j<i+7;j++){
                       if(array[j] == (char)';'){
                             skipIndex = j;
                             char value =(char) Integer.parseInt(strChar.toString(), 16);
                             newChar.add(value);
                             break;
                       }else{
                             strChar.append(array[j]);
                       }
                 }
             }
             else{
                 newChar.add(array[i]);
             }
                
         } 
         return toString(newChar);
     }

   private static String toString(List<Character> newChar){
       char[] charArray = new char[newChar.size()];
       int i = 0;
       for(Character c : newChar){
           charArray[i++] = c;
       }
       return new String(charArray);
   }

}

错误码

错误码	HTTP状态码	描述
Invalid Argument	400 Bad Request	* max-keys小于0。 * max-keys类型不符合要求。
SignatureDoesNotMatch	403	使用Postman时，一些参数涉及到的特殊字符（如/）没有进行转义。

文档导读

上一篇：PUT Bucket

下一篇：GET Bucket Location

纯净模式常规模式

纯净模式

点击可全屏预览文档内容