tencent cloud

对象存储

Documentation对象存储SDK 文档Android SDK对象操作列出对象

列出对象

Download
Focus Mode
Font Size
Last updated: 2026-05-15 15:04:28

简介

本文介绍对象存储 COS 通过 Android SDK 实现列出对象的示例代码和描述。

注意事项

若您要使用列出对象功能，需要先具有目标桶的读取权限：在您进行 授权策略 时，action 需要设置为 cos:GetBucket ，更多授权请参见 支持CAM的业务接口。
若您要使用列出对象历史版本功能，需要先具有目标桶的读取权限：在您进行 授权策略 时，action 需要设置为 cos:GetBucketObjectVersions ，更多授权请参见 支持CAM的业务接口。

相关示例

功能名称
描述
示例代码
列出对象
提供了查询存储桶下的部分或者全部对象的能力。
列出对象历史版本
提供了查询存储桶下的部分或者全部对象及其历史版本信息的能力。

查询对象列表

查询存储桶下的部分或者全部对象。

前期准备：创建 CosXmlService

调用 COS 的接口之前，必须先创建一个 CosXmlService 的实例，详细代码可以参见 创建 CosXmlService。

使用案例：获取第一页数据

String bucketName = "examplebucket-1250000000"; //格式：BucketName-APPID;
final GetBucketRequest getBucketRequest = new GetBucketRequest(bucketName);

// 前缀匹配，用来规定返回的对象前缀地址
getBucketRequest.setPrefix("dir/");

// 单次返回最大的条目数量，默认1000
getBucketRequest.setMaxKeys(100);

cosXmlService.getBucketAsync(getBucketRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        GetBucketResult getBucketResult = (GetBucketResult) result;
        if (getBucketResult.listBucket.isTruncated) {
            // 表示数据被截断，需要拉取下一页数据
            prevPageResult = getBucketResult;
        }
    }

    // 如果您使用 kotlin 语言来调用，请注意回调方法中的异常是可空的，否则不会回调 onFail 方法，即：
    // clientException 的类型为 CosXmlClientException?，serviceException 的类型为 CosXmlServiceException?
    @Override
    public void onFail(CosXmlRequest cosXmlRequest,
                       @Nullable CosXmlClientException clientException,
                       @Nullable CosXmlServiceException serviceException) {
        if (clientException != null) {
            clientException.printStackTrace();
        } else {
            serviceException.printStackTrace();
        }
    }
});

使用案例：请求下一页数据

String bucketName = "examplebucket-1250000000"; //格式：BucketName-APPID;

GetBucketRequest getBucketRequest = new GetBucketRequest(bucketName);

// 前缀匹配，用来规定返回的对象前缀地址
getBucketRequest.setPrefix("dir/");

// prevPageResult 是上一页的返回结果，这里的 nextMarker 表示下一页的起始位置
String nextMarker = prevPageResult.listBucket.nextMarker;
getBucketRequest.setMarker(nextMarker);

// 单次返回最大的条目数量，默认1000
getBucketRequest.setMaxKeys(100);

cosXmlService.getBucketAsync(getBucketRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        GetBucketResult getBucketResult = (GetBucketResult) result;
        if (getBucketResult.listBucket.isTruncated) {
            // 表示数据被截断，需要拉取下一页数据
        }
    }

    // 如果您使用 kotlin 语言来调用，请注意回调方法中的异常是可空的，否则不会回调 onFail 方法，即：
    // clientException 的类型为 CosXmlClientException?，serviceException 的类型为 CosXmlServiceException?
    @Override
    public void onFail(CosXmlRequest cosXmlRequest,
                       @Nullable CosXmlClientException clientException,
                       @Nullable CosXmlServiceException serviceException) {
        if (clientException != null) {
            clientException.printStackTrace();
        } else {
            serviceException.printStackTrace();
        }
    }
});

使用案例：获取对象列表与子目录

String bucketName = "examplebucket-1250000000"; //格式：BucketName-APPID;
GetBucketRequest getBucketRequest = new GetBucketRequest(bucketName);

// 前缀匹配，用来规定返回的对象前缀地址
getBucketRequest.setPrefix("dir/");

// 单次返回最大的条目数量，默认1000
getBucketRequest.setMaxKeys(100);

// 定界符为一个符号，如果有 Prefix，
// 则将 Prefix 到 delimiter 之间的相同路径归为一类，定义为 Common Prefix，
// 然后列出所有 Common Prefix。如果没有 Prefix，则从路径起点开始
getBucketRequest.setDelimiter("/");

