tencent cloud

对象存储

动态与公告
产品动态
产品公告
产品简介
产品概述
功能概览
应用场景
产品优势
基本概念
地域和访问域名
规格与限制
产品计费
计费概述
计费方式
计费项
免费额度
计费示例
查看和下载账单
欠费说明
常见问题
快速入门
控制台快速入门
COSBrowser 快速入门
用户指南
创建请求
存储桶
对象
数据管理
批量处理
全球加速
监控与告警
运维中心
数据处理
内容审核
智能工具箱
数据工作流
应用集成
工具指南
工具概览
环境安装与配置
COSBrowser 工具
COSCLI 工具
COSCMD 工具
COS Migration 工具
FTP Server 工具
Hadoop 工具
COSDistCp 工具
HDFS TO COS 工具
GooseFS-Lite 工具
在线辅助工具
自助诊断工具
实践教程
概览
访问控制与权限管理
性能优化
使用 AWS S3 SDK 访问 COS
数据容灾备份
域名管理实践
图片处理实践
COS 音视频播放器实践
工作流实践
数据直传
内容审核实践
数据安全
数据校验
大数据实践
COS 成本优化解决方案
在第三方应用中使用 COS
迁移指南
本地数据迁移至 COS
第三方云存储数据迁移至 COS
以 URL 作为源地址的数据迁移至 COS
COS 之间数据迁移
Hadoop 文件系统与 COS 之间的数据迁移
数据湖存储
云原生数据湖
元数据加速
数据加速器 GooseFS
数据处理
数据处理概述
图片处理
媒体处理
内容审核
文件处理
文档处理
故障处理
获取 RequestId 操作指引
通过外网上传文件至 COS 缓慢
访问 COS 时返回403错误码
资源访问异常
POST Object 常见异常
API 文档
简介
公共请求头部
公共响应头部
错误码
请求签名
操作列表
Service 接口
Bucket 接口
Object 接口
批量处理接口
数据处理接口
任务与工作流
内容审核接口
云查毒接口
SDK 文档
SDK 概览
准备工作
Android SDK
C SDK
C++ SDK
.NET(C#) SDK
Flutter SDK
Go SDK
iOS SDK
Java SDK
JavaScript SDK
Node.js SDK
PHP SDK
Python SDK
React Native SDK
小程序 SDK
错误码
鸿蒙(Harmony) SDK
终端 SDK 质量优化
安全与合规
数据容灾
数据安全
访问管理
常见问题
热门问题
一般性问题
计费计量问题
域名合规问题
存储桶配置问题
域名和 CDN 问题
文件操作问题
日志监控问题
权限管理问题
数据处理问题
数据安全问题
预签名 URL 问题
SDK 类问题
工具类问题
API 类问题
服务协议
Service Level Agreement
隐私政策
数据处理和安全协议
联系我们
词汇表

上传对象

PDF
聚焦模式
字号
最后更新时间: 2026-02-27 15:22:42

简介

本文介绍对象存储 COS 通过 Android SDK 实现上传对象功能的示例代码和描述。包括高级接口、简单接口、分块上传三个部分。

注意事项

若您使用简单上传,需要具有目标对象的写权限:在您进行 授权策略 时,action 需要设置为cos:PutObject ,更多授权请参见 支持 CAM 的业务接口
若您使用高级接口的自动分块上传或使用简单接口实现分块上传,需要具有目标对象的初始化分块上传、上传分块、完成分块上传的权限:在您进行 授权策略 时,action 需要设置为 cos:InitiateMultipartUploadcos:UploadPartcos:CompleteMultipartUpload,更多授权请参见 支持 CAM 的业务接口
若您使用高级接口的断点续传,需要具有目标对象的初始化分块上传、上传分块、完成分块上传、列举分块上传任务、列举已上传分块的权限:在您进行 授权策略 时,action 需要设置为 cos:InitiateMultipartUploadcos:UploadPartcos:CompleteMultipartUploadcos:ListMultipartUploadscos:ListParts更多授权请参见 支持 CAM 的业务接口

相关示例

功能名称
描述
示例代码
高级接口
高级接口封装了简单上传、分块上传接口,根据文件大小智能的选择上传方式,同时支持断点续传功能。
简单接口
PUT Object 接口可以上传一个对象至指定存储桶中,不支持自动分块上传和断点续传。最大支持上传不超过5GB的对象,5GB以上对象请使用 分块上传 或 高级接口 上传。
分块操作
分块上传可以实现将整个对象切分为多个分块,然后再将这些分块上传到对象存储(Cloud Object Storage,COS)。

高级接口(推荐)

高级接口封装了简单上传、分块上传接口,根据文件大小智能的选择上传方式,同时支持续传功能。
注意:
分块阈值用来区分使用简单上传还是分块上传,阈值支持用户自行配置,默认为2MB。
分块大小支持用户自行配置,默认为1MB。
对文件类型的上传,小于分块阈值的文件,高级接口会选择简单上传,大于分块阈值的文件,高级接口会选择分块上传。
对于文件类型的分块上传,高级接口会多线程并发同时上传多个分块。
对于分块上传,高级上传接口提供获取进度的功能,具体参见下面的示例。
流式上传或者二进制上传仅支持普通上传,不支持分块上传。

前期准备:创建 TransferManager

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

使用案例:上传本地文件

// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject.txt"; //对象在存储桶中的位置标识符,即称对象键
String srcPath = new File(context.getCacheDir(), "exampleobject.txt")
.toString(); //本地文件的绝对路径
//若存在初始化分块上传的 UploadId,则赋值对应的 uploadId 值用于续传;否则,赋值 null
String uploadId = null;

// 上传文件
COSXMLUploadTask cosxmlUploadTask = transferManager.upload(bucket, cosPath,
srcPath, uploadId);

//设置初始化分块上传回调,用于获取uploadId (5.9.7版本以及后续版本支持)
cosxmlUploadTask.setInitMultipleUploadListener(new InitMultipleUploadListener() {
@Override
public void onSuccess(InitiateMultipartUpload initiateMultipartUpload) {
//用于下次续传上传的 uploadId
String uploadId = initiateMultipartUpload.uploadId;
}
});
//设置上传进度回调
cosxmlUploadTask.setCosXmlProgressListener(new CosXmlProgressListener() {
@Override
public void onProgress(long complete, long target) {
// todo Do something to update progress...
}
});
//设置返回结果回调
cosxmlUploadTask.setCosXmlResultListener(new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest request, CosXmlResult result) {
COSXMLUploadTask.COSXMLUploadTaskResult uploadResult =
(COSXMLUploadTask.COSXMLUploadTaskResult) 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();
}
}
});
//设置任务状态回调, 可以查看任务过程
cosxmlUploadTask.setTransferStateListener(new TransferStateListener() {
@Override
public void onStateChanged(TransferState state) {
// todo notify transfer state
}
});
说明:
上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名 URL 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

