Object Storage Service

Products

Object Storage Service

GetBucket(ListObject)

The action is used to list all Object information in assigned Bucket.

Note: Even if the access permission of Bucket is public, this action is also not allowed to be used anonymously, which requires to assign Authorization.

Request Syntax

GET / HTTP/1.1
Host: BucketName. s.jcloud.com
Date: GMT   Date     
Authorization: signatureValue#Please refer to "Identity and Access Management"

Request Parameter

During ListObject, the list can be limited through prefix, marker, delimiter and maxKeys so as to return part of results.

Name Description
delimiter is a character to group Object names. All names include assigned prefixes and the object between the first occurred delimiter characters is used as a set of elements--CommonPrefixes.
Data Type: Character string
Default value: None
marker Return the start marker of Object information sorted in dictionary order, the result does not include marker
Data Type: Character string
Default value: None
maxKeys Limit the maximum number of objects returned this time, if it is not set, it is 1000
Data Type by default: Character string
Default value: 1000
prefix Limit that the returned object key must use a prefix as prefix. It is noted that when using prefix for query, the returned key will still include prefix.
Data Type: Character string
Default value: None

Response Elements

Name Description
Name Bucket Name
Type: Character string
Prefix Start prefix of this query result
Type: Character string
Marker Mark the start point of this List Object.
Type: Character string
NextMarker Start point of next List Object.
Type: Character string
Delimiter is a character to group Object names. All names include assigned prefixes and the object between the first occurred delimiter characters is used as a set of elements--CommonPrefixes.
Type: Character string
MaxKeys Maximum quantity of returned results in response requests.
Type: int
HasNext Indicate whether all results have been returned; "true" represents that this time has not returned all results; "false" represents that this time has returned all results.
Type: Boolean
Effective value: true, false
Contents Save a collection of each returned Object meta.
Type: List
Key
Type of
Key
ETag ETag is Hash value of Object in JD Cloud Storage, which only reflect data contents of Object, but not includes Metadata. It shall note that ETag is not necessarily an MD5 value, when the action of PUT Object is completed, the server will generate MD5 Abstract for received data as its ETag. For Object generated by Multipart Upload, its ETag is not ContentMD5
Type of content: Character string
LastModified Time of last modification of Object.
Type: Character string
Size Number of bytes of Object.
Type: Long
StorageClass Storage Type of Object, Support "STANDARD" (standard storage), "REDUCED_REDUNDANCY" (low frequency access type) (note, only the North China machine room supports "REDUCED_REDUNDANCY")

Type: Character string
CommonPrefixes Indicate a collection of object names that end in delimiter and have a common prefix.
Type: List

Detail Analysis:

1.If accessed Bucket does not exist, including trying to access Bucket that cannot be created due to nonconventional naming, return 404 Not Found Error, error code: NoSuchBucket.

2.If there is no permission to access the Bucket, return 403 Forbidden Error, error code: AccessDenied.

3.When performing a conditional query, even if marker does not actually exist in the list, the return is also printed from the next one that conforms to the marker alphabetical order. If the max-keys are smaller than 0 or greater than 1000, the max-keys are automatically set to the default value of 1000.

4.If prefix is set as some folder name, the files that begin with this prefix can be listed, namely, all file folders and subfolders recursive under the folder. If the delimiter is also set to /, only the files in that folder will be listed under Contents in return, and the subfolder name of that folder will be listed under CommonPrefixes, files and folders recursive under the subfolder will not be displayed. When three objects exist under one bucket: jingdong/test.jpg, jingdong/dir/file, jingdong/dir/file2, if prefix is set to "jingdong/", three objects are returned; if delimiter is additionally set to "/", files "jingdong/test.jpg" will be returned in Contents and folders "jingdong/dir" will be returned in CommonPrefixes; namely, the logic of folder is implemented.

5.marker is the start marker of Object information sorted in dictionary order, the result does not include marker, marker can be set as the last Key in this list to get other Object information unreturned in this action, which is Usually used with maxKeys to implement paging.

Request Example

GET / HTTP/1.1
Host:   oss-example.s-bj.jcloud.com
Date: Tue, 11 Jul 2017   07:54:41 GMT    
Authorization: jingdong   qbS5QXpLORrvdrmb:3xo8IxIXSkA280C0Z5+lkowaAA8=
**Response Example**
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 11 Jul 2017   07:54:41 GMT
Content-Type:   application/json;charset=UTF-8
Content-Length: 900
Connection: keep-alive
Vary: Accept-Encoding
Vary: Accept-Encoding
x-jss-request-id:   99D8C1866CAC92D0
X-Trace: 200-1499759681772-0-0-19-42-42
 
