Function

You can use this command to query objects or object versions in a bucket. All objects are listed in lexicographical order by object name and version ID.

Command Line Structure

In Windows

obsutil ls obs://bucket[/prefix] [-s] [-d][-fs] [-v] [-du] [-marker=xxx] [-versionIdMarker=xxx] [-bf=xxx] [-limit=1]  [-config=xxx]

In Linux or macOS

./obsutil ls obs://bucket[/prefix] [-s][-fs] [-d] [-v] [-du] [-marker=xxx] [-versionIdMarker=xxx] [-bf=xxx] [-limit=1]  [-config=xxx]

Examples

Example 1: Take the Windows OS as an example. Run the obsutil ls obs://bucket-test -limit=10 command to list objects in the bucket.

obsutil ls obs://bucket-test -limit=10
Start at 2024-09-30 08:18:50.0592788 +0000 UTC

Listing objects .

Folder list:
obs://bucket-test/api/

Object list:
key                                               LastModified                  Size      StorageClass        ETag                
obs://bucket-test/AUTHORS                         2018-11-16T02:15:49Z          33243     standard            "796393c1eaf502ef56a85c2ceb640aea"

obs://bucket-test/CONTRIBUTING.md                 2018-11-16T02:15:49Z          1366      standard            "12d93325ba6131f852daecd18dd65edc"

obs://bucket-test/CONTRIBUTORS                    2018-11-16T02:15:49Z          45710     standard            "b486b5003e6215c9199e86ab3ccec9fa"

obs://bucket-test/LICENSE                         2018-11-16T02:15:49Z          1479      standard            "5d4950ecb7b26d2c5e4e7b4e0dd74707"

obs://bucket-test/PATENTS                         2018-11-16T02:15:49Z          1303      standard            "3a55d95595a6f9e37dee53826b4daff2"

obs://bucket-test/README.md                       2018-11-16T02:15:49Z          1399      standard            "97351fd7946b9ea021a31a86ba2a10ab"

obs://bucket-test/VERSION                         2018-11-16T02:15:49Z          7         standard            "43d93b553855b0e1fc67e31c28c07b65"

obs://bucket-test/api/README                      2018-11-16T02:15:49Z          521       standard            "4e9e63a87075df60cdf65c8ce9e92117"

obs://bucket-test/api/except.txt                  2018-11-16T02:15:49Z          20194     standard            "8eb96de3f60447e2f09a7531c99fb3ee"

Next marker: api/except.txt
Folder number: 1
File number: 9

Example 2: Take the Windows OS as an example. Run the obsutil ls obs://bucket-test2 command to list objects in the bucket.

obsutil ls obs://bucket-test2
Start at 2024-09-30 08:21:06.6300221 +0000 UTC

Listing objects .

Object list:
key                                               LastModified                  Size      StorageClass        ETag    
obs://bucket-test2/123                            2022-03-29T09:17:51Z          0B        standard            "d41d8cd98f00b204e9800998ecf8427e"

obs://bucket-test2/1_2-3.txt                      2022-03-29T09:17:51Z          0B        standard            "d41d8cd98f00b204e9800998ecf8427e"

obs://bucket-test2/1_2-3_33.txt                   2022-03-29T09:17:51Z          200B      standard            "dcf204c11d791255adc63e61763c2426"

obs://bucket-test2/New text file.txt
                                                  2022-03-29T09:17:51Z          0B        standard            "d41d8cd98f00b204e9800998ecf8427e"

Total size of bucket: 200B
Folder number: 0
File number: 4

Example 3: Take the Windows OS as an example. Run the obsutil ls obs://bucket-test2/prefix command to list objects whose name prefix is prefix in the bucket.

obsutil ls obs://bucket-test2/prefix
Start at 2024-09-30 08:24:36.7057148 +0000 UTC

Listing objects .

Object list:
key                                               LastModified                  Size      StorageClass        ETag    
obs://bucket-test2/prefix                         2022-03-29T09:17:51Z          0B        standard            "d41d8cd98f00b204e9800998ecf8427e"

obs://bucket-test2/prefix2                        2022-03-29T09:17:51Z          0B        standard            "d41d8cd98f00b204e9800998ecf8427e"

Total size of prefix [prefix]:: 0B
Folder number: 0
File number: 2

For more examples, see Common Examples.

Parameter Description

Parameter	Optional or Mandatory	Description
bucket	Mandatory	The bucket name
prefix	Optional	The prefix of the object name for listing objects NOTE: If this parameter is left blank, all objects in the bucket are listed.
s	Optional (additional parameter)	Displays simplified query result. NOTE: In the simplified format, the returned result contains only the object name.
d	Optional (additional parameter)	Lists only objects and subdirectories in the current directory, instead of recursively listing all objects and subdirectories. 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 use this parameter to limit the scope to list. NOTE: According to the naming conventions in OBS, a slash (/) is used as the directory separator.
v	Optional (additional parameter)	Lists versions of an object in a bucket. The result contains the latest version and historical versions (if any) of the object.
marker	Optional (additional parameter)	The start position for listing objects in a bucket. The objects following this start position are sorted in lexicographical order by object name. NOTE: For details about how to use this parameter, see Listing.
versionIdMarker	Optional (additional parameter). It must be used together with the v and marker parameters.	The start position for listing object versions in a bucket. The object versions following this start position are sorted in lexicographical order by object name. NOTE: If the value of versionIdMarker is not a version ID specified by marker, versionIdMarker is invalid.
bf	Optional (additional parameter)	The display formats of bytes in the listing result. Possible values are: human-readable raw NOTE: If this parameter is not configured, the display format of bytes in the result is determined by the humanReadableFormat parameter in the configuration file.
du	Optional (additional parameter)	Quickly returns the total size of listed objects, without displaying detailed object information. This parameter can be used together with other parameters. NOTE: If there are too many objects listed, wait for a while. CAUTION: This parameter is only supported by obsutil 5.4.6 and later.
limit	Optional (additional parameter)	The maximum number of objects that can be listed. If the value is less than or equal to 0, all objects are listed. If it is left blank, 1,000 objects are listed by default. NOTE: If there are a large number of objects in a bucket, you are advised to set this parameter to limit the number of objects to be listed each time. If not all objects are listed, marker and versionIdMarker of the next request will be returned in the result, which you can use to list the remaining objects.
bucket-cname	Optional (additional parameter)	The user-defined domain name bound to the bucket NOTE: This parameter is only supported by obsutil 5.7.9 and later.
config	Optional (additional parameter)	The user-defined configuration file for executing the current command. For details about parameters that can be configured, see Configuration Parameters.
payer	Optional (additional parameter)	Specifies that requester pays is enabled.

Response

Field	Description
Key	The object name
LastModified	The time when the last modification was made to the object
Size	The object size
StorageClass	The storage class of an object. Possible values are: standard: Standard storage class. It features low access latency and high throughput, and is applicable to storing frequently accessed data (multiple accesses per month) or data that is smaller than 1 MB. warm: Warm storage class. It is ideal for storing infrequently accessed (less than 12 times a year) data, but when needed, the access has to be fast. cold: Cold storage class. It provides secure, durable, and inexpensive storage for rarely-accessed (once a year) data.
ETag	The ETag of an object, which is a Base64-encoded 128-bit MD5 digest. 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 reflects changes to the object content, rather than the object metadata. An uploaded object or copied object has a unique ETag.

Listing Objects

Function

Command Line Structure

Examples

Parameter Description

Response