List objects by using the ossutil list-objects command - Object Storage Service

Lists all objects in a bucket.

list-objects (get-bucket) is the v1 version of the list-objects command. For new application development, use list-objects-v2 (get-bucket-v2) instead. OSS continues to support list-objects for backward compatibility.

Usage notes

By default, an Alibaba Cloud account has permission to list all objects in a bucket. To list objects as a RAM user or using Security Token Service (STS), grant the oss:ListObjects permission. See Attach a custom policy to a RAM user.
This command does not return user metadata of objects.

Syntax

ossutil api list-objects --bucket <bucket-name>
                         [--prefix <prefix>]
                         [--delimiter <delimiter>]
                         [--marker <marker>]
                         [--max-keys <number>]
                         [--encoding-type <encoding-type>]

Parameters

Parameter	Type	Required	Default	Description
`--bucket`	string	Yes	—	The name of the bucket.
`--prefix`	string	No	—	Filters results to objects whose names start with this value.
`--delimiter`	string	No	—	Groups objects by name. Objects whose names share the same prefix before the delimiter are grouped into a single `CommonPrefixes` entry. Use `/` to simulate a directory listing.
`--marker`	string	No	—	The name of the object after which the listing starts. Objects whose names are alphabetically after the marker value are returned.
`--max-keys`	int	No	—	The maximum number of objects to return.
`--encoding-type`	string	No	—	The encoding type for object names in the response.

For supported global options such as --output-format, see Command-line options.

Examples

List all objects in a bucket

ossutil api list-objects --bucket examplebucket

Format output as JSON or YAML

# JSON output
ossutil api list-objects --bucket examplebucket --output-format json

# YAML output
ossutil api list-objects --bucket examplebucket --output-format yaml

Filter by prefix

List all objects whose names start with dir:

ossutil api list-objects --bucket examplebucket --prefix dir

Limit results to the first 100 objects with the dir prefix:

ossutil api list-objects --bucket examplebucket --prefix dir --max-keys 100

Simulate a directory listing

List objects at the root level of a bucket (groups objects into virtual directories using / as delimiter):

ossutil api list-objects --bucket examplebucket --delimiter /

Paginate through results

List objects alphabetically after test.txt:

ossutil api list-objects --bucket examplebucket --marker test.txt

URL-encode object names

URL-encode object names when they contain special characters:

ossutil api list-objects --bucket examplebucket --encoding-type url

What's next

API reference: GetBucket (ListObjects)
Newer version: list-objects-v2 (get-bucket-v2)