{
      "Name": "oss-example",
      "Prefix": null,
      "Marker": null,
      "NextMarker":null,
      "Delimiter": null,
      "MaxKeys": 1000,
      "HasNext": false,
      "HasCommonPrefix": true,
      "Contents": [
          {
              "Key": "jingdong/dir/file",
              "LastModified": "Mon, 17 Jul 2017 12:12:39 GMT",
              "ETag": "77abd5a162ef88440102129fffbb404c",
              "Size": 2884006,
              "StorageClass": "STANDARD"
          },
          {
              "Key": "jingdong/dir/file2",
              "LastModified": "Mon, 17 Jul 2017 12:14:49 GMT",
              "ETag": "77abd5a162ef88440102129fffbb404c",
              "Size": 2884006,
              "StorageClass": "STANDARD"
          },
          {
              "Key": "jingdong/test.jpg",
              "LastModified": "Mon, 17 Jul 2017 12:12:17 GMT",
              "ETag":   "77abd5a162ef88440102129fffbb404c",
              "Size": 2884006,
              "StorageClass": "STANDARD"
          },
          {
              "Key": "test.jpg",
              "LastModified": "Mon, 17 Jul 2017 12:11:56 GMT",
              "ETag": "77abd5a162ef88440102129fffbb404c",
              "Size": 2884006,
              "StorageClass": "STANDARD"
          }
    ],
      "CommonPrefixes": [ ]
}

Request Example (inclusive of Prefix parameter)

GET   /?prefix=jingdong%2F HTTP/1.1
Host:   oss-example.s-bj.jcloud.com
Date: Tue, 11 Jul 2017   08:01:09 GMT    
Authorization: jingdong   qbS5QXpLORrvdrmb:FQZNWlNAraOLgreEflrurbNojJE= 
**Response Example (inclusive of Prefix parameter)**
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 11 Jul 2017   08:01:09 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 613
Connection: keep-alive
Vary: Accept-Encoding
Vary: Accept-Encoding
x-jss-request-id:   9CCEA5403AA5ED6E
X-Trace:   200-1499760069435-0-0-20-45-45
 
{
      "Name": "oss-example",
      "Prefix": "jingdong/",
      "Marker":   null,
      "NextMarker":null,
      "Delimiter": null,
      "MaxKeys": 1000,
      "HasNext": false,
      "HasCommonPrefix": true,
      "Contents": [
          {
              "Key": "jingdong/dir/file",
              "LastModified": "Mon, 17 Jul 2017 12:12:39 GMT",
              "ETag": "77abd5a162ef88440102129fffbb404c",
              "Size": 2884006,
              "StorageClass": "STANDARD"
          },
          {
              "Key": "jingdong/dir/file2",
              "LastModified": "Mon, 17 Jul 2017 12:14:49 GMT",
              "ETag": "77abd5a162ef88440102129fffbb404c",
              "Size": 2884006,
              "StorageClass": "STANDARD"
          },
          {
              "Key": "jingdong/test.jpg",
              "LastModified": "Mon, 17 Jul 2017 12:12:17 GMT",
              "ETag": "77abd5a162ef88440102129fffbb404c",
              "Size": 2884006,
              "StorageClass": "STANDARD"
          }
    ],
      "CommonPrefixes": [ ]
}
**Request Example (inclusive of prefix and parameter)**
GET   /?prefix=jingdong%2F&delimiter=%2F HTTP/1.1
Host: oss-example.s-bj.jcloud.com
Date: Tue, 11 Jul 2017   08:05:13 GMT    
Authorization: jingdong   qbS5QXpLORrvdrmb:jXw8QQvs6IS+JJ2EpiFMUGtgNEM=

Response Example (inclusive of prefix and parameter)

HTTP/1.1 200 OK
Server: nginx
Date: Tue, 11 Jul 2017   08:05:13 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 456
Connection: keep-alive
Vary: Accept-Encoding
Vary: Accept-Encoding
x-jss-request-id:   96F2C2E9FC9B3BE5
X-Trace:   200-1499760313279-0-0-20-45-45
 
{
      "Name": "oss-example",
      "Prefix": "jingdong/",
      "Marker": null,
      "NextMarker":null,
      "Delimiter": "/",
      "MaxKeys": 1000,
      "HasNext": false,
      "HasCommonPrefix": false,
      "Contents": [
          {
              "Key": "jingdong/test.jpg",
              "LastModified": "Mon, 17 Jul 2017 12:12:17 GMT",
              "ETag": "77abd5a162ef88440102129fffbb404c",
              "Size": 2884006,
              "StorageClass": "STANDARD"
          }
    ],
      "CommonPrefixes": [
          "jingdong/dir"
    ]
}
Update Time:2019-05-28 16:47:18