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, OBS returns descriptions for some or all of the objects (a maximum of 1,000 objects) in the bucket. If you also specify one or more of the following parameters in the request: prefix, marker, max-keys, and delimiter, OBS returns a list of objects based on the semantics specified in Table 1.

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

Request Syntax

GET / HTTP/1.1

Host: bucketname.obs.region.example.com
Date: date
Authorization: authorization

Request Syntax (for multi-version objects)

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

Type

Mandatory (Yes/No)

Description

prefix

String

No

Explanation:

Name prefix that the objects to be listed must contain.

Restrictions:

The value must comply with the format of the object name.

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

marker

String

No

Explanation:

Name of the object to start with when listing objects in a bucket. All objects following this object are listed in lexicographical order by object name.

Restrictions:

This parameter is used only for listing non-versioned objects.

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

max-keys

Integer

No

Explanation:

The maximum number of objects returned in the response in alphabetical order

Restrictions:

None

Value range:

The value ranges from 1 to 1000. If the specified value is greater than 1000, only 1,000 objects are returned.

Default value:

1000

delimiter

String

No

Explanation:

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.

For a parallel file system, if this parameter is not specified, all the content in the directory is recursively listed by default, and subdirectories are also listed. In big data scenarios, parallel file systems usually have deep directory levels and each directory has a large number of files. In such case, you are advised to configure [delimiter=/] to list the content in the current directory, but not list subdirectories, thereby improving the listing efficiency.

Restrictions:

None

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

key-marker

String

No

Explanation:

Object name to start with when listing object versions in a bucket. All object versions following the specified value are listed in lexicographical order by object name.

Restrictions:

This field is used only for listing versioned objects.

Value range:

The value of NextKeyMarker in the response body of the last request

Default value:

None

version-id-marker

String

No

Explanation:

Version ID to start with when listing objects in a bucket. All objects following the specified value are listed in lexicographical order by object name and version ID. This parameter must be used together with key_marker. A maximum of 1,000 objects can be returned at a time. key_marker specifies the object name, and version_id_marker specifies the version of the specified object.

Restrictions:

  • This parameter is only used for listing objects with multiple versions.

  • If the value of version_id_marker is not a version ID that belongs to the object specified by key_marker, version_id_marker does not take effect.

Value range:

Object version ID, that is, the value of nextVersionIdMarker in the response body of the last request

Default value:

None

Request Headers

This request uses common request headers. For details, see Table 3.

Request Elements

This request contains no elements.

Response Syntax

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListBucketResult xmlns="http://obs.otc.t-systems.com/doc/2016-01-01/">
    <Name>bucket_name</Name>
    <Prefix></Prefix>
    <Marker></Marker>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>object_name</Key>
        <LastModified>2022-11-11T11:11:11.111Z</LastModified>
        <ETag>"37f80ab36f7c19abe8250e5e00123456"</ETag>
        <Size>55555</Size>
        <Owner>
            <ID>e8df38eb4e4f4f148e06d8db50123456</ID>
        </Owner>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
</ListBucketResult>

Response Headers

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

Response Elements

This response lists objects in XML format. Specific elements are described in Table 2.

Table 2 Response elements

Parameter

Type

Description

ListBucketResult

XML

Explanation:

A list of objects in a bucket

Restrictions:

None

Value range:

None

Default value:

None

Contents

XML

Explanation:

Object metadata

Parent: ListBucketResult

Restrictions:

None

Value range:

None

Default value:

None

CommonPrefixes

XML

Explanation:

Group information. If you specify a delimiter in the request, the response contains group information in CommonPrefixes.

Parent: ListBucketResult

Restrictions:

None

Value range:

None

Default value:

None

Delimiter

String

Explanation:

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 CommonPrefix. If no prefix is specified, objects with the same string from the first character to the first delimiter are grouped into one CommonPrefix.

Assume that a bucket has objects abcd, abcde, and bbcde in it. If delimiter is set to d and prefix is set to a, objects abcd and abcde are grouped into a commonPrefix with abcd as the prefix. If only delimiter is set to d, objects abcd and abcde are grouped into a commonPrefix with abcd as the prefix, and bbcde is grouped separately into another commonPrefix with bbcd as the prefix.

Parent: ListBucketResult

Restrictions:

None

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

ETag

String

Explanation:

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

Parent: ListBucketResult.Contents

Restriction:

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.

Value range:

The value must contain 32 characters.

Default value:

None

Type

String

Explanation:

Object type

Parent: ListBucketResult.Contents

Restrictions:

This parameter is returned when the object is not a Normal object.

Value range:

  • Normal: normal objects

  • APPENDABLE: appendable objects

Default value:

None

ID

String

Explanation:

Domain ID of the object owner

Parent: ListBucketResult.Contents.Owner

Restrictions:

None

Value range:

DomainId

Default value:

None

IsTruncated

Boolean

Explanation:

Whether all results are returned in the response.

Parent: ListBucketResult

Restrictions:

None

Value range:

  • true: Not all results are returned.

  • false: All results are returned.

Default value:

None

Key

String

Explanation:

Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

Parent: ListBucketResult.Contents

Restrictions:

None

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

LastModified

Date

Explanation:

Time (UTC) when an object was last modified

Parent: ListBucketResult.Contents

Restrictions:

The date is in the ISO8601 format.

Example: 2018-01-01T00:00:00.000Z

Value range:

None

Default value:

None

Marker

String

Explanation:

Name of the object to start with when listing objects in a bucket. All objects following this object are listed in lexicographical order by object name.

Assume that you have the following objects: test/a, test/b, test/c, and test/d. If you specify test/b as the marker, test/c and test/d are returned.

Parent: ListBucketResult

Restrictions:

None

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

NextMarker

String

Explanation:

The last object in the returned list. This parameter is returned when not all the objects are listed. You can set the Marker value to list the remaining objects in follow-up requests.

Parent: ListBucketResult

Restrictions:

None

Value range:

An object name string

Default value:

None

MaxKeys

String

Explanation:

The maximum number of objects returned in the response in alphabetical order

Parent: ListBucketResult

Restrictions:

None

Value range:

The value ranges from 1 to 1000. If a value larger than 1000 is specified, 1000 is used.

Default value:

1000

Name

String

Explanation:

Bucket name

Parent: ListBucketResult

Restrictions:

  • A bucket name must be unique across all accounts and regions.

  • A bucket name:

    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.

    • Cannot be formatted as an IP address.

    • Cannot start or end with a hyphen (-) or period (.).

    • Cannot contain two consecutive periods (..), for example, my..bucket.

    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.

  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Default value:

None

Owner

XML

Explanation:

User information, including the domain ID and name of the object owner

Parent: ListBucketResult.Contents

Restrictions:

None

Value range:

None

Default value:

None

DisplayName

String

Explanation:

Name of the object owner

Parent: ListBucketResult.Contents.Owner

Restrictions:

None

Value range:

None

Default value:

None

Prefix

String

Explanation:

Name prefix that the objects to be listed must contain.

Assume that you have the following objects: logs/day1, logs/day2, logs/day3, and ExampleObject.jpg. If you specify logs/ as the prefix, logs/day1, logs/day2, and logs/day3 will be returned. If you leave this parameter blank and there are also no other filters specified, all objects in the bucket will be returned.

Parent: ListBucketResult

Restrictions:

The prefix you specified must already exist in the bucket.

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

Size

String

Explanation:

Object size in bytes

Parent: ListBucketResult.Contents

Restrictions:

None

Value range:

The value ranges from 0 TB to 48.8 TB, in bytes.

Default value:

None

StorageClass

String

Explanation:

Storage class of an object.

Parent: ListBucketResult.Contents

Restrictions:

None

Value range:

  • STANDARD

  • WARM

  • COLD

Default value:

None

Table 3 Elements in the response message for listing versioned objects

Parameter

Type

Description

ListVersionsResult

Container

Explanation:

Container for the list of objects (including versioned objects)

Restrictions:

None

Value range:

None

Default value:

None

Name

String

Explanation:

Bucket name

Parent: ListVersionsResult

Restrictions:

  • A bucket name must be unique across all accounts and regions.

  • A bucket name:

    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.

    • Cannot be formatted as an IP address.

    • Cannot start or end with a hyphen (-) or period (.).

    • Cannot contain two consecutive periods (..), for example, my..bucket.

    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.

  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Value range:

None

Default value:

None

Prefix

String

Explanation:

Name prefix that the objects to be listed must contain.

Assume that you have the following objects: logs/day1, logs/day2, logs/day3, and ExampleObject.jpg. If you specify logs/ as the prefix, logs/day1, logs/day2, and logs/day3 will be returned. If you leave this parameter blank and there are also no other filters specified, all objects in the bucket will be returned.

Parent: ListVersionsResult

Restrictions:

The prefix you specified must already exist in the bucket.

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

KeyMarker

String

Explanation:

Name of the object to start with when listing objects in a bucket. All objects following this object are listed in lexicographical order by object name.

Assume that you have the following objects: test/a, test/b, test/c, and test/d. If you specify test/b as the marker, test/c and test/d are returned.

Parent: ListVersionsResult

Restrictions:

This parameter is used only for listing versioned objects.

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

