All Products
Search
Document Center

Object Storage Service:GetBucket (ListObjects)

Last Updated:Jul 21, 2023

Lists the information about all objects in a bucket.

Usage notes

  • The GetBucket (ListObjects) operation has been updated to GetBucketV2 (ListObjectsV2). We recommend that you use GetBucketV2 (ListObjectsV2) when you develop your applications. To provide backward compatibility, Object Storage Service (OSS) continues to support the GetBucket (ListObjects) operation. For more information about GetBucketV2 (ListObjectsV2), see ListObjectsV2 (GetBucketV2).
  • The user metadata of objects is not returned for GetBucket (ListObjects) requests.
  • You are charged based on the number of PUT requests when you call the GetBucket (ListObjects) operation. For more information, see API operation calling fees.

Request syntax

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

Request headers

A ListObjects (GetBucket) request contains only common request headers such as Authorization and Host. For more information about common request headers, see Common request headers.

Request parameters

ParameterTypeRequiredExampleDescription
delimiterStringNo/The character that is used to group objects by name. If you specify the delimiter parameter in the request, the response contains the CommonPrefixes parameter. The objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in CommonPrefixes.

This header is empty by default.

markerStringNotest1.txtThe name of the object after which the ListObjects (GetBucket) operation starts. If this parameter is specified, objects whose names are alphabetically greater than the marker value are returned.

The marker parameter is used to list the returned objects by page, and the marker value must be smaller 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 value.

This header is empty by default.

max-keysStringNo200The maximum number of objects that you want to return. If the list operation cannot be complete at a time because the max-keys parameter is specified, the NextMarker element is included in the response as the marker for the next list operation.

Valid values: 1 to 1000

Default value: 100

prefixStringNofunThe prefix that the names of the returned objects must contain.
  • The prefix value must be smaller than 1,024 bytes in length.
  • If you specify a prefix to query objects, the names of the returned objects still contain the prefix.

If prefix is set to a directory name in the request, the objects whose names contain this prefix are listed, which includes all objects and subdirectories in the directory.

If prefix is specified and delimiter is set to a forward slash (/), only objects in the directory are listed. The names of the subdirectories in the directory are returned in the CommonPrefixes parameter. However, objects and directories in the subdirectories are not listed.

For example, a bucket contains the following 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.

This header is empty by default.

encoding-typeStringNoURLThe encoding type of the content in the response.

This header is empty by default.

Valid value: URL

Important The values of delimiter, marker, prefix, NextMarker, and Key are UTF-8 encoded. If the value of delimiter, marker, prefix, NextMarker, or Key contains a control character that is not supported by the XML 1.0 standard, you can specify the encoding-type parameter to encode the value in the response.

Response parameters

ParameterTypeExampleDescription
ListBucketResultContainerN/AThe container that stores the result of the GetBucket (ListObjects) request.

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

Parent nodes: none

NameStringoss-exampleThe name of the bucket.

Parent nodes: ListBucketResult

PrefixStringfun/The prefix contained in the returned object names.

Parent nodes: ListBucketResult or CommonPrefixes

MarkerStringtest1.txtThe name of the object after which the list operation begins.

Parent nodes: ListBucketResult

MaxKeysString100The maximum number of returned objects in the response.

Parent nodes: ListBucketResult

DelimiterString/The character that is used to group objects by name. The objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in CommonPrefixes.

Parent nodes: ListBucketResult

EncodingTypeStringurlThe encoding type of the content in the response. If you specify the encoding-type parameter in the request, the following parameters in the response are encoded: Delimiter, Marker, Prefix, NextMarker, and Key.

Parent nodes: ListBucketResult

IsTruncatedEnumerated stringfalseIndicates whether the returned results are truncated.
Valid values: true and false
  • true indicates that not all results are returned this time.
  • false indicates that all results are returned this time.

Parent nodes: ListBucketResult

NextMarkerStringtest100.txtThe position from which the next list operation starts.

