View the object in the bucket

Updated at：2025-11-03

Simple query

View the list of objects in a bucket.

Basic workflow

Instantiate the BOSClient class.
Executing the BOSClient listObjects method will return an instance of the BOSListObjectsResponse class.
You can iterate through the contents field of the BOSListObjectsResponse type to retrieve keys, lastModified dates, eTags, sizes, and owners.

Example code

Swift

1BOSListObjectsRequest* listObjRequest = [[BOSListObjectsRequest alloc] init];
2listObjRequest.bucket = @"<bucketname>";
3__block BOSListObjectsResponse* listObjResponse = nil;
4BCETask* task = [client listObjects:listObjRequest];
5task.then(^(BCEOutput* output) {
6  if (output.response) {
7      listObjResponse = (BOSListObjectsResponse*)output.response;
8      for (BOSObjectInfo* object in listObjResponse.contents) {
9          NSLog(@"the object key is %@", object.key);
10          NSLog(@"the object lastModified is %@", object.lastModified);
11          NSLog(@"the object eTag is %@", object.eTag);
12          NSLog(@"the object size is %llu", object.size);
13          NSLog(@"the object owner id is %@", object.owner.ownerID);
14      }
15  }
16  if (output.error) {
17      NSLog(@"list objects failure");
18  }
19});
20[task waitUtilFinished];

Note: The listObjects method returns a BOSListObjectsResponse object, which contains the results of this listObject request. Users can obtain the description information of all objects through the contents attribute in BOSListObjectsResponse.

By default, if the number of objects in a bucket exceeds 1,000, only 1,000 objects will be returned. The isTruncated value in the result will be YES, and nextMarker will indicate the starting point for the next query.

To retrieve more objects, use the marker parameter for reading in batches. Refer to [Extended Query](#Extended query).

Complete example

Swift

1#import <BaiduBCEBasic/BaiduBCEBasic.h>
2#import <BaiduBCEBOS/BaiduBCEBOS.h>
3void example(void) {
4 // Initialize
5    BCECredentials* credentials = [[BCECredentials alloc] init];
6    credentials.accessKey = @"<access key>";
7    credentials.secretKey = @"<secret key>";
8    BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
9    configuration.credentials = credentials;
10    BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];
11    BOSListObjectsRequest* listObjRequest = [[BOSListObjectsRequest alloc] init];
12    listObjRequest.bucket = @"<bucketname>";
13    __block BOSListObjectsResponse* listObjResponse = nil;
14    BCETask* task = [client listObjects:listObjRequest];
15    task.then(^(BCEOutput* output) {
16        if (output.response) {
17            listObjResponse = (BOSListObjectsResponse*)output.response;
18            for (BOSObjectInfo* object in listObjResponse.contents) {
19                NSLog(@"the object key is %@", object.key);
20                NSLog(@"the object lastModified is %@", object.lastModified);
21                NSLog(@"the object eTag is %@", object.eTag);
22                NSLog(@"the object size is %llu", object.size);
23                NSLog(@"the object owner id is %@", object.owner.ownerID);
24            }
25        }
26        if (output.error) {
27            NSLog(@"list objects failure");
28        }
29    });
30    [task waitUtilFinished];
31}

Extended query

Users can configure BOSListObjectsRequest parameters to enable additional query operations. The available extended parameters in BOSListObjectsRequest include:

