List files in the storage space

The BOS SDK allows users to list objects in the following two ways:

• Simple listing
• Advanced listing via parameters

In addition, users can also simulate folders while listing files.

Simple listing

To quickly and easily obtain a list of desired files, users can retrieve the bucket's object list using the listObjects method.

1client.list_objects(bucket_name)

Note:

1. If the number of objects in a bucket exceeds 1,000, only 1,000 objects will be returned by default.
2. To retrieve more objects, the marker parameter can be used to enable batch reading.

Advanced listing via parameters

In addition to the simple listing mentioned above, users can also configure optional parameters through options to implement various flexible query functions. The settable parameters are as follows:

Note:

1. If there is an object named with the prefix, when querying only with prefix, all returned keys will still include the object named with the Prefix. For details, see [Recursively List All Files in a Directory](#Recursively list all files in a directory).
2. If there is an object named with the prefix, when querying with the combination of prefix and delimiter, there will be Null in all returned keys, and the key names do not contain the prefix. For details, see [View Files and Subdirectories in a Directory](#View files and subdirectories in a directory).

The following are several examples to illustrate the method of listing via parameters:

Specify the maximum number of returned items

1# Specify the maximum number of returned items as 500
2options = {
3            maxKeys: 500
4}
5puts client.list_objects(bucket_name, options)

Return objects with a specified prefix

1# Specify to return objects with the prefix "usr"
2options = {
3            prefix: 'usr'
4}
5puts client.list_objects(bucket_name, options)

Return from after a specified object

1# Users can define to exclude a certain object and start returning from after it
2options = {
3            marker: 'object'
4}
5puts client.list_objects(bucket_name, options)

Pagination to get all objects

Users can set a maximum of 500 records per page

1options = {
2            maxKeys: 500
3}
4is_truncated = true
5while is_truncated
6    res = client.list_objects(bucket_name, options)
7    is_truncated = res['isTruncated']
8    options[:marker] = res['nextMarker'] unless res['nextMarker'].nil?
9end

Results of paginated restoration of all objects after a specific object

Users can set a maximum of 500 records per page and start getting from after a specific object

1options = {
2            maxKeys: 5,
3            marker: 'object'
4}
5is_truncated = true
6while is_truncated
7    res = client.list_objects(bucket_name, options)
8    is_truncated = res['isTruncated']
9    options[:marker] = res['nextMarker'] unless res['nextMarker'].nil?
10end

The parameters available for calling in the resolution class returned by the listObjects method are as follows:

Simulate folder function

BOS storage does not have a native folder concept. Everything is stored as objects. However, for easier management, BOS users often organize files using folder structures.

To facilitate this, BOS allows the creation of simulated folders by creating objects with a size of 0. These objects can be uploaded and downloaded, and are displayed as folders if they end with “/” in the console.

By combining the delimiter and prefix parameters, users can simulate folder functionalities. The combined effect of delimiter and prefix is as follows:

When a prefix is set to a folder name, files starting with that prefix—including all files and subfolders contained within—are listed recursively. File names will appear in contents.

If the delimiter is set to /, only the files and top-level subfolders within the folder are listed. Names of subfolders are returned in CommonPrefixes. Files and folders nested within these subfolders are not displayed.

The following are several application methods:

List all files in the bucket

When users need to get all files under a bucket, they can refer to [Pagination to Get All Objects](#Advanced listing via parameters)

Recursively list all files in a directory

You can obtain all files in the dir directory by setting the Prefix parameter:

1options = {
2            prefix: 'dir/'
3}
4is_truncated = true
5while is_truncated
6    res = client.list_objects(bucket_name, options)
7    is_truncated = res['isTruncated']
8    options[:marker] = res['nextMarker'] unless res['nextMarker'].nil?
9end

View files and subdirectories in a directory

With the combination of Prefix and Delimiter, it can list files and subdirectories under the the dir directory:

1options = {
2            prefix: 'dir/',
3            delimiter: '/'
4}
5is_truncated = true
6while is_truncated
7    res = client.list_objects(bucket_name, options)
8    is_truncated = res['isTruncated']
9    options[:marker] = res['nextMarker'] unless res['nextMarker'].nil?
10end

List storage properties of objects in a bucket

After users complete the upload, if they need to view the storage class properties of all objects in a specified bucket, it can be achieved through the following code:

1res = client.list_objects(bucket_name)
2res['contents'].each { |obj| puts obj['storageClass'] }