使用案例:上传二进制数据

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

// 上传字节数组
byte[] bytes = "this is a test".getBytes(Charset.forName("UTF-8"));
COSXMLUploadTask cosxmlUploadTask = transferManager.upload(bucket, cosPath,
bytes);

//设置返回结果回调
cosxmlUploadTask.setCosXmlResultListener(new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest request, CosXmlResult result) {
COSXMLUploadTask.COSXMLUploadTaskResult uploadResult =
(COSXMLUploadTask.COSXMLUploadTaskResult) 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();
}
}
});
说明:
上传二进制数据仅支持普通上传,不支持分块上传。
上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名 URL 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

使用案例:流式上传

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

// 流式上传
InputStream inputStream =
new ByteArrayInputStream("this is a test".getBytes(Charset.forName(
"UTF-8")));
COSXMLUploadTask cosxmlUploadTask = transferManager.upload(bucket, cosPath,
inputStream);

//设置返回结果回调
cosxmlUploadTask.setCosXmlResultListener(new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest request, CosXmlResult result) {
COSXMLUploadTask.COSXMLUploadTaskResult uploadResult =
(COSXMLUploadTask.COSXMLUploadTaskResult) 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();
}
}
});
说明:
流式上传仅支持普通上传,不支持分块上传。
上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名 URL 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

