Help Center> Object Storage Service> Tools Guide> obsutil> Object Commands> Listing Objects
View PDF

Listing Objects

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] [-v] [-marker=xxx] [-versionIdMarker=xxx] [-bf=xxx] [-limit=1] [-format=default] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
  • In Linux or macOS 
    ./obsutil ls obs://bucket[/prefix] [-s] [-d] [-v] [-marker=xxx] [-versionIdMarker=xxx] [-bf=xxx] [-limit=1] [-format=default] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

  • 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

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 is: api/except.txt
Folder number is: 1
File number is: 9

Parameter Description

Parameter

Optional or Mandatory

Description

bucket

Mandatory

Bucket name

prefix

Optional

Prefix of an 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.

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)

Object name to start with when listing objects in a bucket. All objects are listed 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.

Version ID to start with when listing versions of objects in a bucket. All versions and objects are listed in lexicographical order by object name and version ID.

NOTE:

If the value of versionIdMarker is not a version ID specified by marker, versionIdMarker is invalid.

bf

Optional (additional parameter)

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.

limit

Optional (additional parameter)

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, 1000 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.

format

Optional (additional parameter)

Prints a listing result in the user-defined format. Currently, the value can only be default, indicating that the listing result is displayed in one row.

config

Optional (additional parameter)

User-defined configuration file for executing a command. For details about parameters that can be configured, see Parameter Description.

e

Optional (additional parameter)

Specifies the endpoint.

i

Optional (additional parameter)

Specifies the user's AK.

k

Optional (additional parameter)

Specifies the user's SK.

t

Optional (additional parameter)

Specifies the user's security token.
Parent topic: Object Commands