Parent nodes: ListBucketResult

ContentsContainerN/AThe container that stores the metadata of the returned objects.

Parent nodes: ListBucketResult

KeyStringfun/test.jpgThe name of the object.

Parent nodes: ListBucketResult.Contents

LastModifiedTime2012-02-24T08:42:32.000ZThe time when the returned objects were last modified.

Parent nodes: ListBucketResult.Contents

ETagString5B3C1A2E053D763E1B002CC607C5A0FE1****The entity tag (ETag). An ETag is created when an object is created to identify the content of the object.
  • If an object is created by calling the PutObject operation, the ETag value of the object is the MD5 hash of the object content.
  • If an object is created by using another method, the ETag value is not the MD5 hash of the object content but a unique value that is calculated based on a specific rule.
  • The ETag of an object can be used to check whether the object content is modified. However, we recommend that you use the MD5 hash of an object rather than the ETag value of the object to verify data integrity.

Parent nodes: ListBucketResult.Contents

TypeStringNormalThe type of the object. Valid values:
  • Normal: The object is uploaded by using simple upload.
  • Multipart: The object is uploaded by using multipart upload.
  • Appendable: The object is uploaded by using append upload.
SizeString344606The size of the returned object. Unit: bytes.

Parent nodes: ListBucketResult.Contents

StorageClassStringStandardThe storage class of the object.

Parent nodes: ListBucketResult.Contents

RestoreInfoStringongoing-request="true"The restoration status of the object.
  • If no RestoreObject requests are sent or the requests expire, this field is not included in the response.
  • If a RestoreObject request is sent and the object is still being restored, the returned RestoreInfo value is ongoing-request="true".
  • If a RestoreObject request is sent and the object is restored, the returned RestoreInfo value is in the following format: ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT". In the returned RestoreInfo value, the expiry-date field indicates the time before which the restored object can be read.
OwnerContainerN/AThe container that stores information about the bucket owner.

Child nodes: DisplayName and ID

Parent nodes: Contents

IDString0022012****The ID of the bucket owner.

Parent nodes: ListBucketResult.Contents.Owner

DisplayNameStringuser_exampleThe name of the object owner.

Parent nodes: ListBucketResult.Contents.Owner

CommonPrefixesContainerN/AIf the Delimiter parameter is specified in the request, the response contains the CommonPrefixes element. The objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in CommonPrefixes.

Parent nodes: ListBucketResult

For more information about the common response headers such as x-oss-request-id and Content-Type included in the response to a ListObjects (GetBucket) request, see Common response headers.