cosXmlService.getBucketAsync(getBucketRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        GetBucketResult getBucketResult = (GetBucketResult) result;
    }

    // 如果您使用 kotlin 语言来调用，请注意回调方法中的异常是可空的，否则不会回调 onFail 方法，即：
    // clientException 的类型为 CosXmlClientException?，serviceException 的类型为 CosXmlServiceException?
    @Override
    public void onFail(CosXmlRequest cosXmlRequest,
                       @Nullable CosXmlClientException clientException,
                       @Nullable CosXmlServiceException serviceException) {
        if (clientException != null) {
            clientException.printStackTrace();
        } else {
            serviceException.printStackTrace();
        }
    }
});

查询对象历史版本列表

查询开启版本控制的存储桶下的部分或者全部对象。

前期准备：创建 CosXmlService

调用 COS 的接口之前，必须先创建一个 CosXmlService 的实例，详细代码可以参见 创建 CosXmlService。

使用案例：获取对象历史版本列表第一页数据

String bucketName = "examplebucket-1250000000"; //格式：BucketName-APPID;
final GetBucketObjectVersionsRequest getBucketRequest =
        new GetBucketObjectVersionsRequest(bucketName);

// 前缀匹配，用来规定返回的对象前缀地址
getBucketRequest.setPrefix("dir/");

// 单次返回最大的条目数量，默认1000
getBucketRequest.setMaxKeys(100);

cosXmlService.getBucketObjectVersionsAsync(getBucketRequest,
        new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        GetBucketObjectVersionsResult getBucketResult =
                (GetBucketObjectVersionsResult) result;
        if (getBucketResult.listVersionResult.isTruncated) {
            // 表示数据被截断，需要拉取下一页数据
            prevPageResult = getBucketResult;
        }
    }

    // 如果您使用 kotlin 语言来调用，请注意回调方法中的异常是可空的，否则不会回调 onFail 方法，即：
    // clientException 的类型为 CosXmlClientException?，serviceException 的类型为 CosXmlServiceException?
    @Override
    public void onFail(CosXmlRequest cosXmlRequest,
                       @Nullable CosXmlClientException clientException,
                       @Nullable CosXmlServiceException serviceException) {
        if (clientException != null) {
            clientException.printStackTrace();
        } else {
            serviceException.printStackTrace();
        }
    }
});

使用案例：获取对象历史版本列表下一页数据

String bucketName = "examplebucket-1250000000"; //格式：BucketName-APPID;
final GetBucketObjectVersionsRequest getBucketRequest =
        new GetBucketObjectVersionsRequest(bucketName);

// 前缀匹配，用来规定返回的对象前缀地址
getBucketRequest.setPrefix("dir/");

// 单次返回最大的条目数量，默认1000
getBucketRequest.setMaxKeys(100);

// prevPageResult 是上一页的返回结果，这里的 nextMarker 与 nextVersionIdMarker
// 表示下一页的起始位置
getBucketRequest.setKeyMarker(prevPageResult.listVersionResult
        .nextKeyMarker);
getBucketRequest.setVersionIdMarker(prevPageResult.listVersionResult
        .nextVersionIdMarker);

cosXmlService.getBucketObjectVersionsAsync(getBucketRequest,
        new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        GetBucketObjectVersionsResult getBucketResult =
                (GetBucketObjectVersionsResult) result;
        if (getBucketResult.listVersionResult.isTruncated) {
            // 表示数据被截断，需要拉取下一页数据
            prevPageResult = getBucketResult;
        }
    }

    // 如果您使用 kotlin 语言来调用，请注意回调方法中的异常是可空的，否则不会回调 onFail 方法，即：
    // clientException 的类型为 CosXmlClientException?，serviceException 的类型为 CosXmlServiceException?
    @Override
    public void onFail(CosXmlRequest cosXmlRequest,
                       @Nullable CosXmlClientException clientException,
                       @Nullable CosXmlServiceException serviceException) {
        if (clientException != null) {
            clientException.printStackTrace();
        } else {
            serviceException.printStackTrace();
        }
    }
});

SDK API 参考

SDK 所有接口的具体参数与方法说明，请参考 SDK API 参考。

API 操作

关于列出对象的 API 接口说明，请参见 List Objects 文档。
关于列出对象历史版本的 API 接口说明，请参见 List Object versions 文档。
Previous Topic: 复制与移动对象Next Topic: 删除对象

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback