GET Bucket(ListObjects)

描述

注：
ListObjects接口已有新版本接口ListObjectsV2。
推荐您在开发应用程序时使用较新的版本ListObjectsV2。
为保证向后兼容，KS3仍然支持List Objects接口。
有关ListObjectsV2的更多信息，请参见ListObjectsV2。

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

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

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

请求

语法

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

注意：

• endpoint与Region对应关系
• SignatureValue签名算法

请求参数

参数	描述	必需
delimiter	分隔符，用于对一组参数进行分割的字符。 类型: String 默认值: 无 示例：/	否
marker	指定列举指定空间中对象的起始位置。KS3按照字母排序方式返回结果，将返回大于指定的 marker 的文件列表。 类型: String 默认值: 无 示例：1.txt	否
max-keys	设置响应体中返回的最大记录数（最后实际返回可能小于该值）。默认为1000。如果你想要的结果在1000条以后，你可以设定 marker 的值来调整起始位置。 如参数携带了delimiter，max-keys默认为100。 类型: String 默认值: 1000	否
prefix	限定响应结果列表使用的前缀，正如你在电脑中使用的文件夹一样。 类型: String 默认值: 无	否

请求头部

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

请求内容

该接口不使用请求内容。

响应

响应头部

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

响应内容

名称	描述
Name	用户空间的名称。 类型: String 父节点: ListBucketResult
Prefix	该list请求时指定的key前缀 类型: String 父节点:ListBucketResult
MaxKeys	响应体中返回的最大记录数。默认为1000。 类型: String 父节点: ListBucketResult
Delimiter	分隔符，用于分割参数。分割后便于确定公共前缀。 类型: String 父节点: ListBucketResult
CommonPrefixes	当用户指定分隔符后，KS3会返回他们的公共前缀。实际上，公共前缀包括的值类似于文件目录中的同一个目录下的子目录。值的数量不能超过最大数量。例如：指定分隔符为 /,对于notes/summer/a.txt 和 notes/summer/b.xml，其公共前缀为 notes/summer/。 类型: String 父节点: ListBucketResult
Marker	指定列举指定空间中对象的起始位置。KS3按照字母排序方式返回结果，将从给定的 marker 开始返回列表。 类型: String 父节点: ListBucketResult
NextMarker	当用户空间中对象列表记录数超过了最大值，会标记列表被截断(IsTruncated=true)，同时返回下个记录的位置信息。用户在下次list objects的时候，可以使用该值作为marker参数。注意：当不提供delimiter参数的时候，KS3将不会返回NextMarker,如果IsTruncated为true，则可以使用返回的Contents中的最后一个key作为下次list的marker参数 类型: String 父节点: ListBucketResult
IsTruncated	是否被截断。如果对象列表记录数超过了设定的最大值，那么将会被截断。 类型: BooleanAncestor: 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	对象的名称。 类型: 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>73410125</ID>
            <DisplayName>[email protected]</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>[email protected]</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;

3. 转码示例

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);
   }

}