使用案例:通过 URI 上传

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

// 文件的 Uri
Uri uri = Uri.parse("exampleObject");
// 若存在初始化分块上传的 UploadId,则赋值对应的 uploadId 值用于续传;否则,赋值 null
String uploadId = null;
COSXMLUploadTask cosxmlUploadTask = transferManager.upload(bucket, cosPath,
uri, uploadId);

//设置返回结果回调
cosxmlUploadTask.setCosXmlResultListener(new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest request, CosXmlResult result) {
COSXMLUploadTask.COSXMLUploadTaskResult uploadResult =
(COSXMLUploadTask.COSXMLUploadTaskResult) 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();
}
}
});
说明:
上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名 URL 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

使用案例:上传暂停、继续与取消

对于上传任务,可以通过以下方式暂停:
// 如果上传过程中,已经发起了最后的 Complete Multipart Upload 请求,那么暂停会失败
boolean pauseSuccess = cosxmlUploadTask.pauseSafely();
暂停之后,可以通过以下方式续传:
// 如果暂停成功,可以恢复上传
if (pauseSuccess) {
cosxmlUploadTask.resume();
}
也可以通过以下方式取消上传:
cosxmlUploadTask.cancel();

使用案例:批量上传

//本地文件的绝对路径
File[] files = new File(context.getCacheDir(), "exampleDirectory").listFiles();

// 开始批量上传
for (File file : files) {
//若存在初始化分块上传的 UploadId,则赋值对应的 uploadId 值用于续传;否则,赋值 null
String uploadId = null;

// 上传文件
COSXMLUploadTask cosxmlUploadTask = transferManager.upload(bucket, cosPath,
file.getAbsolutePath(), uploadId);

//设置返回结果回调
cosxmlUploadTask.setCosXmlResultListener(new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest request, CosXmlResult result) {
COSXMLUploadTask.COSXMLUploadTaskResult uploadResult =
(COSXMLUploadTask.COSXMLUploadTaskResult) 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();
}
}
});
}

使用案例:创建目录

// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
// 文件夹在存储桶中的位置标识符,即称对象键,必须以 '/' 结尾
String cosPath = "exampleobject/";
PutObjectRequest putObjectRequest = new PutObjectRequest(bucket, cosPath, new byte[0]);
cosXmlService.putObjectAsync(putObjectRequest, new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest request, CosXmlResult result) {
PutObjectResult putObjectResult =
(PutObjectResult) 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();
}
}
});

使用案例:设置低优先级任务

// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
// 文件夹在存储桶中的位置标识符,即称对象键,必须以 '/' 结尾
String cosPath = "exampleobject/";
String srcPath = new File(context.getCacheDir(), "exampleobject")
.toString(); //本地文件的绝对路径
PutObjectRequest putObjectRequest= new PutObjectRequest(bucket, cosPath, srcPath);
putObjectRequest.setPriorityLow(); // 设置为低优先级上传任务
final COSXMLUploadTask uploadTask = transferManager.upload(putObjectRequest, null);
uploadTask.setCosXmlResultListener(new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest request, CosXmlResult result) {}


@Override
public void onFail(CosXmlRequest request, CosXmlClientException clientException, CosXmlServiceException serviceException) {}
});

使用案例:上传时添加元数据

// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject.txt"; //对象在存储桶中的位置标识符,即称对象键
String srcPath = new File(context.getCacheDir(), "exampleobject.txt")
.toString(); //本地文件的绝对路径
//若存在初始化分块上传的 UploadId,则赋值对应的 uploadId 值用于续传;否则,赋值 null
String uploadId = null;

//上传文件,通过设置 x-cos-meta-*格式的请求头来为对象添加用户自定义元数据
PutObjectRequest putObjectRequest = new PutObjectRequest(bucket,cosPath,srcPath);
try {
putObjectRequest.setRequestHeaders("x-cos-meta-test", "testvalue", false);
} catch (CosXmlClientException e) {
e.printStackTrace();
}
COSXMLUploadTask cosxmlUploadTask = transferManager.upload(putObjectRequest, uploadId);

