You can call this operation to query information about all objects in a bucket.

Note The user-defined object metadata is not returned for the GetBucket request.

Request syntax

GET / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request parameters

Parameter Type Required Description
Delimiter String No

Specifies the character used to group object names. If you specify the Delimiter parameter in the request, the response contains the CommonPrefixes element. CommonPrefixes is a group of all objects whose names contain the same string between the prefix and the first occurrence of the delimiter after the prefix.

Default value: none

Marker String No

Specifies the name of the bucket after which the list begins. If this parameter is specified, buckets whose names are alphabetically greater than the Marker parameter value are returned.

The Marker parameter is used to list the returned objects by pages, and its value must be less than 1,024 bytes in length.

Even if the specified marker does not exist in the list during a conditional query, the list starts from the object whose name is alphabetically greater than the Marker parameter value.

Default value: none

Max-keys String No

Specifies the maximum number of objects to return.

Valid values: 1 to 1000

Default value: 100

Note If the listing cannot be completed at one time because Max-keys is specified, an additional <NextMarker> is added as the marker for next listing.
Prefix String No

Specifies the prefix that the returned object names must contain.

If Prefix is set to a folder name in the request, the objects whose names contain this prefix are listed, including all recursive objects and subfolders in the folder.

If you specify Prefix and set Delimiter to a forward slash (/), only the objects in the folder are listed. The subfolders in the folder are returned in CommonPrefixes. Recursive objects and folders in the subfolders are not listed.

For example, a bucket contains three objects: fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi. If Prefix is set to fun/, the three objects are returned. If Prefix is set to fun/ and Delimiter is set to a forward slash (/), fun/test.jpg and fun/movie/are returned.

Note
  • The parameter value must be less than 1,024 bytes in length.

  • If you specify a prefix to query objects, the returned objects still contain the prefix.

Default value: none

Encoding-type String No

Specifies the encoding type of the object name in the response.

Default value: none

Valid value: url

Note Delimiter, Marker, Prefix, NextMarker, and Key are UTF-8 encoded. If Delimiter, Marker, Prefix, NextMarker, and object names contain control characters that are not supported by XML 1.0 standard, you can specify Encoding-type to encode Delimiter, Marker, Prefix, NextMarker, and Key in the returned results.

Response elements

Element Type Description
Contents Container

Indicates the container that stores the returned object metadata.

Parent node: ListBucketResult

CommonPrefixes String

If the Delimiter parameter is specified in the request, the response contains the CommonPrefixes element. The element indicates a group of all objects whose names contain the same string between the prefix and the first occurrence of the delimiter after the prefix.

Parent node: ListBucketResult

Delimiter String

Indicates the character used to group object names. If you specify the Delimiter parameter in the request, the response contains the CommonPrefixes element. CommonPrefixes is a group of all objects whose names contain the same string between the prefix and the first occurrence of the delimiter after the prefix.

Parent node: ListBucketResult

EncodingType String

Indicates the encoding type of the object name in the response. In addition, you can use the Encoding-type parameter to encode the following parameters in the response: Delimiter, Marker, Prefix, NextMarker, and Key.

Parent node: ListBucketResult

DisplayName String

Indicates the name of the object owner.

Parent node: ListBucketResult.Contents.Owner

ETag String

Indicates the entity tag (ETag). An ETag is created when the object is created to identify the content of an object.

Parent node: ListBucketResult.Contents

For an object created with a PutObject request, the ETag value of the object is the MD5 value of the object content. If an object is created by using another method, the ETag value of the object is the UUID of the object content. The ETag value of an object can be used to check whether the object content has changed. However, we recommend that you not use the ETag of an object as the MD5 value of the object to verify data integrity.

ID String

Indicates the user ID of the bucket owner.

Parent node: ListBucketResult.Contents.Owner

IsTruncated Boolean

Indicates whether the returned results are truncated.

Valid values: true and false
  • true indicates that not all of the results are returned this time.
  • false indicates that all of the results have been returned this time.

Parent node: ListBucketResult

Key String

Indicates the key of the object.

Parent node: ListBucketResult.Contents

LastModified Date

Indicates the latest modification time of the object.

Parent node: ListBucketResult.Contents

ListBucketResult Container

Indicates the container that stores the result of the GetBucket request.

Child nodes: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, NextMarker, and Contents

Parent node: none

Marker String

Indicates the starting point for returning objects upon the GetBucket (ListObject) request.

