tencent cloud

对象存储

文档对象存储SDK 文档Android SDK对象操作复制与移动对象

复制与移动对象

Download
聚焦模式
字号
最后更新时间： 2026-05-15 15:03:02

简介

本文介绍对象存储 COS 通过 Android SDK 实现复制与移动对象功能的示例代码和描述。包括高级接口、简单操作两个部分。

注意事项

若您使用简单接口复制对象，需要具有源对象的读权限和目标对象的写权限：在您进行 授权策略 时，目标对象的授权 action 需要设置为cos:PutObject ，源对象的授权 action 需要设置为cos:GetObject ，更多授权请参见 支持CAM的业务接口。
若您使用高级接口的自动分块复制或使用简单接口的分块操作实现分块复制，需要具有源对象的读权限以及目标对象的初始化分块上传、上传对象、完成分块上传的权限：在您进行 授权策略 时，目标对象的授权 action 需要设置为 cos:InitiateMultipartUpload，cos:PutObject，cos:CompleteMultipartUpload，源对象的授权 action 需要设置为cos:GetObject ，更多授权请参见 支持CAM的业务接口。
若您要移动对象，除了上述复制相关权限还需要具有源对象的删除权限：在您进行 授权策略 时，源对象的授权 action 需要设置为cos:DeleteObject ，更多授权请参见 支持CAM的业务接口。

相关示例

功能名称
描述
示例代码
高级接口
高级接口封装了简单拷贝、分块拷贝接口，根据文件大小智能的选择拷贝对象的方式。
简单操作
简单操作的拷贝接口可以拷贝一个对象至指定存储桶中，不支持自动分块拷贝。最大支持拷贝不超过5GB的对象，5GB以上对象请使用 分块拷贝 或 高级接口 拷贝。

高级接口

高级接口封装了简单复制、分块复制接口的异步请求，并支持暂停、恢复以及取消复制请求。

前期准备：创建 TransferManager

使用高级接口的操作之前，必须先创建一个 TransferManager 的实例。创建 TransferManager 的实例之前，需要创建一个 CosXmlService 实例，详细代码可以参见 创建 CosXmlService。
// 初始化 TransferConfig，这里使用默认配置，如果需要定制，请参考 SDK 接口文档
// 默认对大于或等于5M的文件自动进行分块复制，分块大小为5M，可以通过如下代码修改分块阈值
TransferConfig transferConfig = new TransferConfig.Builder()
        // 设置启用分块复制的最小对象大小 默认为5M
        .setDividsionForCopy(5242880)
        // 设置分块复制时的分块大小 默认为5M
        .setSliceSizeForCopy(5242880)
        .build();
// 初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXmlService,
        transferConfig);

使用案例：复制对象

String sourceBucket = "sourcebucket-1250000000"; //源对象所在的存储桶
String sourceRegion = "COS_REGION"; //源对象的存储桶所在的地域
String sourceCosPath = "sourceObject"; //源对象的对象键
//构造源对象属性
CopyObjectRequest.CopySourceStruct copySourceStruct =
        new CopyObjectRequest.CopySourceStruct(sourceBucket, sourceRegion, sourceCosPath);
//目标桶
// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
//目标对象
String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即对象键

//复制对象
COSXMLCopyTask cosxmlCopyTask = transferManager.copy(bucket, cosPath,
        copySourceStruct);

//设置返回结果回调
cosxmlCopyTask.setCosXmlResultListener(new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        COSXMLCopyTask.COSXMLCopyTaskResult copyResult =
                (COSXMLCopyTask.COSXMLCopyTaskResult) result;
    }

    // 如果您使用 kotlin 语言来调用，请注意回调方法中的异常是可空的，否则不会回调 onFail 方法，即：
    // clientException 的类型为 CosXmlClientException?，serviceException 的类型为 CosXmlServiceException?
    @Override
    public void onFail(CosXmlRequest request,
                       @Nullable CosXmlClientException clientException,
                       @Nullable CosXmlServiceException serviceException) {
        if (clientException != null) {
            clientException.printStackTrace();
        } else {
            serviceException.printStackTrace();
        }
    }
});
//设置任务状态回调, 可以查看任务过程
cosxmlCopyTask.setTransferStateListener(new TransferStateListener() {
    @Override
    public void onStateChanged(TransferState state) {
        // todo notify transfer state
    }
});

使用案例：移动对象

移动对象主要包括两个操作：复制源对象到目标位置，删除源对象。
由于 COS 通过存储桶名称（Bucket）和对象键（ObjectKey）来标识对象。移动对象也就意味着修改这个对象的标识，COS Android SDK 目前没有提供修改对象唯一标识名的单独接口，但是可以通过组合复制对象加上删除对象的基本操作，来达到修改对象标识的目的，从而实现移动对象。
例如将 sourcebucket-1250000000 这个存储桶中的 sourceObject 这个对象移动到 examplebucket-1250000000 存储桶中，并命名为 exampleobject。首先可以复制 sourceObject 对象到 examplebucket-1250000000 存储桶，并将对象键设定为 exampleobject，复制完成后删除 sourceObject 这个对象，来实现“移动”的效果。
final String sourceBucket = "sourcebucket-1250000000"; //源对象所在的存储桶
final String sourceRegion = "COS_REGION"; //源对象的存储桶所在的地域
final String sourceKey = "sourceObject"; //源对象键
//构造源对象属性
CopyObjectRequest.CopySourceStruct copySource = new CopyObjectRequest.CopySourceStruct(sourceBucket,
        sourceRegion, sourceKey);