//设置返回结果回调
cosxmlUploadTask.setCosXmlResultListener(new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest request, CosXmlResult result) {
COSXMLUploadTask.COSXMLUploadTaskResult uploadResult =
(COSXMLUploadTask.COSXMLUploadTaskResult) 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();
}
}
});

简单上传

PUT Object 接口可以上传一个对象至指定存储桶中,该操作需要请求者对存储桶有 WRITE 权限。最大支持上传不超过5GB的对象,5GB以上对象请使用 分块上传高级接口 上传。
注意:
Key(文件名)不能以/结尾,否则会被识别为文件夹。
每个主账号(即同一个 APPID),存储桶的 ACL 规则数量最多为1000条,对象 ACL 规则数量不限制。如果您不需要进行对象 ACL 控制,请在上传时不要设置,默认继承存储桶权限。

前期准备:创建 CosXmlService

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

使用案例:上传本地文件

// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject.txt"; //对象位于存储桶中的位置标识符,即对象键。
String srcPath = new File(context.getCacheDir(), "exampleobject.txt")
.toString();//"本地文件的绝对路径";
PutObjectRequest putObjectRequest = new PutObjectRequest(bucket, cosPath,
srcPath);

putObjectRequest.setProgressListener(new CosXmlProgressListener() {
@Override
public void onProgress(long progress, long max) {
// todo Do something to update progress...
}
});
cosXmlService.putObjectAsync(putObjectRequest, new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest cosXmlRequest, CosXmlResult result) {
PutObjectResult putObjectResult = (PutObjectResult) 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();
}
}
});
说明:
上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名 URL 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

使用案例:上传二进制数据

// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject.txt"; //对象位于存储桶中的位置标识符,即对象键。
byte[] data = "this is a test".getBytes(Charset.forName("UTF-8"));
PutObjectRequest putObjectRequest = new PutObjectRequest(bucket, cosPath,
data);

putObjectRequest.setProgressListener(new CosXmlProgressListener() {
@Override
public void onProgress(long progress, long max) {
// todo Do something to update progress...
}
});
cosXmlService.putObjectAsync(putObjectRequest, new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest cosXmlRequest, CosXmlResult result) {
PutObjectResult putObjectResult = (PutObjectResult) 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();
}
}
});
说明:
上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名 URL 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

使用案例:流式上传

// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject.txt"; //对象位于存储桶中的位置标识符,即对象键。
InputStream inputStream = new ByteArrayInputStream("this is a test".getBytes(
Charset.forName("UTF-8")));
PutObjectRequest putObjectRequest = new PutObjectRequest(bucket, cosPath,
inputStream);

putObjectRequest.setProgressListener(new CosXmlProgressListener() {
@Override
public void onProgress(long progress, long max) {
// todo Do something to update progress...
}
});
cosXmlService.putObjectAsync(putObjectRequest, new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest cosXmlRequest, CosXmlResult result) {
PutObjectResult putObjectResult = (PutObjectResult) 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();
}
}
});
说明:
上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名 URL 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

分块操作

分块操作是大文件上传时,使用一系列分块,改善大文件上传耗时太久可能导致的各种中断问题。关于分块上传的更多说明请参见 分块上传。分块上传对象的操作流程如下。

操作流程

分块上传的流程

1. 初始化分块上传(Initiate Multipart Upload),得到 UploadId。
2. 使用 UploadId 上传分块(Upload Part),或者复制分块(Upload Part Copy)。
3. 完成分块上传(Complete Multipart Upload)。

分块继续上传的流程

1. 如果没有记录 UploadId,查询分块上传任务(List Multipart Uploads),得到对应文件的 UploadId。
2. 使用 UploadId 列出已上传的分块(List Parts)。
3. 使用 UploadId 上传剩余的分块(Upload Part),或者复制剩余的分块(Upload Part Copy)。
4. 完成分块上传(Complete Multipart Upload)。

