# Listing Objects in a Bucket

#### Functions

This operation lists objects in a bucket. To use this operation, you must have the permission to read the bucket.

If you specify only the bucket name in the request URI, for example GET /BucketName, OBS returns descriptions for some or all objects (a maximum of 1000 objects) in the bucket. If you also specify one or more parameters among prefix, marker, max-keys, and delimiter in the request, OBS returns a list of objects as specified.

You can also add the versions parameter to the request to list multiple versions of an object in a bucket.

#### Request Syntax

    1
    2
    3
    4

    GET / HTTP/1.1
    Host: bucketname.obs.region.example.com
    Date: date
    Authorization: authorization

#### Request Syntax (for multi-version objects)

    1
    2
    3
    4

    GET /?versions HTTP/1.1
    Host: bucketname.obs.region.example.com
    Date: date
    Authorization: authorization

#### Request Parameters

This request uses parameters to list some objects in a bucket. Table 1 describes the parameters.

Table 1 Request parameters
Parameter | Description | Mandatory
--- | --- | ---
prefix | Lists objects that begin with the specified prefix. Type: string | No
marker | Specifies a marker when listing objects in a bucket. With a marker configured, objects after this marker will be returned in alphabetical order. Type: string | No
max-keys | Sets the maximum number of objects (in alphabetical order) returned in the response body. The value ranges from 1 to 1000. If the value has exceeded the upper limit, 1,000 objects are returned by default. Type: integer | No

delimiter

Separator used to group object names. If a prefix is specified, objects with the same string from the prefix to the first delimiter are grouped into one CommonPrefixes. If no prefix is specified, objects with the same string from the first character to the first delimiter are grouped into one CommonPrefixes.

For example, there are three objects (abcd, abcde, and bbcde) in a bucket. If delimiter is set to d and prefix is set to a, objects abcd and abcde are grouped into a CommonPrefixes with abcd as the prefix. If only delimiter is set to d, objects abcd and abcde are grouped into a CommonPrefixes with abcd as the prefix, and bbcde is grouped separately into another CommonPrefixes with bbcd as the prefix.

Type: string

No

key-marker | Position to start with when objects are listed Type: string Valid value: value of NextKeyMarker in the response body of the last request | No

version-id-marker

This parameter applies only to versioning objects.

Specifies the version ID to start with when objects in a bucket are listed. Objects are listed in alphabetical order (a maximum of 1,000 objects are displayed at a time). This parameter is used together with the key-marker in the request. If the value of version-id-marker is not a version ID specified by key-marker, version-id-marker is invalid.

Type: string

Valid value: object version ID, that is, the value of NextVersionIdMarker in the response body of the last request

No

#### Request Headers

This request uses common request headers. Table 3 lists the common request headers.

#### Request Elements

This request contains no elements.

#### Response Syntax

    1
    2
    3
    4
    5
    6

    HTTP/1.1 status_code
    Date: date
    x-obs-bucket-location: region
    Content-Type: application/xml
    Content-Length: length
    <Response Body>

#### Response Headers

The response to the request uses common headers. For details, see Table 1.

#### Response Elements

This response contains the XML list of buckets owned by the user. Table 2 describes the elements.

Table 2 Response elements
Element | Description
--- | ---
ListBucketResult | A list of objects in a bucket Type: XML
Contents | Object metadata Type: XML Ancestor: ListBucketResult
CommonPrefixes | Group information. If you specify a delimiter in the request, the response contains group information in CommonPrefixes. Type: XML Ancestor: ListBucketResult
Delimiter | The delimiter parameter specified in a request Type: string Ancestor: ListBucketResult

ETag

128-bit MD5 digest of the Base64 code of an object. ETag is the unique identifier of the object content. It can be used to identify whether the object content is changed. For example, if ETag value is A when an object is uploaded and the ETag value has changed to B when the object is downloaded, it indicates that the object content is changed. The actual ETag is the hash value of the object, which only reflects the changed content rather than the metadata. An uploaded object or copied object has a unique ETag after being encrypted using MD5. (If the object is encrypted on the server side, the ETag value is not the MD5 digest of the object, but the unique identifier calculated through server-side encryption.)

Type: string

Ancestor: ListBucketResult.Contents

