查看Bucket中的Object
更新时间：2025-04-01
简单查询
查看Bucket中Object列表。
基本流程
- 创建BosClient类的实例。
- 执行BosClient.listObjects(bucketName)方法，会返回ListObjectsResult类的实例。
- 返回信息见ListObjectsResult对象的各个成员。
示例代码
let listObjectsResult: ListObjectsResult;
try {
listObjectsResult = await bosClient.listObjects(bucketName);
for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
}
} catch (bosResponse) {
logger.error(`errCode: ${bosResponse.error.code}`)
logger.error(`requestId: ${bosResponse.error.requestId}`)
logger.error(`errMessage: ${bosResponse.error.message}`)
logger.error(`statusCode: ${bosResponse.statusCode}`)
}说明：
- 默认情况下，如果Bucket中的Object数量大于1000，则只会返回1000个Object，并且返回结果中IsTruncated值为True，并返回NextMarker做为下次读取的起点。
- 若想获取更多的Object，可以使用Marker参数分次读取。
完整代码
import { logger, Credential, BosClient, ClientOptions} from "bos"
import { ListObjectsResult, ObjectSummaryType } from "bos/src/main/ets/bos/api/DataType"
let credential = new Credential(AccessKeyID, SecretAccessKey, Token); //STS返回的临时AK/SK及Token
let clientOptions = new ClientOptions();
clientOptions.endpoint = "bj.bcebos.com"; //传入Bucket所在区域域名
let bosClient = new BosClient(credential, clientOptions); // 创建BosClient
let bucketName = "test-bucket-harmony";
let listObjectsResult: ListObjectsResult;
try {
listObjectsResult = await bosClient.listObjects(bucketName);
for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
}
} catch (bosResponse) {
logger.error(`errCode: ${bosResponse.error.code}`)
logger.error(`requestId: ${bosResponse.error.requestId}`)
logger.error(`errMessage: ${bosResponse.error.message}`)
logger.error(`statusCode: ${bosResponse.statusCode}`)
}扩展查询
用户可以通过设置ListObjectsArgs参数来完成更多扩展查询操作设置。ListObjectsArgs中可以设置的扩展参数如下：
| 参数名称 | 说明 | 默认值 |
|---|---|---|
| delimiter | 是一个分隔符，用来对objectKey进行分层。通常与prefix配合在查询模拟文件夹中使用。从prefix开始到第一次出现delimiter字符之间的objectKey称为：commonPrefixes | - |
| marker | 是一个字符串，用来设定返回结果的起始位置。设定Marker值之后，返回的Object会从Marker值之后按字母排序开始返回。 | - |
| maxKeys | 设定此次返回Object的最大个数，不可超过1000。 | - |
| prefix | 设定objectKey的前缀，前缀是指objectKey包含并以Prefix的值作为开始。通常与Delimiter配合在查询模拟文件夹中使用。 | - |
示例代码
示例一：
import { logger, Credential, BosClient, ClientOptions} from "bos"
import { ListObjectsResult, ObjectSummaryType, ListObjectsArgs } from "bos/src/main/ets/bos/api/DataType"
let credential = new Credential(AccessKeyID, SecretAccessKey, Token); //STS返回的临时AK/SK及Token
let clientOptions = new ClientOptions();
clientOptions.endpoint = "bj.bcebos.com"; //传入Bucket所在区域域名
let bosClient = new BosClient(credential, clientOptions); // 创建BosClient
let bucketName = "test-bucket-harmony";
let args = new ListObjectsArgs();
args.delimiter = "/";
args.maxKeys = 3;
args.prefix = "fun";
args.marker = "123";
let listObjectsResult: ListObjectsResult;
try {
listObjectsResult = await bosClient.listObjects(bucketName, args);
for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
}
} catch (bosResponse) {
logger.error(`errCode: ${bosResponse.error.code}`)
logger.error(`requestId: ${bosResponse.error.requestId}`)
logger.error(`errMessage: ${bosResponse.error.message}`)
logger.error(`statusCode: ${bosResponse.statusCode}`)
}示例二：使用nextmarker完整示例。
import { logger, Credential, BosClient, ClientOptions} from "bos"
import { ListObjectsResult, ObjectSummaryType, ListObjectsArgs } from "bos/src/main/ets/bos/api/DataType"
let credential = new Credential(AccessKeyID, SecretAccessKey, Token); //STS返回的临时AK/SK及Token
let clientOptions = new ClientOptions();
clientOptions.endpoint = "bj.bcebos.com"; //传入Bucket所在区域域名
let bosClient = new BosClient(credential, clientOptions); // 创建BosClient
let bucketName = "test-bucket-harmony";
let args = new ListObjectsArgs();
args.delimiter = "/";
args.maxKeys = 3;
args.prefix = "test";
let listObjectsResult: ListObjectsResult;
try {
listObjectsResult = await bosClient.listObjects(bucketName, args);
for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
}
if (listObjectsResult.isTruncated) {
args.marker = listObjectsResult.nextMarker as string;
}
listObjectsResult = await bosClient.listObjects(bucketName, args);
for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
}
} catch (bosResponse) {
logger.error(`errCode: ${bosResponse.error.code}`)
logger.error(`requestId: ${bosResponse.error.requestId}`)
logger.error(`errMessage: ${bosResponse.error.message}`)
logger.error(`statusCode: ${bosResponse.statusCode}`)
}查询prefix
由于BOS本身是一个KV的存储系统，所以原则上并不会存在“文件夹”的概念，但您可以通过 delimiter 和 prefix 参数的配合进行文件夹功能模拟。
假设Bucket中有5个文件：bos.jpg，fun/，fun/test.jpg，fun/movie/001.avi，fun/movie/007.avi，可以把 “/” 符号作为分隔符模拟文件夹。
递归列出prefix下所有文件
可以通过设置 prefix 参数来获取某个模拟文件夹下所有的文件：
let args = new ListObjectsArgs();
args.prefix = "fun/";
let listObjectsResult: ListObjectsResult;
try {
listObjectsResult = await bosClient.listObjects(bucketName, args);
for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
}
} catch (bosResponse) {
logger.error(`errCode: ${bosResponse.error.code}`)
logger.error(`requestId: ${bosResponse.error.requestId}`)
logger.error(`errMessage: ${bosResponse.error.message}`)
logger.error(`statusCode: ${bosResponse.statusCode}`)
}输出：
name: fun/ size: 0 storageClass: COLD
name: fun/movie/001.avi size: 0 storageClass: COLD
name: fun/movie/007.avi size: 0 storageClass: COLD
name: fun/test.jpg size: 0 storageClass: COLD查看prefix下的文件和子文件夹
在 prefix 和 delimiter 结合的情况下，可以列出模拟文件夹下的文件和子文件夹：
import { logger, Credential, BosClient, ClientOptions} from "bos"
import { ListObjectsResult, ObjectSummaryType, ListObjectsArgs, PrefixType } from "bos/src/main/ets/bos/api/DataType"
let credential = new Credential(AccessKeyID, SecretAccessKey, Token); //STS返回的临时AK/SK及Token
let clientOptions = new ClientOptions();
clientOptions.endpoint = "bj.bcebos.com"; //传入Bucket所在区域域名
let bosClient = new BosClient(credential, clientOptions); // 创建BosClient
let bucketName = "test-bucket-harmony";
let args = new ListObjectsArgs();
args.delimiter = "/";
args.prefix = "fun/";
let listObjectsResult: ListObjectsResult;
try {
listObjectsResult = await bosClient.listObjects(bucketName, args);
for (let objectInfo of listObjectsResult.contents as ObjectSummaryType[]) {
logger.info("objects:");
logger.info(`name: ${objectInfo.key} size: ${objectInfo.size} storageClass: ${objectInfo.storageClass}`);
}
logger.info("commonPrefix:");
// 遍历所有CommonPrefix
for(let prefix of listObjectsResult.commonPrefixes as PrefixType[]) {
logger.info(`commonPrefix: ${prefix.prefix}`);
}
} catch (bosResponse) {
logger.error(`errCode: ${bosResponse.error.code}`)
logger.error(`requestId: ${bosResponse.error.requestId}`)
logger.error(`errMessage: ${bosResponse.error.message}`)
logger.error(`statusCode: ${bosResponse.statusCode}`)
}输出：
objects:
name: fun/ size: 0 storageClass: COLD
name: fun/test.jpg size: 0 storageClass: COLD
commonPrefix:
commonPrefix: fun/movie/说明：返回的结果中， objects 的列表中给出的是fun文件夹下的文件。而 commonPrefixs 的列表中给出的是fun文件夹下的所有子文件夹。可以看出 fun/movie/001.avi ， fun/movie/007.avi 两个文件并没有被列出来，因为它们属于 fun 文件夹下的 movie 子文件夹下的文件。