String bucket = "examplebucket-1250000000"; //目标存储桶，格式：BucketName-APPID
String key = "exampleobject"; //目标对象的对象键

// copy(String bucket, String cosPath, CopyObjectRequest.CopySourceStruct copySourceStruct){
COSXMLCopyTask copyTask = transferManager.copy(bucket, key, copySource);
copyTask.setCosXmlResultListener(new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        try {
            // 复制成功后删除文件
            DeleteObjectRequest deleteObjectRequest = new DeleteObjectRequest(sourceBucket, sourceKey);
            DeleteObjectResult deleteResult = cosXmlService.deleteObject(deleteObjectRequest);
        } catch (CosXmlClientException e) {
            e.printStackTrace();
        } catch (CosXmlServiceException e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onFail(CosXmlRequest request, CosXmlClientException exception, CosXmlServiceException serviceException) {

    }
});
说明：
更多完整示例，请前往 GitHub 查看。

简单复制对象

复制文件到目标路径（PUT Object-Copy）。

前期准备：创建 CosXmlService

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

使用案例：复制对象时保留对象属性

String sourceBucket = "sourcebucket-1250000000"; //源对象所在的存储桶
String sourceRegion = "COS_REGION"; //源对象的存储桶所在的地域
String sourceCosPath = "sourceObject"; //源对象键
// 构造源对象属性
CopyObjectRequest.CopySourceStruct copySourceStruct =
        new CopyObjectRequest.CopySourceStruct(sourceBucket, sourceRegion, sourceCosPath);

// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即对象键
CopyObjectRequest copyObjectRequest = new CopyObjectRequest(bucket, cosPath,
        copySourceStruct);

cosXmlService.copyObjectAsync(copyObjectRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        CopyObjectResult copyObjectResult = (CopyObjectResult) 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();
        }
    }
});

使用案例：复制对象时替换对象属性

String sourceBucket = "sourcebucket-1250000000"; //源对象所在的存储桶
String sourceRegion = "COS_REGION"; //源对象的存储桶所在的地域
String sourceCosPath = "sourceObject"; //源对象键
// 构造源对象属性
CopyObjectRequest.CopySourceStruct copySourceStruct =
        new CopyObjectRequest.CopySourceStruct(sourceBucket, sourceRegion, sourceCosPath);

// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即对象键
CopyObjectRequest copyObjectRequest = new CopyObjectRequest(bucket, cosPath,
        copySourceStruct);
copyObjectRequest.setCopyMetaDataDirective(MetaDataDirective.REPLACED);
copyObjectRequest.setXCOSMeta("x-cos-metadata-oldKey", "newValue");

cosXmlService.copyObjectAsync(copyObjectRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        CopyObjectResult copyObjectResult = (CopyObjectResult) 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();
        }
    }
});

使用案例：修改对象元数据

// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String region = "COS_REGION"; //源对象的存储桶所在的地域
String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即对象键
// 构造源对象属性
CopyObjectRequest.CopySourceStruct copySourceStruct =
        new CopyObjectRequest.CopySourceStruct(bucket, region, cosPath);

CopyObjectRequest copyObjectRequest = new CopyObjectRequest(bucket, cosPath,
        copySourceStruct);
copyObjectRequest.setCopyMetaDataDirective(MetaDataDirective.REPLACED);
// 修改元数据为新值
copyObjectRequest.setXCOSMeta("x-cos-metadata-oldKey", "newValue");

cosXmlService.copyObjectAsync(copyObjectRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        CopyObjectResult copyObjectResult = (CopyObjectResult) 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();
        }
    }
});
说明：
更多完整示例，请前往 GitHub 查看。

使用案例：修改对象存储类型

// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String region = "COS_REGION"; //源对象的存储桶所在的地域
String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即对象键
// 构造源对象属性
CopyObjectRequest.CopySourceStruct copySourceStruct =
        new CopyObjectRequest.CopySourceStruct(bucket, region, cosPath);

CopyObjectRequest copyObjectRequest = new CopyObjectRequest(bucket, cosPath,
        copySourceStruct);
// 修改为低频存储
copyObjectRequest.setCosStorageClass(COSStorageClass.STANDARD_IA);

cosXmlService.copyObjectAsync(copyObjectRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        CopyObjectResult copyObjectResult = (CopyObjectResult) 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();
        }
    }
});
说明：
更多完整示例，请前往 GitHub 查看。

SDK API 参考

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

API 操作

关于简单操作的 API 接口说明，请参见 PUT Object - Copy 文档。
关于分块操作的 API 接口说明，请参见 List Multipart Uploads 、Initiate Multipart Upload 、Upload Part - Copy 、List Parts、Abort Multipart Upload、Complete Multipart Upload文档。
关于删除对象的 API 接口说明，请参见 DETELE Object 文档。
上一篇: 下载对象下一篇: 列出对象

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