View the object in the bucket
Updated at：2025-11-03
Simple query
View the list of objects in a bucket.
Basic workflow
- Create an instance of the BOSClient class.
- Executing the BosClient.listObjects(bucketName) method returns an instance of the ListObjectsResult class.
- Details about the returned information are found in each member of the ListObjectsResult object.
Example code
Plain Text
1let listObjectsResult: ListObjectsResult;
2try {
3 listObjectsResult = await bosClient.listObjects(bucketName);
4 for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
5 logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
6 }
7} catch (bosResponse) {
8 logger.error(`errCode: ${bosResponse.error.code}`)
9 logger.error(`requestId: ${bosResponse.error.requestId}`)
10 logger.error(`errMessage: ${bosResponse.error.message}`)
11 logger.error(`statusCode: ${bosResponse.statusCode}`)
12}Notes:
- By default, if the number of objects in the bucket exceeds 1,000, only 1,000 objects will be returned. In this case, the IsTruncated value in the returned result will be set to True, and NextMarker will be provided as the starting point for the next retrieval.
- To retrieve additional objects, the marker parameter allows for batch reading.
Complete code
Plain Text
1import { logger, Credential, BosClient, ClientOptions} from "bos"
2import { ListObjectsResult, ObjectSummaryType } from "bos/src/main/ets/bos/api/DataType"
3
4 let credential = new Credential(AccessKeyID, SecretAccessKey, Token); //Temporary AK/SK and Token returned by STS
5let clientOptions = new ClientOptions();
6 clientOptions.endpoint = "bj.bcebos.com"; //Pass in the domain name of the region where the bucket is located
7 let bosClient = new BosClient(credential, clientOptions); // Create BosClient
8let bucketName = "test-bucket-harmony";
9
10let listObjectsResult: ListObjectsResult;
11try {
12 listObjectsResult = await bosClient.listObjects(bucketName);
13 for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
14 logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
15 }
16} catch (bosResponse) {
17 logger.error(`errCode: ${bosResponse.error.code}`)
18 logger.error(`requestId: ${bosResponse.error.requestId}`)
19 logger.error(`errMessage: ${bosResponse.error.message}`)
20 logger.error(`statusCode: ${bosResponse.statusCode}`)
21}Extended query
Users can configure ListObjectsArgs parameters to execute extended query operations. The extended parameters available for ListObjectsArgs are listed below:
| Parameter name | Description | Default value |
|---|---|---|
| delimiter | This is a delimiter used to organize objectKey hierarchically. It is typically used with a prefix when querying simulated folders. The segment of the objectKey from the prefix up to the first occurrence of the delimiter is referred to as: commonPrefixes. | - |
| marker | This string sets the starting point for returned results. When the marker value is assigned, the returned objects will begin with the marker value in alphabetical order. | - |
| maxKeys | Specify the maximum number of objects to return, which must not exceed 1,000. | - |
| prefix | Set a prefix for the objectKey. A prefix specifies that the objectKey begins with and contains the designated Prefix value. It is often used together with a delimiter when querying simulated folders. | - |
Example code
Example 1:
Plain Text
1import { logger, Credential, BosClient, ClientOptions} from "bos"
2import { ListObjectsResult, ObjectSummaryType, ListObjectsArgs } from "bos/src/main/ets/bos/api/DataType"
3
4 let credential = new Credential(AccessKeyID, SecretAccessKey, Token); //Temporary AK/SK and Token returned by STS
5let clientOptions = new ClientOptions();
6 clientOptions.endpoint = "bj.bcebos.com"; //Pass in the domain name of the region where the bucket is located
7 let bosClient = new BosClient(credential, clientOptions); // Create BosClient
8let bucketName = "test-bucket-harmony";
9
10let args = new ListObjectsArgs();
11args.delimiter = "/";
12args.maxKeys = 3;
13args.prefix = "fun";
14args.marker = "123";
15let listObjectsResult: ListObjectsResult;
16try {
17 listObjectsResult = await bosClient.listObjects(bucketName, args);
18 for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
19 logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
20 }
21} catch (bosResponse) {
22 logger.error(`errCode: ${bosResponse.error.code}`)
23 logger.error(`requestId: ${bosResponse.error.requestId}`)
24 logger.error(`errMessage: ${bosResponse.error.message}`)
25 logger.error(`statusCode: ${bosResponse.statusCode}`)
26}Example II: A complete example using nextMarker.
Plain Text
1import { logger, Credential, BosClient, ClientOptions} from "bos"
2import { ListObjectsResult, ObjectSummaryType, ListObjectsArgs } from "bos/src/main/ets/bos/api/DataType"
3
4
5 let credential = new Credential(AccessKeyID, SecretAccessKey, Token); //Temporary AK/SK and Token returned by STS
6let clientOptions = new ClientOptions();
7 clientOptions.endpoint = "bj.bcebos.com"; //Pass in the domain name of the region where the bucket is located
8 let bosClient = new BosClient(credential, clientOptions); // Create BosClient
9let bucketName = "test-bucket-harmony";
10
11let args = new ListObjectsArgs();
12args.delimiter = "/";
13args.maxKeys = 3;
14args.prefix = "test";
15let listObjectsResult: ListObjectsResult;
16try {
17 listObjectsResult = await bosClient.listObjects(bucketName, args);
18 for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
19 logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
20 }
21 if (listObjectsResult.isTruncated) {
22 args.marker = listObjectsResult.nextMarker as string;
23 }
24 listObjectsResult = await bosClient.listObjects(bucketName, args);
25 for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
26 logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
27 }
28} catch (bosResponse) {
29 logger.error(`errCode: ${bosResponse.error.code}`)
30 logger.error(`requestId: ${bosResponse.error.requestId}`)
31 logger.error(`errMessage: ${bosResponse.error.message}`)
32 logger.error(`statusCode: ${bosResponse.statusCode}`)
33}Query prefix
Since BOS is inherently a KV 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 prefix
You can obtain all files under a simulated folder by setting the prefix parameter:
Plain Text
1let args = new ListObjectsArgs();
2args.prefix = "fun/";
3
4let listObjectsResult: ListObjectsResult;
5try {
6 listObjectsResult = await bosClient.listObjects(bucketName, args);
7 for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
8 logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
9 }
10} catch (bosResponse) {
11 logger.error(`errCode: ${bosResponse.error.code}`)
12 logger.error(`requestId: ${bosResponse.error.requestId}`)
13 logger.error(`errMessage: ${bosResponse.error.message}`)
14 logger.error(`statusCode: ${bosResponse.statusCode}`)
15}Output:
Plain Text
1name: fun/ size: 0 storageClass: COLD
2name: fun/movie/001.avi size: 0 storageClass: COLD
3name: fun/movie/007.avi size: 0 storageClass: COLD
4name: fun/test.jpg size: 0 storageClass: COLDView files and subfolders under the prefix
With the combination of prefix and delimiter, it can list files and subfolders under the simulated folder:
Plain Text
1import { logger, Credential, BosClient, ClientOptions} from "bos"
2import { ListObjectsResult, ObjectSummaryType, ListObjectsArgs, PrefixType } from "bos/src/main/ets/bos/api/DataType"
3
4 let credential = new Credential(AccessKeyID, SecretAccessKey, Token); //Temporary AK/SK and Token returned by STS
5let clientOptions = new ClientOptions();
6 clientOptions.endpoint = "bj.bcebos.com"; //Pass in the domain name of the region where the bucket is located
7 let bosClient = new BosClient(credential, clientOptions); // Create BosClient
8let bucketName = "test-bucket-harmony";
9
10let args = new ListObjectsArgs();
11args.delimiter = "/";
12args.prefix = "fun/";
13let listObjectsResult: ListObjectsResult;
14try {
15 listObjectsResult = await bosClient.listObjects(bucketName, args);
16 for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
17 logger.info("objects:");
18 logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
19 }
20 logger.info("commonPrefix:");
21 // Traverse all CommonPrefix
22 for(let prefix of listObjectsResult.commonPrefixes as PrefixType[]) {
23 logger.info(`commonPrefix: ${prefix.prefix}`);
24 }
25} catch (bosResponse) {
26 logger.error(`errCode: ${bosResponse.error.code}`)
27 logger.error(`requestId: ${bosResponse.error.requestId}`)
28 logger.error(`errMessage: ${bosResponse.error.message}`)
29 logger.error(`statusCode: ${bosResponse.statusCode}`)
30}Output:
Plain Text
1objects:
2name: fun/ size: 0 storageClass: COLD
3name: fun/test.jpg size: 0 storageClass: COLD
4commonPrefix:
5commonPrefix: fun/movie/Note: In the returned results, the list of objects 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.