Examples

  • Sample requests for the simple ListObjects (GetBucket) operation
    GET / HTTP/1.1
    Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otf****:BC+oQIXVR2/ZghT7cGa0ykbo****

    Sample responses

    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>examplebucket</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 requests that have the prefix parameter specified
    GET /?prefix=fun HTTP/1.1
    Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otf****:BC+oQIXVR2/ZghT7cGa0ykbo****

    Sample responses

    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>examplebucket</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 requests that have the prefix and delimiter parameters specified
    GET /?prefix=fun/&delimiter=/ HTTP/1.1
    Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otf****:DNrnx7xHk3sgysx7I8U9I9IY****

    Sample responses

    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>examplebucket</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>
  • Sample requests that have the marker parameter specified

    In this example, the max-keys parameter is set to 2, which indicates that the maximum number of objects to return is 2.

    GET /?max-keys=2&marker=test1.txt HTTP/1.1
    Host: examplebucket.oss-cn-shenzhen.aliyuncs.com
    Accept-Encoding: identity
    Accept: */*
    Connection: keep-alive
    User-Agent: aliyun-sdk-python/2.11.0(Darwin/18.2.0/x86_64;3.4.1)
    date: Tue, 26 May 2020 08:39:48 GMT
    authorization: OSS qn6qrrqxo2oawuk53otf****:DNrnx7xHk3sgysx7I8U9I9IY****

    Sample responses

    The NextMarker element in the response indicates the marker for the next list operation.

    HTTP/1.1 200 OK
    Server: AliyunOSS
    Date: Tue, 26 May 2020 08:39:48 GMT
    Content-Type: application/xml
    Content-Length: 1032
    Connection: keep-alive
    x-oss-request-id: 5ECCD5D4881816373582xxx
    x-oss-server-time: 3
    
    <?xml version="1.0" encoding="UTF-8"?>
    <ListBucketResult>
      <Name>examplebucket</Name>
      <Prefix></Prefix>
      <Marker>test1.txt</Marker>
      <MaxKeys>2</MaxKeys>
      <Delimiter></Delimiter>
      <EncodingType>url</EncodingType>
      <IsTruncated>true</IsTruncated>
      <NextMarker>test100.txt</NextMarker>
      <Contents>
        <Key>test10.txt</Key>
        <LastModified>2020-05-26T07:50:18.000Z</LastModified>
        <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
        <Type>Normal</Type>
        <Size>1</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
          <ID>1305433xxx</ID>
          <DisplayName>1305433xxx</DisplayName>
        </Owner>
      </Contents>
      <Contents>
        <Key>test100.txt</Key>
        <LastModified>2020-05-26T07:50:20.000Z</LastModified>
        <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
        <Type>Normal</Type>
        <Size>1</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
          <ID>1305433xxx</ID>
          <DisplayName>1305433xxx</DisplayName>
        </Owner>
      </Contents>
    </ListBucketResult>
  • Sample requests that are sent to list all objects, including Archive or Cold Archive objects in a bucket
    In this example, the examplebucket bucket contains the following Cold Archive objects: exampleobject1.txt, exampleobject2.txt, and exampleobject3.txt. The three objects are in the following states:
    • No RestoreObject requests are sent to restore exampleobject1.txt or the RestoreObject requests sent to restore the object expire.
    • A RestoreObject request is sent to restore exampleobject2.txt and the object is being restored.
    • A RestoreObject request is sent to restore exampleobject3.txt and the object is restored.

    Sample requests

    GET / HTTP/1.1
    Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otf****:DNrnx7xHk3sgysx7I8U9I9IY****

    Sample responses

    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906****
    Date: 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>examplebucket</Name>
      <Prefix></Prefix>
      <Marker></Marker>
      <MaxKeys></MaxKeys>
      <Delimiter></Delimiter>
      <IsTruncated>false</IsTruncated>
      <Contents>
            <Key>exampleobject1.txt</Key>
            <LastModified>2020-06-22T11:42:32.000Z</LastModified>
            <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>ColdArchive</StorageClass>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user-example</DisplayName>
            </Owner>
      </Contents>
      <Contents>
            <Key>exampleobject2.txt</Key>
            <LastModified>2020-06-22T11:42:32.000Z</LastModified>
            <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>Standard</StorageClass>
            <RestoreInfo>ongoing-request="true"</RestoreInfo>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user-example</DisplayName>
            </Owner>
      </Contents>
      <Contents>
            <Key>exampleobject3.txt</Key>
            <LastModified>2020-06-22T11:42:32.000Z</LastModified>
            <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>Standard</StorageClass>
            <RestoreInfo>ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"</RestoreInfo>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user-example</DisplayName>
            </Owner>
      </Contents>
    </ListBucketResult>

OSS SDKs

You can use OSS SDKs for the following programming languages to call the ListObjects (GetBucket) operation:

Error codes

Error codeHTTP status codeDescription
NoSuchBucket404The error message returned because the requested bucket does not exist. Check whether the name of the requested bucket complies with the naming rules.
AccessDenied403The error message returned because you do not have the permissions to access the bucket. Only the bucket owner and RAM users who have the oss:ListObjects permission can access the bucket.
InvalidArgument400
  • The error message returned because the max-keys value is less than 0 or greater than 1,000.
  • The error message returned because the length of the value of prefix, marker, or delimiter is invalid.