Parameter name	Description	Default value
maxKeys	Specify the maximum number of objects to return, which must not exceed 1,000.	1000
prefix	Set the prefix of the objectKey. The prefix means that the objectKey contains and starts with the value of prefix. It is usually used in conjunction with delimiter when [querying simulated folders](#Query simulated folders).	-
delimiter	It is a delimiter used to hierarchize objectKey. It is usually used in conjunction with prefix when [querying simulated folders](#Query simulated folders). The objectKey from the prefix to the first occurrence of the delimiter character is called: commonPrefixes.	-
marker	This is a string that specifies the starting position of the returned results. When the marker value is set, objects will be listed starting from this value in alphabetical order.	-

Basic workflow

Create a BOSListObjectsRequest class instance.
Configure fields like delimiter, marker, prefix, and maxKeys in the BOSListObjectsRequest to enable extended query operations.
Create a BOSClient instance and execute the listObjects method.

Example code

Swift

1BOSListObjectsRequest* listObjRequest = [[BOSListObjectsRequest alloc] init];
2listObjRequest.bucket = @"<bucketname>";
3listObjRequest.marker = @"<marker>";
4__block BOSListObjectsResponse* listObjResponse = nil;
5BCETask* task = [client listObjects:listObjRequest];
6task.then(^(BCEOutput* output) {
7  if (output.response) {
8      listObjResponse = (BOSListObjectsResponse*)output.response;
9      for (BOSObjectInfo* object in listObjResponse.contents) {
10          NSLog(@"the object key is %@", object.key);
11          NSLog(@"the object lastModified is %@", object.lastModified);
12          NSLog(@"the object eTag is %@", object.eTag);
13          NSLog(@"the object size is %llu", object.size);
14          NSLog(@"the object owner id is %@", object.owner.ownerID);
15      }
16  }
17  if (output.error) {
18      NSLog(@"list objects failure");
19  }
20});
21[task waitUtilFinished];

Complete example

Example 1:

Swift

1#import <BaiduBCEBasic/BaiduBCEBasic.h>
2#import <BaiduBCEBOS/BaiduBCEBOS.h>
3void example(void) {
4 // Initialize
5    BCECredentials* credentials = [[BCECredentials alloc] init];
6    credentials.accessKey = @"<access key>";
7    credentials.secretKey = @"<secret key>";
8    BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
9    configuration.credentials = credentials;
10    BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];
11    BOSListObjectsRequest* listObjRequest = [[BOSListObjectsRequest alloc] init];
12    listObjRequest.bucket = @"<bucketname>";
13    listObjRequest.marker = @"<marker>";
14    __block BOSListObjectsResponse* listObjResponse = nil;
15    BCETask* task = [client listObjects:listObjRequest];
16    task.then(^(BCEOutput* output) {
17        if (output.response) {
18            listObjResponse = (BOSListObjectsResponse*)output.response;
19            for (BOSObjectInfo* object in listObjResponse.contents) {
20                NSLog(@"the object key is %@", object.key);
21                NSLog(@"the object lastModified is %@", object.lastModified);
22                NSLog(@"the object eTag is %@", object.eTag);
23                NSLog(@"the object size is %llu", object.size);
24                NSLog(@"the object owner id is %@", object.owner.ownerID);
25            }
26        }
27        if (output.error) {
28            NSLog(@"list objects failure");
29        }
30    });
31    [task waitUtilFinished];
32}

Example II: A complete example using nextMarker.

Swift

1#import <BaiduBCEBasic/BaiduBCEBasic.h>
2#import <BaiduBCEBOS/BaiduBCEBOS.h>
3void example(void) {
4 // Initialize
5    BCECredentials* credentials = [[BCECredentials alloc] init];
6    credentials.accessKey = @"<access key>";
7    credentials.secretKey = @"<secret key>";
8    BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
9    configuration.credentials = credentials;
10    BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];
11    BOSListObjectsRequest* listObjRequest = [[BOSListObjectsRequest alloc] init];
12    listObjRequest.bucket = @"<bucketname>";
13    listObjRequest.marker = @"<marker>";
14    __block BOSListObjectsResponse* listObjResponse = nil;
15    BCETask* task = [client listObjects:listObjRequest];
16    task.then(^(BCEOutput* output) {
17        if (output.response) {
18            listObjResponse = (BOSListObjectsResponse*)output.response;
19        }
20        if (output.error) {
21            NSLog(@"list objects failure");
22        }
23    });
24    [task waitUtilFinished];
25    if (listObjResponse != nil) {
26        listObjRequest.marker = listObjResponse.nextMarker;
27        task = [client listObjects:listObjRequest];
28        task.then(^(BCEOutput* output) {
29            if (output.response) {
30                listObjResponse = (BOSListObjectsResponse*)output.response;
31                for (BOSObjectInfo* object in listObjResponse.contents) {
32                    NSLog(@"the object key is %@", object.key);
33                    NSLog(@"the object lastModified is %@", object.lastModified);
34                    NSLog(@"the object eTag is %@", object.eTag);
35                    NSLog(@"the object size is %llu", object.size);
36                    NSLog(@"the object owner id is %@", object.owner.ownerID);
37                }
38            }
39        });
40    }
41}

Query simulated folders

Since BOS is inherently a (<Key>,<Value>) storage system, the concept of "folder" does not exist in principle. However, you can simulate the folder function by combining the delimiter and prefix} parameters.

Suppose the bucket contains five files: bos.jpg, fun/, fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi. The "/" symbol can be used as a delimiter to mimic folder structures.

Recursively list all files under the simulated folder

You can obtain all files under a simulated folder by setting the prefix parameter:

Swift

1BOSListObjectsRequest* listObjRequest = [[BOSListObjectsRequest alloc] init];
2listObjRequest.bucket = @"<bucketname>";
3 listObjRequest.prefix = @"fun/";
4__block BOSListObjectsResponse* listObjResponse = nil;
5BCETask* task = [client listObjects:listObjRequest];
6task.then(^(BCEOutput* output) {
7    if (output.response) {
8        listObjResponse = (BOSListObjectsResponse*)output.response;
9        for (BOSObjectInfo* object in listObjResponse.contents) {
10            NSLog(@"%@", object.key);
11        }
12    }
13});
14[task waitUtilFinished];

Output:

Swift

1Objects:
2fun/
3fun/movie/001.avi
4fun/movie/007.avi
5fun/test.jpg

View files and subfolders under the simulated folder

With the combination of prefix and delimiter, it can list files and subfolders under the simulated folder:

Swift

1BOSListObjectsRequest* listObjRequest = [[BOSListObjectsRequest alloc] init];
2listObjRequest.bucket = @"<bucketname>";
3// Specify "/" as the delimiter for simulated folder
4listObjRequest.delimiter = @"/";
5// List all files and subfolders under the fun folder
6listObjRequest.prefix = @"fun/";
7__block BOSListObjectsResponse* listObjResponse = nil;
8BCETask* task = [client listObjects:listObjRequest];
9task.then(^(BCEOutput* output) {
10    if (output.response) {
11        listObjResponse = (BOSListObjectsResponse*)output.response;
12    }
13    if (output.error) {
14        NSLog(@"list objects failure");
15    }
16});
17[task waitUtilFinished];
18// Traverse all objects
19NSLog(@"Objects:");
20for (BOSObjectInfo* object in listObjResponse.contents) {
21    NSLog(@"%@", object.key);
22}
23// Traverse all CommonPrefixes
24NSLog(@"CommonPrefixs:");
25for (NSString* commonPrefix in listObjResponse.commonPrefixes) {
26    NSLog(@"%@", commonPrefix);
27}

Output:

Swift

1Objects:
2fun/
3fun/test.jpg
4CommonPrefixs:
5fun/movie/

Note: In the returned results, the list of contents shows the files under the “fun” folder. The list in commonPrefixs shows all subfolders under the fun folder. It can be seen that the two files fun/movie/001.avi and fun/movie/007.avi are not listed because they belong to the movie subfolder under the fun folder.

Get Object

Copy Object