VersionIdMarker

String

Explanation:

Version ID to start with when listing versioned objects, which is consistent with that set in the request

Restrictions:

This parameter is used only for listing versioned objects.

Value range:

The value must contain 32 characters.

Default value:

None

NextKeyMarker

String

Explanation:

Start position when listing versioned objects in the next request. 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.

Parent: ListVersionsResult

Restrictions:

None

Value range:

An object name string

Default value:

None

NextVersionIdMarker

String

Explanation:

Version ID to start with when listing versioned objects in the next request. It is used with the nextKeyMarker parameter. 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.

Parent: ListVersionsResult

Restrictions:

This parameter is used only for listing versioned objects.

Value range:

The value must contain 32 characters.

Default value:

None

MaxKeys

String

Explanation:

The maximum number of objects returned in the response in alphabetical order

Parent: ListVersionsResult

Restrictions:

None

Value range:

The value ranges from 1 to 1000. If a value larger than 1000 is specified, 1000 is used.

Default value:

1000

IsTruncated

Boolean

Explanation:

Whether all results are returned in the response.

Parent: ListVersionsResult

Restrictions:

None

Value range:

  • true: Not all results are returned.

  • false: All results are returned.

Default value:

None

Version

Container

Explanation:

Container that contains the version information

Parent: ListVersionsResult

Restrictions:

None

Value range:

None

Default value:

None

DeleteMarker

Container

Explanation:

Container that contains objects with delete markers

Parent: ListVersionsResult

Restrictions:

None

Value range:

None

Default value:

None

Key

String

Explanation:

Name of the versioned object. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

Parent: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

Restrictions:

None

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

VersionId

String

Explanation:

Version ID of the object.

Parent: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

Restrictions:

None

Value range:

The value must contain 32 characters.

Default value:

None

IsLatest

Boolean

Explanation:

Whether the object is of the latest version

Parent: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

Restrictions:

None

Value range:

  • true: The version is the latest.

  • false: The version is not the latest.

Default value:

None

LastModified

Date

Explanation:

Time (UTC) when an object was last modified

Parent: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

Restrictions:

The date is in the ISO8601 format.

Example: 2018-01-01T00:00:00.000Z

Value range:

None

Default value:

None

ETag

String

Explanation:

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

Parent: ListVersionsResult.Version

Restrictions:

None

Value range:

The value must contain 32 characters.

Default value:

None

Type

String

Explanation:

Object type

Parent: ListVersionsResult.Version

Restrictions:

This parameter is returned when the object is not a Normal object.

Value range:

  • NORMAL: normal objects

  • APPENDABLE: appendable objects

Default value:

None

Size

String

Explanation:

Object size in bytes

Parent: ListVersionsResult.Version

Restrictions:

None

Value range:

The value ranges from 0 TB to 48.8 TB, in bytes.

Default value:

None

Owner

Container

Explanation:

User information, including the domain ID and name of the object owner

Parent: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

Restrictions:

None

Value range:

None

Default value:

None

ID

String

Explanation:

Domain ID of the object owner

Parent: ListVersionsResult.Version.Owner | ListVersionsResult.DeleteMarker.Owner

Restrictions:

None

Value range:

DomainId

Default value:

None

DisplayName

String

Explanation:

Name of the object owner

Parent: ListVersionsResult.Version.Owner | ListVersionsResult.DeleteMarker.Owner

Restrictions:

None

Value range:

None

Default value:

None

StorageClass

String

Explanation:

Storage class of an object

Parent: ListVersionsResult.Version

Restrictions:

None

Value range:

  • STANDARD

  • WARM

  • COLD

Default value:

None

CommonPrefixes

Container

Explanation:

Group information. If you specify a delimiter in the request, the response contains group information in CommonPrefixes.

Parent: ListVersionsResult

Restrictions:

None

Value range:

None

Default value:

None

Prefix

String

Explanation:

Indicates a different prefix in the group information in CommonPrefixes.

Parent: ListVersionsResult.CommonPrefixes

Restrictions:

The prefix you specified must already exist in the bucket.

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

Error Responses

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

Sample Request: Listing All Objects

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: Listing All Objects

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>
      <DisplayName>ObjectOwnerName</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>

Sample Request: Listing Some Objects

Assume 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: Listing Some Objects

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>
      <DisplayName>ObjectOwnerName</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>

Sample Request: Listing Object Versions

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: Listing Object Versions

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>
  <Version>
    <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>
      <DisplayName>ObjectOwnerName</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Version>
</ListVersionsResult>
last updated: 2024-11-14 08:51 UTC - commit: c2bf2e27e452e727da999792ea626796d0094467