Parent node: ListBucketResult

MaxKeys String

Indicates the maximum number of buckets returned each time.

Parent node: ListBucketResult

Name String

Indicates the name of the bucket.

Parent node: ListBucketResult

Owner Container

Indicates the container that stores the information about the bucket owner.

Child node: DisplayName and ID

Parent node: ListBucketResult

Prefix String

Indicates the prefix that the returned object names must contain.

Parent node: ListBucketResult

Size String

Indicates the size of the returned object content. Unit: bytes.

Parent node: ListBucketResult.Contents

StorageClass String

Indicates the storage class of the object.

Parent node: ListBucketResult.Contents

Examples

  • Sample request for simple GetBucket
    GET / HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykbo****

    Sample response

    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906****
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Content-Type: application/xml
    Content-Length: 1866
    Connection: keep-alive
    Server: AliyunOSS
    <? xml version="1.0" encoding="UTF-8"? >
    <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
    <Name>oss-example</Name>
    <Prefix></Prefix>
    <Marker></Marker>
    <MaxKeys>100</MaxKeys>
    <Delimiter></Delimiter>
    <IsTruncated>false</IsTruncated>
    <Contents>
          <Key>fun/movie/001.avi</Key>
          <LastModified>2012-02-24T08:43:07.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user-example</DisplayName>
          </Owner>
    </Contents>
    <Contents>
          <Key>fun/movie/007.avi</Key>
          <LastModified>2012-02-24T08:43:27.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user-example</DisplayName>
          </Owner>
    </Contents>
    <Contents>
          <Key>fun/test.jpg</Key>
          <LastModified>2012-02-24T08:42:32.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user-example</DisplayName>
          </Owner>
    </Contents>
    <Contents>
          <Key>oss.jpg</Key>
          <LastModified>2012-02-24T06:07:48.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user-example</DisplayName>
          </Owner>
    </Contents>
    </ListBucketResult>
  • Sample request that has the Prefix parameter specified
    GET /? prefix=fun HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykbo****

    Sample response

    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906****
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Content-Type: application/xml
    Content-Length: 1464
    Connection: keep-alive
    Server: AliyunOSS
    <? xml version="1.0" encoding="UTF-8"? >
    <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
    <Name>oss-example</Name>
    <Prefix>fun</Prefix>
    <Marker></Marker>
    <MaxKeys>100</MaxKeys>
    <Delimiter></Delimiter>
    <IsTruncated>false</IsTruncated>
    <Contents>
          <Key>fun/movie/001.avi</Key>
          <LastModified>2012-02-24T08:43:07.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user_example</DisplayName>
          </Owner>
    </Contents>
    <Contents>
          <Key>fun/movie/007.avi</Key>
          <LastModified>2012-02-24T08:43:27.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user_example</DisplayName>
          </Owner>
    </Contents>
    <Contents>
          <Key>fun/test.jpg</Key>
          <LastModified>2012-02-24T08:42:32.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user_example</DisplayName>
          </Owner>
    </Contents>
    </ListBucketResult>
  • Sample request that has the Prefix and Delimiter parameters specified
    GET /? prefix=fun/&delimiter=/ HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:DNrnx7xHk3sgysx7I8U9I9IY****

    Sample response

    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906****
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Content-Type: application/xml
    Content-Length: 712
    Connection: keep-alive
    Server: AliyunOSS
    <? xml version="1.0" encoding="UTF-8"? >
    <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
    <Name>oss-example</Name>
    <Prefix>fun/</Prefix>
    <Marker></Marker>
    <MaxKeys>100</MaxKeys>
    <Delimiter>/</Delimiter>
    <IsTruncated>false</IsTruncated>
    <Contents>
          <Key>fun/test.jpg</Key>
          <LastModified>2012-02-24T08:42:32.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user_example</DisplayName>
          </Owner>
    </Contents>
    <CommonPrefixes>
          <Prefix>fun/movie/</Prefix>
    </CommonPrefixes>
    </ListBucketResult>

SDKs

The SDKs of the GetBucket operation for various programming languages are as follows:

Error codes

Error code HTTP status code Description
NoSuchBucket 404 The error message returned because the specified bucket does not exist.
AccessDenied 403 The error message returned because you are not authorized to view information about the bucket.
InvalidArgument 400
  • The error message returned because the value of Max-keys is less than 0 or greater than 1000.
  • The error message returned because the length of Prefix, Marker, or Delimiter is invalid.