Type | Object type. This parameter is returned when the object type is not Normal. Type: string Ancestor: ListBucketResult.Contents
ID | Tenant ID of the object owner Type: string Ancestor: ListBucketResult.Contents.Owner
IsTruncated | Determines whether the returned list of objects is truncated. The value true indicates that the list was truncated and false indicates that the list was not truncated. Type: boolean Ancestor: ListBucketResult
Key | Object name Type: string Ancestor: ListBucketResult.Contents
LastModified | Time (UTC) when an object was last modified Type: date Ancestor: ListBucketResult.Contents
Marker | Marker for the position from which objects in a bucket will be listed Type: string Ancestor: ListBucketResult
NextMarker | A marker for the last returned object in the list. NextMarker is returned when not all the objects are listed. You can set the Marker value to list the remaining objects in follow-up requests. Type: string Ancestor: ListBucketResult
MaxKeys | Maximum number of objects returned Type: string Ancestor: ListBucketResult
Name | Name of the requested bucket Type: string Ancestor: ListBucketResult
Owner | User information, including the domain ID and username Type: XML Ancestor: ListBucketResult.Contents
Prefix | Prefix of an object name. Only objects whose names have this prefix are listed. Type: string Ancestor: ListBucketResult
Size | Object size in bytes Type: string Ancestor: ListBucketResult.Contents
StorageClass | Storage class of an object Type: enumeration Valid value: STANDARD | WARM | COLD Ancestor: ListBucketResult.Contents

Table 3 Elements in the response message for listing multi-version objects.
Element | Description
--- | ---
ListVersionsResult | Container for the list of objects (including objects with multiple version IDs) Type: container
Name | Bucket name Type: string Ancestor: ListVersionsResult
Prefix | Prefix of an object name. Only objects whose names have this prefix are listed. Type: string Ancestor: ListVersionsResult
KeyMarker | Marker for the object key from which objects will be listed Type: string Ancestor: ListVersionsResult
VersionIdMarker | Object version ID to start with when objects are listed Type: string Ancestor: ListVersionsResult
NextKeyMarker | Key marker for the last returned object in the list. NextKeyMarker is returned when not all the objects are listed. You can set the KeyMarker value to list the remaining objects in follow-up requests. Type: string Ancestor: ListVersionsResult
NextVersionIdMarker | Version ID marker for the last returned object in the list. NextVersionIdMarker is returned when not all the objects are listed. You can set the VersionIdMarker value to list the remaining objects in follow-up requests. Type: string Ancestor: ListVersionsResult
MaxKeys | Maximum number of objects returned Type: string Ancestor: ListVersionsResult
IsTruncated | Indicates whether the returned list of objects is truncated. The value true indicates that the list was truncated and false indicates that the list was not truncated. Type: boolean Ancestor: ListVersionsResult
Version | Container of version information Type: container Ancestor: ListVersionsResult
DeleteMarker | Container for objects with deletion markers Type: container Ancestor: ListVersionsResult
Key | Object name Type: string Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker
VersionId | Object version ID Type: string Ancestor: ListVersionsResult, Version | ListVersionsResult, DeleteMarker
IsLatest | Whether the object is the latest version. If the parameter value is true, the object is the latest version. Type: boolean Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker
LastModified | Time (UTC) when an object was last modified Type: date Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

ETag

128-bit MD5 digest of the Base64 code of an object. ETag is the unique identifier of the object content. It can be used to identify whether the object content is changed. The actual ETag is the hash value of the object. For example, if ETag value is A when an object is uploaded and the ETag value has changed to B when the object is downloaded, it indicates that the object content is changed. The ETag only reflects the changed content rather than the metadata. An uploaded object or copied object has a unique ETag after being encrypted using MD5.

Type: string

Ancestor: ListVersionsResult.Version

Type | Object type. This parameter is returned when the object type is not Normal. Type: string Ancestor: ListVersionsResult.Version
Size | Object size in bytes Type: string Ancestor: ListVersionsResult.Version
Owner | User information, including the domain ID and username Type: container Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker
ID | ID of the domain to which the object owner belongs Type: string Ancestor: ListVersionsResult.Version.Owner | ListVersionsResult.DeleteMarker.Owner
StorageClass | Storage class of an object Type: enumeration Ancestor: ListVersionsResult.Version
CommonPrefixes | Group information. If you specify a delimiter in the request, the response contains group information in CommonPrefixes. Type: container Ancestor: ListVersionsResult
Prefix | Indicates a different prefix in the group information in CommonPrefixes. Type: string Ancestor: ListVersionsResult.CommonPrefixes

#### Error Responses

No special error responses are involved. For details about error responses, see Table 2.

#### Sample Request 1

