金山云-文档中心-GET Bucket

Standard Storage Service (KS3)

View more results

Document title with current keyword not found

Description

This GET operation lists some or all (up to 1000) objects in the specified space. You can set request parameters to select the objects to be listed in the specified space.

Users need to have 'READ' permission on the space to use this interface.

Note: If you want to list user spaces, you can use the GET service interface.

Request

Grammar

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

Note:

Corresponding relationship between Endpoint and Region

SignatureValue signature algorithm

Request parameters

Parameter	Description	Necessity
delimiter	Separator character used to split a set of parameters. Type: String Default: None	No
encoding-type	Indicates the encoding used for requests KS3 and KS3 responses.`object key`can contain any Unicode character. However, the XML 1.0 parser cannot parse certain characters, such as 0 to 10 in ASCII. Characters that cannot be parsed can be added to the request, and KS3 will encode them in the response. Type: String Default: None Valid value: url	No
marker	Specifies the starting position of the listed objects in the space. KS3 returns the results alphabetically, starting with the given 'marker'. Type: String Default: None	No
max-keys	Sets the maximum number of records returned in the response body (the actual return value may be less than this value). The default is 1000. If you want results after 1000, you can set the value of 'marker' to adjust the starting position. Type: String Default: 1000	No
prefix	Limit the prefix used for the response results list, just like the folders you use on your computer. Type: String Default: None	No

Request header

This interface only uses common request headers. For more information, please click Public request headers.

Request content

The interface does not use the requested content.

Response

Response header

This interface can use all common response headers. For more information,please click Public response headers.

Response content

Name	Description
Contents	Metadata returned by each object. Type: XML metadata Parent node: ListBucketResult
CommonPrefixes	When the user specifies a separator, KS3 returns their common prefix. In fact, the value of the public prefix is similar to that of the subdirectory under the same directory in the file directory. The number of values cannot exceed the maximum number. For example, the specified separator is' / '. For ' notes / summer / a.txt ' and ' notes / summer / b.xml ', the public prefix is ' notes / summer /'. Type: String Parent node: ListBucketResult
Delimiter	Separator, which is used to divide parameters. It is convenient to determine common prefix after division. Type: String Parent node: ListBucketResult
DisplayName	The name of the object. Type: String Parent node: ListBucketResult.Contents.Owner
Encoding-Type	The encoding of the object name in the KS3 response. Type: String Parent node: ListBucketResult
ETag	How to use the tag of the object MD5 summary only depends on the content of the object. Type: String Parent node: ListBucketResult.Contents
ID	The user ID of the owner of the object. Type: String Parent node: ListBucketResult.Contents.Owner
IsTruncated	Is it truncated. If the number of object list records exceeds the set maximum, it will be truncated. Type: BooleanAncestor: ListBucketResult
Key	Object's key. Type: String Parent node: ListBucketResult.Contents
LastModified	Time and date of last modified. Type: DateAncestor: ListBucketResult.Contents
Marker	Specifies the starting location of the objects in the space to list. KS3 returns the results alphabetically, starting with the given 'marker'. Type: String Parent node: ListBucketResult
MaxKeys	The maximum number of records returned in the response body. The default value is 1000. Type: String Parent node: ListBucketResult
Name	The name of the user space. Type: String Parent node: ListBucketResult
NextMarker	When the number of object list records in user space exceeds the maximum, the list will be marked as truncated (IsTruncated=true), and the location information of the next record will be returned. The user can use this value as the 'marker' parameter next time 'list objects'. Note: when the 'delimiter' parameter is not provided, KS3 will not return 'NextMarker'. If 'IsTruncated' is true, the last key in the returned 'Contents' can be used as the' marker 'parameter of the next list Type: String Parent node: ListBucketResult
Owner	User space owner information. Type: String Child nodes: DisplayName, ID : ListBucketResult.Contents &##124; CommonPrefixes
Prefix	The 'key' prefix specified in the list request. Type: String Parent node: ListBucketResult
Size	Object size, in bytes. Type: String Parent node: ListBucketResult.Contents
StorageClass	Storage types, including: STANDARD/STANDARD_IA/ARCHIVE Type: String Parent node: ListBucketResult.Contents

Special errors

The interface does not return any special errors.

Example

Request example

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

Response example

<?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>

Interface details

Since max-keys can only be 1000 at most, a list operation does not necessarily list all files. When the returned 'IsTruncated' is true, the returned result is truncated. That is to say, this list has not listed all objects. If the request parameter contains' delimiter ', the returned' NextMarker 'can be used as the' marker 'parameter of the next list. If the request parameter does not contain' delimiter ', the last one of the returned' Contents' can be used as the 'marker' parameter of the next list.
The directory structure can be simulated by using prefix and delimiter. If max-keys and delimiter are set, the number of file lists returned is not necessarily equal to max-keys, which may be less than max-keys. Suppose there are the following objects in the bucket, They are: movie/action/1.mp4
movie/fun/2.mp4 movie/fun/3.mp4
photo/1.jpg
4.txt
When only prefix = movie / fun / is provided, the returned results are movie / fun / 2.mp4, movie / fun / 3.mp4 When the delimiter = / is provided, the returned results are commonprefixes: movie /, photo / contents: 4.txt When prefix = movie /,delimiter = / are provided, the returned results are commonprefixes: movie / action /, movie / fun/
Description of invisible character processing

1、Due to the exception of converting some invisible characters into XML, KS3 transcodes the invisible characters of the interface.

2、Rules of transcoding

Convert the hexadecimal value of the invisible character to #x{dd}; for example, convert the invisible character 0x00 (empty character) to #x00;

The conversion list is as follows:

Invisible character (HEX)	Converted character
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、Transcoding example

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

}

On this page

Previous:PUT Bucket ACL

Next:GET Bucket logging

Pure ModeNormal Mode

Pure Mode

Click to preview the document content in full screen