All Documents
Current Document

Content is empty

If you don't find the content you expect, please try another search term

Documentation

GET Bucket

Last updated:2021-09-14 16:18:03

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:

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 keycan 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
Pure ModeNormal Mode

Pure Mode

Click to preview the document content in full screen
Feedback