List all objects.

    1
    2
    3
    4
    5
    6

    GET / HTTP/1.1
    User-Agent: curl/7.29.0
    Host: examplebucket.obs.region.example.com
    Accept: */*
    Date: WED, 01 Jul 2015 02:28:25 GMT
    Authorization: OBS H4IPJX0TQTHTHEBQQCEC:KiyoYze4pmRNPYfmlXBfRTVxt8c=

#### Sample Response 1

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26

    HTTP/1.1 200 OK
    Server: OBS
    x-obs-request-id: BF260000016435D34E379ABD93320CB9
    x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSXiN7GPL/yXM6OSBaYCUV1zcY5OelWp
    Content-Type: application/xml
    Date: WED, 01 Jul 2015 02:23:30 GMT
    Content-Length: 586

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <ListBucketResult xmlns="http://obs.example.com/doc/2015-06-30/">
      <Name>examplebucket</Name>
      <Prefix/>
      <Marker/>
      <MaxKeys>1000</MaxKeys>
      <IsTruncated>false</IsTruncated>
      <Contents>
        <Key>object001</Key>
        <LastModified>2015-07-01T00:32:16.482Z</LastModified>
        <ETag>"2fa3bcaaec668adc5da177e67a122d7c"</ETag>
        <Size>12041</Size>
        <Owner>
          <ID>b4bf1b36d9ca43d984fbcb9491b6fce9</ID>
        </Owner>
        <StorageClass>STANDARD</StorageClass>
      </Contents>
    </ListBucketResult>

#### Sample Request 2

Filter objects.

Assuming that you have a bucket examplebucket that contains objects newfile, obj001, obj002, and obs001. If you want to list only object obj002, the request message is as follows:

    GET /?marker=obj001&prefix=obj HTTP/1.1
    User-Agent: curl/7.29.0
    Host: examplebucket.obs.region.example.com
    Accept: */*
    Date: WED, 01 Jul 2015 02:28:25 GMT
    Authorization: OBS H4IPJX0TQTHTHEBQQCEC:KiyoYze4pmRNPYfmlXBfRTVxt8c=

#### Sample Response 2

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26

    HTTP/1.1 200 OK
    Server: OBS
    x-obs-request-id: BF260000016435D758FBA857E0801874
    x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCShn/xAyk/xHBX6qgGSB36WXrbco0X80
    Content-Type: application/xml
    Date: WED, 01 Jul 2015 02:29:48 GMT
    Content-Length: 707

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <ListBucketResult xmlns="http://obs.example.com/doc/2015-06-30/">
    <Name>examplebucket</Name>
    <Prefix>obj</Prefix>
    <Marker>obj001</Marker>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
      <Contents>
        <Key>obj002</Key>
        <LastModified>2015-07-01T02:11:19.775Z</LastModified>
        <ETag>"a72e382246ac83e86bd203389849e71d"</ETag>
        <Size>9</Size>
        <Owner>
          <ID>b4bf1b36d9ca43d984fbcb9491b6fce9</ID>
        </Owner>
        <StorageClass>STANDARD</StorageClass>
      </Contents>
    </ListBucketResult>

#### Sample Request 3

Versioning

    1
    2
    3
    4
    5
    6

    GET /?versions HTTP/1.1
    User-Agent: curl/7.29.0
    Host: examplebucket.obs.region.example.com
    Accept: */*
    Date: WED, 01 Jul 2015 02:29:45 GMT
    Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iZeDESIMxBK2YODk7vIeVpyO8DI=

#### Sample Response 3

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29

    HTTP/1.1 200 OK
    Server: OBS
    x-obs-request-id: BF260000016435D758FBA857E0801874
    x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCShn/xAyk/xHBX6qgGSB36WXrbco0X80
    Content-Type: application/xml
    Date: WED, 01 Jul 2015 02:29:48 GMT
    Content-Length: 707

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <ListVersionsResult xmlns="http://obs.example.com/doc/2015-06-30/">
     <Name>bucket02</Name>
      <Prefix/>
      <KeyMarker/>
      <VersionIdMarker/>
      <MaxKeys>1000</MaxKeys>
      <IsTruncated>false</IsTruncated>
      <Contents>
        <Key>object001</Key>
        <VersionId>00011000000000013F16000001643A22E476FFFF9046024ECA3655445346485a</VersionId>
        <IsLatest>true</IsLatest>
        <LastModified>2015-07-01T00:32:16.482Z</LastModified>
        <ETag>"2fa3bcaaec668adc5da177e67a122d7c"</ETag>
        <Size>12041</Size>
        <Owner>
          <ID>b4bf1b36d9ca43d984fbcb9491b6fce9</ID>
        </Owner>
        <StorageClass>STANDARD</StorageClass>
      </Contents>
    </ListVersionsResult>

Parent topic: Operations on Buckets