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][-fs] [-v] [-du] [-marker=xxx] [-versionIdMarker=xxx] [-encoding-type=url][-bf=xxx] [-limit=1] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
- In Linux or macOS
./obsutil ls obs://bucket[/prefix] [-s][-fs] [-d] [-v] [-du] [-marker=xxx] [-versionIdMarker=xxx] [-encoding-type=url][-bf=xxx] [-limit=1] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=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 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
- 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 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 is: 200B Folder number is: 0 File number is: 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 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 bucket is: 0B Folder number is: 0 File number is: 2
- For more examples, see Listing.
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. 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) |
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:
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:
|
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, 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. |
encoding-type |
Optional (additional parameter) |
If the object name contains special characters, set this parameter to url. |
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. |
Response
Field |
Description |
---|---|
Key |
Object name |
LastModified |
Time when the last modification was made to the object |
Size |
Object size |
StorageClass |
Storage class of an object
|
ETag |
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. |
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.