终止分块上传的流程

1. 如果没有记录 UploadId,查询分块上传任务(List Multipart Uploads),得到对应文件的 UploadId。
2. 终止分块上传并删除已上传分块(Abort Multipart Upload)。

前期准备:创建 CosXmlService

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

使用案例:查询分块上传

查询指定存储桶中正在进行的分块上传(List Multipart Uploads)。
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
ListMultiUploadsRequest listMultiUploadsRequest =
new ListMultiUploadsRequest(bucket);
cosXmlService.listMultiUploadsAsync(listMultiUploadsRequest,
new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest cosXmlRequest, CosXmlResult result) {
ListMultiUploadsResult listMultiUploadsResult =
(ListMultiUploadsResult) 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();
}
}
});

使用案例:初始化分块上传

初始化 Multipart Upload 上传操作,获取对应的 uploadId(Initiate Multipart Upload)。
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject.txt"; //对象在存储桶中的位置标识符,即对象键。

InitMultipartUploadRequest initMultipartUploadRequest =
new InitMultipartUploadRequest(bucket, cosPath);
cosXmlService.initMultipartUploadAsync(initMultipartUploadRequest,
new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest cosXmlRequest, CosXmlResult result) {
// 分片上传的 uploadId
uploadId = ((InitMultipartUploadResult) result)
.initMultipartUpload.uploadId;
}

// 如果您使用 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();
}
}
});

使用案例:上传分块

分块上传对象(Upload Part)。
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject.txt"; //对象在存储桶中的位置标识符,即对象键
UploadPartRequest uploadPartRequest = new UploadPartRequest(bucket, cosPath,
partNumber, srcFile.getPath(), offset, PART_SIZE, uploadId);

uploadPartRequest.setProgressListener(new CosXmlProgressListener() {
@Override
public void onProgress(long progress, long max) {
// todo Do something to update progress...
}
});

cosXmlService.uploadPartAsync(uploadPartRequest, new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest cosXmlRequest, CosXmlResult result) {
String eTag = ((UploadPartResult) result).eTag;
eTags.put(partNumber, eTag);
}

// 如果您使用 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();
}
}
});

使用案例:查询已上传的分块

查询特定分块上传操作中的已上传的块(List Parts)。
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject.txt"; //对象在存储桶中的位置标识符,即对象键。

ListPartsRequest listPartsRequest = new ListPartsRequest(bucket, cosPath,
uploadId);
cosXmlService.listPartsAsync(listPartsRequest, new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest cosXmlRequest, CosXmlResult result) {
ListParts listParts = ((ListPartsResult) result).listParts;
}

// 如果您使用 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();
}
}
});

使用案例:完成分块上传

完成整个文件的分块上传(Complete Multipart Upload)。
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject.txt"; //对象在存储桶中的位置标识符,即对象键。

CompleteMultiUploadRequest completeMultiUploadRequest =
new CompleteMultiUploadRequest(bucket,
cosPath, uploadId, eTags);
cosXmlService.completeMultiUploadAsync(completeMultiUploadRequest,
new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest cosXmlRequest, CosXmlResult result) {
CompleteMultiUploadResult completeMultiUploadResult =
(CompleteMultiUploadResult) 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();
}
}
});

使用案例:终止分块上传

终止一个分块上传操作并删除已上传的块(Abort Multipart Upload)。
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject.txt"; //对象在存储桶中的位置标识符,即对象键。

AbortMultiUploadRequest abortMultiUploadRequest =
new AbortMultiUploadRequest(bucket,
cosPath, uploadId);
cosXmlService.abortMultiUploadAsync(abortMultiUploadRequest,
new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest cosXmlRequest, CosXmlResult result) {
AbortMultiUploadResult abortMultiUploadResult =
(AbortMultiUploadResult) 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 文档。
关于分块操作的 API 接口说明,请参见 List Multipart UploadsInitiate Multipart UploadUpload PartList PartsAbort Multipart UploadComplete Multipart Upload文档。

帮助和支持

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

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

文档反馈