tencent cloud

简介

本文档提供关于对象的上传操作相关的 API 概览以及 SDK 示例代码。

简单操作

API	操作名	操作描述
PUT Object	简单上传对象	上传一个对象至存储桶
POST Object	表单上传对象	使用表单请求上传对象
APPEND Object	追加上传对象	使用分块追加的方式上传对象

分块操作

API	操作名	操作描述
List Multipart Uploads	查询分块上传	查询正在进行中的分块上传信息
Initiate Multipart Upload	初始化分块上传	初始化分块上传操作
Upload Part	上传分块	分块上传对象
Upload Part - Copy	复制分块	将其他对象复制为一个分块
List Parts	查询已上传块	查询特定分块上传操作中的已上传的块
Complete Multipart Upload	完成分块上传	完成整个文件的分块上传
Abort Multipart Upload	终止分块上传	终止一个分块上传操作并删除已上传的块

高级接口（推荐）

高级 API 由类 TransferManager 通过封装各个简单接口，来提供更便捷操作的接口。内部使用一个线程池，来并发接受和处理用户的请求，因此用户也可选择提交多个任务之后异步的执行任务。

TransferManager 实例是并发安全的，这里推荐一个进程只创建一个 TransferManager 实例，当不会再通过这个实例调用高级接口的时候，再选择关闭这个实例。

功能说明

高级接口封装了简单上传、分块上传接口，根据文件大小智能的选择上传方式，同时支持续传、上传时显示进度等功能。

说明：

• 分块阈值用来区分使用简单上传还是分块上传，阈值支持用户自行配置，默认为5MB。
• 分块大小支持用户自行配置，默认为1MB。
• 对流类型的上传，小于分块阈值或未指定 Content-Length 头部的上传，高级接口会选择简单上传。
• 对流类型的上传，大于分块阈值且指定 Content-Length 头部的上传，高级接口会选择分块上传。
• 对文件类型的上传，小于分块阈值的文件，高级接口会选择简单上传，大于分块阈值的文件，高级接口会选择分块上传。
• 对于文件类型的分块上传，高级接口会多线程并发同时上传多个分块。
• 对于分块上传，高级上传接口提供获取进度的功能，具体参见下面的示例。

创建 TransferManager

使用高级接口的操作之前，必须先创建一个 TransferManager 的实例。

// 创建 TransferManager 实例，这个实例用来后续调用高级接口
TransferManager createTransferManager() {
  // 创建一个 COSClient 实例，这是访问 COS 服务的基础实例。
  // 详细代码参见本页: 简单操作 -> 创建 COSClient
  COSClient cosClient = createCOSClient();
   // 自定义线程池大小，建议在客户端与 COS 网络充足（例如使用腾讯云的 CVM，同地域上传 COS）的情况下，设置成16或32即可，可较充分的利用网络资源
  // 对于使用公网传输且网络带宽质量不高的情况，建议减小该值，避免因网速过慢，造成请求超时。
  ExecutorService threadPool = Executors.newFixedThreadPool(32);
   // 传入一个 threadpool, 若不传入线程池，默认 TransferManager 中会生成一个单线程的线程池。
  TransferManager transferManager = new TransferManager(cosClient, threadPool);
   // 设置高级接口的配置项
  // 分块上传阈值和分块大小分别为 5MB 和 1MB
  TransferManagerConfiguration transferManagerConfiguration = new TransferManagerConfiguration();
  transferManagerConfiguration.setMultipartUploadThreshold(5*1024*1024);
  transferManagerConfiguration.setMinimumUploadPartSize(1*1024*1024);
  transferManager.setConfiguration(transferManagerConfiguration);
   return transferManager;
}

参数说明

TransferManagerConfiguration 类用于记录高级接口的配置信息，其主要成员说明如下：

成员名	设置方法	描述	类型
minimumUploadPartSize	set 方法	分块上传的块大小，单位：字节（Byte），默认为5MB	long
multipartUploadThreshold	set 方法	大于等于该值则并发的分块上传文件，单位：字节（Byte），默认为5MB	long
multipartCopyThreshold	set 方法	大于等于该值则并发的分块复制文件，单位：字节（Byte），默认为5GB	long
multipartCopyPartSize	set 方法	分块复制的块大小，单位：字节（Byte），默认为100MB	long

关闭 TransferManager

在确定不再通过 TransferManager 的实例调用高级接口之后，一定要关闭这个实例，防止资源泄露。

void shutdownTransferManager(TransferManager transferManager) {
  // 指定参数为 true, 则同时会关闭 transferManager 内部的 COSClient 实例。
  // 指定参数为 false, 则不会关闭 transferManager 内部的 COSClient 实例。
  transferManager.shutdownNow(true);
}

上传本地文件

上传的源是本地的一个文件。

方法原型

// 上传对象
public Upload upload(final PutObjectRequest putObjectRequest)
          throws CosServiceException, CosClientException;

请求示例

// 使用高级接口必须先保证本进程存在一个 TransferManager 实例，如果没有则创建
// 详细代码参见本页：高级接口 -> 创建 TransferManager
TransferManager transferManager = createTransferManager();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// 本地文件路径
String localFilePath = "/path/to/localFile";
File localFile = new File(localFilePath);
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
try {
  // 高级接口会返回一个异步结果Upload
  // 可同步地调用 waitForUploadResult 方法等待上传完成，成功返回UploadResult, 失败抛出异常
  Upload upload = transferManager.upload(putObjectRequest);
  UploadResult uploadResult = upload.waitForUploadResult();
} catch (CosServiceException e) {
  e.printStackTrace();
} catch (CosClientException e) {
  e.printStackTrace();
} catch (InterruptedException e) {
  e.printStackTrace();
}
// 确定本进程不再使用 transferManager 实例之后，关闭之
// 详细代码参见本页：高级接口 -> 关闭 TransferManager
shutdownTransferManager(transferManager);

参数说明

参数名称	描述	类型
putObjectRequest	上传文件请求	PutObjectRequest

Request 成员说明：

Request 成员	设置方法	描述	类型
bucketName	构造函数或 set 方法	存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范	String
key	构造函数或 set 方法	对象键（Key）是对象在存储桶中的唯一标识。 例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键	String
file	构造函数或 set 方法	本地文件	File
input	构造函数或 set 方法	输入流	InputStream
metadata	构造函数或 set 方法	文件的元数据	ObjectMetadata
trafficLimit	set 方法	用于对上传对象进行流量控制，单位：bit/s，默认不进行流量控制	Int

返回值

• 成功：返回 Upload，可以查询上传是否结束，也可同步的等待上传结束。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

返回参数说明

通过调用 Upload 的 waitForUploadResult() 方法获取的上传对象信息记录在类 UploadResult 中，类 UploadResult 主要成员说明如下：

成员名称	描述	类型
bucketName	存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范	String
key	对象键（Key）是对象在存储桶中的唯一标识。 例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键	String
requestId	请求 Id	String
dateStr	当前服务端时间	String
versionId	当存储桶开启了版本控制功能，返回对象的版本号 Id	String
crc64Ecma	服务端根据对象内容计算出来的 CRC64	String

上传流类型

上传的源是一个 InputStream 类型（和其子类型）的流实例。

方法原型

// 上传对象
public Upload upload(final PutObjectRequest putObjectRequest)
          throws CosServiceException, CosClientException;

请求示例

// 使用高级接口必须先保证本进程存在一个 TransferManager 实例，如果没有则创建
// 详细代码参见本页：高级接口 -> 创建 TransferManager
TransferManager transferManager = createTransferManager();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// 这里创建一个 ByteArrayInputStream 来作为示例，实际中这里应该是您要上传的 InputStream 类型的流
long inputStreamLength = 1024 * 1024;
byte data[] = new byte[inputStreamLength];
InputStream inputStream = new ByteArrayInputStream(data);
ObjectMetadata objectMetadata = new ObjectMetadata();
// 上传的流如果能够获取准确的流长度，则推荐一定填写 content-length
// 如果确实没办法获取到，则下面这行可以省略，但同时高级接口也没办法使用分块上传了
objectMetadata.setContentLength(inputStreamLength);
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, inputStream, objectMetadata);
try {
  // 高级接口会返回一个异步结果Upload
  // 可同步地调用 waitForUploadResult 方法等待上传完成，成功返回UploadResult, 失败抛出异常
  Upload upload = transferManager.upload(putObjectRequest);
  UploadResult uploadResult = upload.waitForUploadResult();
} catch (CosServiceException e) {
  e.printStackTrace();
} catch (CosClientException e) {
  e.printStackTrace();
} catch (InterruptedException e) {
  e.printStackTrace();
}
// 确定本进程不再使用 transferManager 实例之后，关闭之
// 详细代码参见本页：高级接口 -> 关闭 TransferManager
shutdownTransferManager(transferManager);

参数说明

参数名称	描述	类型
putObjectRequest	上传文件请求	PutObjectRequest

Request 成员说明：

Request 成员	设置方法	描述	类型
bucketName	构造函数或 set 方法	存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范	String
key	构造函数或 set 方法	对象键（Key）是对象在存储桶中的唯一标识。 例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键	String
file	构造函数或 set 方法	本地文件	File
input	构造函数或 set 方法	输入流	InputStream
metadata	构造函数或 set 方法	文件的元数据	ObjectMetadata
trafficLimit	set 方法	用于对上传对象进行流量控制，单位：bit/s，默认不进行流量控制	Int

返回值

• 成功：返回 Upload，可以查询上传是否结束，也可同步的等待上传结束。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

返回参数说明

通过调用 Upload 的 waitForUploadResult() 方法获取的上传对象信息记录在类 UploadResult 中，类 UploadResult 主要成员说明如下：

成员名称	描述	类型
bucketName	存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范	String
key	对象键（Key）是对象在存储桶中的唯一标识。 例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键	String
requestId	请求 Id	String
dateStr	当前服务端时间	String
versionId	当存储桶开启了版本控制功能，返回对象的版本号 Id	String
crc64Ecma	服务端根据对象内容计算出来的 CRC64	String

显示上传进度

说明：

只有使用了分块上传的接口才能显示上传进度。

要显示上传进度首先需要一个自己的打印上传进度的函数，在这个函数里通过调用接口来获取已经成功上传的大小从而计算出当前进度。

方法原型

// 上传对象
public Upload upload(final PutObjectRequest putObjectRequest)
          throws CosServiceException, CosClientException;

请求示例

// 可以参考下面的例子，结合实际情况做调整
void showTransferProgress(Transfer transfer) {
  // 这里的 Transfer 是异步上传结果 Upload 的父类
  System.out.println(transfer.getDescription());
   // transfer.isDone() 查询上传是否已经完成
  while (transfer.isDone() == false) {
      try {
          // 每 2 秒获取一次进度
          Thread.sleep(2000);
      } catch (InterruptedException e) {
          return;
      }
       TransferProgress progress = transfer.getProgress();
      long sofar = progress.getBytesTransferred();
      long total = progress.getTotalBytesToTransfer();
      double pct = progress.getPercentTransferred();
      System.out.printf("upload progress: [%d / %d] = %.02f%%\n", sofar, total, pct);
  }
   // 完成了 Completed，或者失败了 Failed
  System.out.println(transfer.getState());
}

结合上传文件的代码示例如下：

// 使用高级接口必须先保证本进程存在一个 TransferManager 实例，如果没有则创建
// 详细代码参见本页：高级接口 -> 创建 TransferManager
TransferManager transferManager = createTransferManager();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// 本地文件路径
String localFilePath = "/path/to/localFile";
File localFile = new File(localFilePath);
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
try {
  // 高级接口会返回一个异步结果Upload
  Upload upload = transferManager.upload(putObjectRequest);
  // 打印上传进度，直到上传结束
  showTransferProgress(upload);
  // 捕获可能出现的异常
  UploadResult uploadResult = upload.waitForUploadResult();
} catch (CosServiceException e) {
  e.printStackTrace();
} catch (CosClientException e) {
  e.printStackTrace();
} catch (InterruptedException e) {
  e.printStackTrace();
}
// 确定本进程不再使用 transferManager 实例之后，关闭之
// 详细代码参见本页：高级接口 -> 关闭 TransferManager
shutdownTransferManager(transferManager);

获取进度说明

通过 upload 这个类的 getProgress 可以获得一个 TransferProgress 类，这个类的下面三个方法用来获取上传进度，说明如下：

方法名称	描述	类型
getBytesTransferred	获取已上传的字节数	long
getTotalBytesToTransfer	获取总文件的字节数	long
getPercentTransferred	获取已上传的字节百分比	double

参数说明

参数名称	描述	类型
putObjectRequest	上传文件请求	PutObjectRequest

Request 成员说明：

Request 成员	设置方法	描述	类型
bucketName	构造函数或 set 方法	存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范	String
key	构造函数或 set 方法	对象键（Key）是对象在存储桶中的唯一标识。 例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键	String
file	构造函数或 set 方法	本地文件	File
input	构造函数或 set 方法	输入流	InputStream
metadata	构造函数或 set 方法	文件的元数据	ObjectMetadata
trafficLimit	set 方法	用于对上传对象进行流量控制，单位：bit/s，默认不进行流量控制	Int

返回值

• 成功：返回 Upload，可以查询上传是否结束，也可同步的等待上传结束。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

返回参数说明

通过调用 Upload 的 waitForUploadResult() 方法获取的上传对象信息记录在类 UploadResult 中，类 UploadResult 主要成员说明如下：

成员名称	描述	类型
bucketName	存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范	String
key	对象键（Key）是对象在存储桶中的唯一标识。 例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键	String
requestId	请求 ID	String
dateStr	当前服务端时间	String
versionId	当存储桶开启了版本控制功能，返回对象的版本号 ID	String
crc64Ecma	服务端根据对象内容计算出来的 CRC64	String

上传时暂停、继续与取消

使用高级接口可以暂停上传任务、随后继续上传，或者直接取消一个上传任务。

说明：

• 流式上传不可以暂停、继续与取消。
• 简单上传不可以暂停、继续与取消。
• 加密上传不可以暂停、继续与取消。

方法原型

// 上传对象
public Upload upload(final PutObjectRequest putObjectRequest)
          throws CosServiceException, CosClientException;

请求示例

// 使用高级接口必须先保证本进程存在一个 TransferManager 实例，如果没有则创建
// 详细代码参见本页：高级接口 -> 示例代码：创建 TransferManager
TransferManager transferManager = createTransferManager();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// 本地文件路径
String localFilePath = "/path/to/localFile";
File localFile = new File(localFilePath);
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
try {
  // 高级接口会返回一个异步结果Upload
  Upload upload = transferManager.upload(putObjectRequest);
  // 等待 3 秒，上传一部分
  Thread.sleep(3000);
  // 暂停上传，获取一个 PersistableUpload 实例，用来随后的恢复
  PersistableUpload persistableUpload = upload.pause();
  // 复杂的暂停与继续用法：
  // PersistableUpload 实例也可以通过 serialize 序列化后存储起来，之后再通过 deserialize 反序列化来恢复继续上传
  // persistableUpload.serialize(out);
  // 继续上传
  upload = transferManager.resumeUpload(persistableUpload);
  // 捕获可能出现的异常
  UploadResult uploadResult = upload.waitForUploadResult();
   // 或者直接取消这次上传
  // upload.abort();
} catch (CosServiceException e) {
  e.printStackTrace();
} catch (CosClientException e) {
  e.printStackTrace();
} catch (InterruptedException e) {
  e.printStackTrace();
}
// 确定本进程不再使用 transferManager 实例之后，关闭之
// 详细代码参见本页：高级接口 -> 示例代码：关闭 TransferManager
shutdownTransferManager(transferManager);

参数说明

参数名称	描述	类型
putObjectRequest	上传文件请求	PutObjectRequest

Request 成员说明：

Request 成员	设置方法	描述	类型
bucketName	构造函数或 set 方法	存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范	String
key	构造函数或 set 方法	对象键（Key）是对象在存储桶中的唯一标识。 例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键	String
file	构造函数或 set 方法	本地文件	File
input	构造函数或 set 方法	输入流	InputStream
metadata	构造函数或 set 方法	文件的元数据	ObjectMetadata
trafficLimit	set 方法	用于对上传对象进行流量控制，单位：bit/s，默认不进行流量控制	Int

返回值

• 成功：返回 Upload，可以查询上传是否结束，也可同步的等待上传结束。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

返回参数说明

通过调用 Upload 的 waitForUploadResult() 方法获取的上传对象信息记录在类 UploadResult 中，类 UploadResult 主要成员说明如下：

成员名称	描述	类型
bucketName	存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范	String
key	对象键（Key）是对象在存储桶中的唯一标识。 例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键	String
requestId	请求 ID	String
dateStr	当前服务端时间	String
versionId	当存储桶开启了版本控制功能，返回对象的版本号 ID	String
crc64Ecma	服务端根据对象内容计算出来的 CRC64	String

上传本地目录

TransferManager 实例封装了从本地一个目录来读取文件并且上传到 COS 的功能，这个功能可以在不破坏目录结构的情况下，将文件上传。同时，也可以指定将目录下的文件上传到另一个目录。

说明：

支持递归上传目录，如果上传目录太大，可能会存在上传较慢或阻塞太久的情况。如果需要递归上传目录，则建议上传小容量的目录（例如有 1024 以上个文件）。如果需要上传大容量目录，建议分成多个小目录进行分次调用。

方法原型

public MultipleFileUpload uploadDirectory(String bucketName, String virtualDirectoryKeyPrefix,
          File directory, boolean includeSubdirectories);

请求示例

// 使用高级接口必须先保证本进程存在一个 TransferManager 实例，如果没有则创建
// 详细代码参见本页：高级接口 -> 示例代码：创建 TransferManager
TransferManager transferManager = createTransferManager();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 设置文件上传到 bucket 之后的前缀目录，设置为 “”，表示上传到 bucket 的根目录
String cos_path = "/prefix";
// 要上传的文件夹的绝对路径
String dir_path = "/path/to/localdir";
// 是否递归上传目录下的子目录，如果是 true，子目录下的文件也会上传，且cos上会保持目录结构
Boolean recursive = false;
try {
  // 返回一个异步结果Upload, 可同步的调用waitForUploadResult等待upload结束, 成功返回UploadResult, 失败抛出异常.
  MultipleFileUpload upload = transferManager.uploadDirectory(bucketName, cos_path, new File(dir_path), recursive);
   // 可以选择查看上传进度，这个函数参见 高级接口 -> 上传文件 -> 显示上传进度
  showTransferProgress(upload);
   // 或者阻塞等待完成
  upload.waitForCompletion();
} catch (CosServiceException e) {
  e.printStackTrace();
} catch (CosClientException e) {
  e.printStackTrace();
} catch (InterruptedException e) {
  e.printStackTrace();
}
// 确定本进程不再使用 transferManager 实例之后，关闭之
// 详细代码参见本页：高级接口 -> 示例代码：关闭 TransferManager
shutdownTransferManager(transferManager);

参数说明

参数名称	描述	类型
bucketName	cos 上的 bucket	GetObjectRequest
virtualDirectoryKeyPrefix	cos 上 object 的前缀	String
directory	要上传的文件夹的绝对路径	File
includeSubDirectory	是否递归上传子目录	Boolean

返回值

• 成功：返回 MultipleFileUpload，可以查询上传是否结束，也可同步的等待上传结束。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

简单操作

简单操作由 COSClient 类型发起请求，使用简单操作之前必须先创建一个 COSClient 实例。

COSClient 实例是并发安全的，这里推荐一个进程只创建一个 COSClient 实例，当不会再通过这个实例发起请求的时候，再选择关闭这个实例。

创建 COSClient

调用 COS 的接口之前，必须先创建一个 COSClient 的实例。

// 创建 COSClient 实例，这个实例用来后续调用请求
COSClient createCOSClient() {
  // 设置用户身份信息。
  // SECRETID 和 SECRETKEY 请登录访问管理控制台 https://console.cloud.tencent.com/cam/capi 进行查看和管理
  String secretId = "SECRETID";
  String secretKey = "SECRETKEY";
  COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
   // ClientConfig 中包含了后续请求 COS 的客户端设置：
  ClientConfig clientConfig = new ClientConfig();
   // 设置 bucket 的地域
  // COS_REGION 请参照 https://intl.cloud.tencent.com/document/product/436/6224
  clientConfig.setRegion(new Region("COS_REGION"));
   // 设置请求协议, http 或者 https
  // 5.6.53 及更低的版本，建议设置使用 https 协议
  // 5.6.54 及更高版本，默认使用了 https
  clientConfig.setHttpProtocol(HttpProtocol.https);
   // 以下的设置，是可选的：
   // 设置 socket 读取超时，默认 30s
  clientConfig.setSocketTimeout(30*1000);
  // 设置建立连接超时，默认 30s
  clientConfig.setConnectionTimeout(30*1000);
   // 如果需要的话，设置 http 代理，ip 以及 port
  clientConfig.setHttpProxyIp("httpProxyIp");
  clientConfig.setHttpProxyPort(80);
   // 生成 cos 客户端。
  return new COSClient(cred, clientConfig);
}

使用临时密钥创建 COSClient

如果要使用临时密钥请求 COS，则需要用临时密钥创建 COSClient。
本 SDK 并不能生成临时密钥，而需要使用额外的操作来生成，参考 临时密钥生成。

// 创建 COSClient 实例，这个实例用来后续调用请求
COSClient createCOSClient() {
  // 这里需要已经获取到临时密钥的结果。
  // 临时密钥的生成参考 https://intl.cloud.tencent.com/document/product/436/14048
  String tmpSecretId = "TMPSECRETID";
  String tmpSecretKey = "TMPSECRETKEY";
  String sessionToken = "SESSIONTOKEN";
   COSCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);
   // ClientConfig 中包含了后续请求 COS 的客户端设置：
  ClientConfig clientConfig = new ClientConfig();
   // 设置 bucket 的地域
  // COS_REGION 请参照 https://intl.cloud.tencent.com/document/product/436/6224
  clientConfig.setRegion(new Region("COS_REGION"));
   // 设置请求协议, http 或者 https
  // 5.6.53 及更低的版本，建议设置使用 https 协议
  // 5.6.54 及更高版本，默认使用了 https
  clientConfig.setHttpProtocol(HttpProtocol.https);
   // 以下的设置，是可选的：
   // 设置 socket 读取超时，默认 30s
  clientConfig.setSocketTimeout(30*1000);
  // 设置建立连接超时，默认 30s
  clientConfig.setConnectionTimeout(30*1000);
   // 如果需要的话，设置 http 代理，ip 以及 port
  clientConfig.setHttpProxyIp("httpProxyIp");
  clientConfig.setHttpProxyPort(80);
   // 生成 cos 客户端。
  return new COSClient(cred, clientConfig);
}

上传本地文件

上传的源是本地的一个文件。

方法原型

// 方法1  将本地文件上传到 COS
public PutObjectResult putObject(String bucketName, String key, File file)
          throws CosClientException, CosServiceException;
// 方法2  输入流上传到 COS
public PutObjectResult putObject(String bucketName, String key, InputStream input, ObjectMetadata metadata)
          throws CosClientException, CosServiceException;
// 方法3  对以上两个方法的包装, 支持更细粒度的参数控制, 如 content-type,  content-disposition 等
public PutObjectResult putObject(PutObjectRequest putObjectRequest)
          throws CosClientException, CosServiceException;

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// 本地文件路径
String localFilePath = "/path/to/localFile";
File localFile = new File(localFilePath);
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
try {
  PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);
  System.out.println(putObjectResult.getRequestId());
} catch (CosServiceException e) {
  e.printStackTrace();
} catch (CosClientException e) {
  e.printStackTrace();
} catch (InterruptedException e) {
  e.printStackTrace();
}
// 确认本进程不再使用 cosClient 实例之后，关闭之
cosClient.shutdown();

参数说明

参数名称	描述	类型
putObjectRequest	上传文件请求	PutObjectRequest

Request 成员说明：

Request 成员	设置方法	描述	类型	必填
bucketName	构造函数或 set 方法	Bucket 的命名格式为 BucketName-APPID，详情请参见 命名规范	String	是
key	构造函数或 set 方法	对象键（Key）是对象在存储桶中的唯一标识。 例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg中，对象键为 doc/picture.jpg，详情请参见 对象键	String	是
file	构造函数或 set 方法	本地文件	File	否
input	构造函数或 set 方法	输入流	InputStream	否
metadata	构造函数或 set 方法	对象的元数据	ObjectMetadata	否
trafficLimit	set 方法	用于对上传对象进行流量控制，单位：bit/s，默认不进行流量控制	Int	否

ObjectMetadata 类用于记录对象的元信息，其主要成员说明如下：

成员名称	描述	类型
httpExpiresDate	缓存的超时时间，为 HTTP 响应头部中 Expires 字段的值	Date
ongoingRestore	正在从归档存储类型恢复该对象	Boolean
userMetadata	前缀为 x-cos-meta- 的用户自定义元信息	Map<String, String>
metadata	除用户自定义元信息以外的其他头部	Map<String, String>
restoreExpirationTime	归档对象恢复副本的过期时间	Date

返回结果说明

• 成功：PutObjectResult，包含文件的 eTag 等信息。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

返回参数说明

PutObjectResult 类用于返回结果信息，其主要成员说明如下：

成员名称	描述	类型
requestId	请求 ID	String
dateStr	当前服务端时间	String
versionId	开启版本控制的存储桶，返回对象的版本号 ID	String
eTag	简单上传接口返回对象的 MD5 值	String
crc64Ecma	服务端根据对象内容计算出来的 CRC64	String

上传流类型

上传的源是一个 InputStream 类型（和其子类型）的流实例。

方法原型

// 方法1  将本地文件上传到 COS
public PutObjectResult putObject(String bucketName, String key, File file)
          throws CosClientException, CosServiceException;
// 方法2  输入流上传到 COS
public PutObjectResult putObject(String bucketName, String key, InputStream input, ObjectMetadata metadata)
          throws CosClientException, CosServiceException;
// 方法3  对以上两个方法的包装, 支持更细粒度的参数控制, 如 content-type,  content-disposition 等
public PutObjectResult putObject(PutObjectRequest putObjectRequest)
          throws CosClientException, CosServiceException;

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// 这里创建一个 ByteArrayInputStream 来作为示例，实际中这里应该是您要上传的 InputStream 类型的流
long inputStreamLength = 1024 * 1024;
byte data[] = new byte[inputStreamLength];
InputStream inputStream = new ByteArrayInputStream(data);
ObjectMetadata objectMetadata = new ObjectMetadata();
// 上传的流如果能够获取准确的流长度，则推荐一定填写 content-length
// 如果确实没办法获取到，则下面这行可以省略，但同时高级接口也没办法使用分块上传了
objectMetadata.setContentLength(inputStreamLength);
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, inputStream, objectMetadata);
try {
  PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);
  System.out.println(putObjectResult.getRequestId());
} catch (CosServiceException e) {
  e.printStackTrace();
} catch (CosClientException e) {
  e.printStackTrace();
} catch (InterruptedException e) {
  e.printStackTrace();
}
// 确认本进程不再使用 cosClient 实例之后，关闭之
cosClient.shutdown();

参数说明

参数名称	描述	类型
putObjectRequest	上传文件请求	PutObjectRequest

Request 成员说明：

Request 成员	设置方法	描述	类型	必填
bucketName	构造函数或 set 方法	Bucket 的命名格式为 BucketName-APPID，详情请参见 命名规范	String	是
key	构造函数或 set 方法	对象键（Key）是对象在存储桶中的唯一标识。 例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg中，对象键为 doc/picture.jpg，详情请参见 对象键	String	是
file	构造函数或 set 方法	本地文件	File	否
input	构造函数或 set 方法	输入流	InputStream	否
metadata	构造函数或 set 方法	对象的元数据	ObjectMetadata	否
trafficLimit	set 方法	用于对上传对象进行流量控制，单位：bit/s，默认不进行流量控制	Int	否

ObjectMetadata 类用于记录对象的元信息，其主要成员说明如下：

成员名称	描述	类型
httpExpiresDate	缓存的超时时间，为 HTTP 响应头部中 Expires 字段的值	Date
ongoingRestore	正在从归档存储类型恢复该对象	Boolean
userMetadata	前缀为 x-cos-meta- 的用户自定义元信息	Map<String, String>
metadata	除用户自定义元信息以外的其他头部	Map<String, String>
restoreExpirationTime	归档对象恢复副本的过期时间	Date

返回结果说明

• 成功：PutObjectResult，包含文件的 eTag 等信息。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

返回参数说明

PutObjectResult 类用于返回结果信息，其主要成员说明如下：

成员名称	描述	类型
requestId	请求 ID	String
dateStr	当前服务端时间	String
versionId	开启版本控制的存储桶，返回对象的版本号 ID	String
eTag	简单上传接口返回对象的 MD5 值	String
crc64Ecma	服务端根据对象内容计算出来的 CRC64	String

创建目录

COS 本身没有目录的概念，但是可以将以 '/' 分隔的对象路径看做虚拟文件夹。

说明：

• 如果需要一个目录，可以直接往需要的目录上传一个文件，则目录会自动创建。例如：上传一个 /dir/example.txt 这样的文件，则 /dir 这个目录就自动生成了。这种情况请参考本页的上传本地文件。

如果需要一个下面没有文件的目录，则使用这里的办法：上传一个空流到一个以 '/' 结尾的路径，这样就有了一个虚拟的目录。

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 在这里指定要创建的目录的路径
String key = "/example/dir/";
// 这里创建一个空的 ByteArrayInputStream 来作为示例
byte data[] = new byte[0];
InputStream inputStream = new ByteArrayInputStream(data);
ObjectMetadata objectMetadata = new ObjectMetadata();
objectMetadata.setContentLength(0);
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, inputStream, objectMetadata);
try {
  PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);
  System.out.println(putObjectResult.getRequestId());
} catch (CosServiceException e) {
  e.printStackTrace();
} catch (CosClientException e) {
  e.printStackTrace();
} catch (InterruptedException e) {
  e.printStackTrace();
}
// 确认本进程不再使用 cosClient 实例之后，关闭之
cosClient.shutdown();

追加上传对象

以分段追加的方式上传对象。

方法原型

public AppendObjectResult appendObject(AppendObjectRequest appendObjectRequest)
      throws CosServiceException, CosClientException

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// 这里假定要追加上传的是这两个文件里的内容
File part1File = new File("/path/to/part1File");
File part2File = new File("/path/to/part2File");
try {
  AppendObjectRequest appendObjectRequest = new AppendObjectRequest(bucketName, key, part1File);
  appendObjectRequest.setPosition(0L);
  AppendObjectResult appendObjectResult = cosclient.appendObject(appendObjectRequest);
  long nextAppendPosition = appendObjectResult.getNextAppendPosition();
  System.out.println(nextAppendPosition);
   appendObjectRequest = new AppendObjectRequest(bucketName, key, part2File);
  appendObjectRequest.setPosition(nextAppendPosition);
  appendObjectResult = cosclient.appendObject(appendObjectRequest);
  nextAppendPosition = appendObjectResult.getNextAppendPosition();
  System.out.println(nextAppendPosition);
} catch (CosServiceException e) {
  e.printStackTrace();
} catch (CosClientException e) {
  e.printStackTrace();
}
// 关闭客户端
cosclient.shutdown();

参数说明

参数名称	描述	类型
appendObjectRequest	追加上传文件请求	AppendObjectRequest

AppendObjectRequest 成员说明：

Request 成员	设置方法	描述	类型	是否必填
bucketName	构造函数或 set 方法	Bucket 的命名格式为 BucketName-APPID，详情请参见 命名规范	String	是
key	构造函数或 set 方法	对象键（Key）是对象在存储桶中的唯一标识。 例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg中，对象键为 doc/picture.jpg，详情请参见 对象键	String	是
localfile	构造函数或 set 方法	本地文件	File	否
input	构造函数或 set 方法	输入流	InputStream	否
metadata	构造函数或 set 方法	对象的元数据	ObjectMetadata	否
trafficLimit	set 方法	用于对上传对象进行流量控制，单位：bit/s，默认不进行流量控制	Int	否
position	set 方法	追加操作的起始位置，单位：byte	Long	是

返回结果说明

• 成功：AppendObjectResult。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

返回参数说明

AppendObjectResult 类用于返回结果信息，其主要成员说明如下：

成员名称	描述	类型
metadata	返回头部	ObjectMetadata
nextAppendPosition	下一次追加的位置	Long

表单上传对象

使用表单请求上传对象。

构造表单上传的 form body

根据表单参数，构造上传最开始的 form body 部分

String buildPostObjectBody(String boundary, Map<String, String> formFields, String filename, String contentType) {
  StringBuffer stringBuffer = new StringBuffer();
  for(Map.Entry entry: formFields.entrySet()) {
      // 添加boundary行,行首以--开头
      stringBuffer.append("--").append(boundary).append("\r\n");
      // 字段名
      stringBuffer.append("Content-Disposition: form-data; name=\""
              + entry.getKey() + "\"\r\n\r\n");
      // 字段值
      stringBuffer.append(entry.getValue() + "\r\n");
  }
  // 添加boundary行,行首以--开头
  stringBuffer.append("--").append(boundary).append("\r\n");
  // 文件名
  stringBuffer.append("Content-Disposition: form-data; name=\"file\"; "
          + "filename=\"" + filename + "\"\r\n");
  // 文件类型
  stringBuffer.append("Content-Type: " + contentType + "\r\n\r\n");
  return stringBuffer.toString();
}

上传本地文件

// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// COS_REGION 请参照 https://intl.cloud.tencent.com/document/product/436/6224
String endpoint = "cos.{COS_REGION}.myqcloud.com";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// SECRETID 和 SECRETKEY 请登录访问管理控制台进行查看和管理
String secretId = "AKIDXXXXXXXX";
String seretKey = "1A2Z3YYYYYYYYYY";
String localFilePath = "/path/to/localFile";
String contentType = "image/jpeg";
long startTimestamp = System.currentTimeMillis() / 1000;
long endTimestamp = startTimestamp +  30 * 60;
String endTimestampStr = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'").format(endTimestamp * 1000);
String keyTime = startTimestamp + ";" + endTimestamp;
String boundary = "----WebKitFormBoundaryZBPbaoYE2gqeB21N";
// 设置表单的body字段值
Map<String, String> formFields = new HashMap<>();
formFields.put("q-sign-algorithm", "sha1");
formFields.put("key", key);
formFields.put("q-ak", secretId);
formFields.put("q-key-time", keyTime);
// 构造policy，参考文档: https://intl.cloud.tencent.com/document/product/436/14690
String policy = "{\n" +
      "    \"expiration\": \"" + endTimestampStr + "\",\n" +
      "    \"conditions\": [\n" +
      "        { \"bucket\": \"" + bucketName + "\" },\n" +
      "        { \"q-sign-algorithm\": \"sha1\" },\n" +
      "        { \"q-ak\": \"" + secretId + "\" },\n" +
      "        { \"q-sign-time\":\"" + keyTime + "\" }\n" +
      "    ]\n" +
      "}";
// policy需要base64后算放入表单中
String encodedPolicy = new String(Base64.encodeBase64(policy.getBytes()));
// 设置policy
formFields.put("policy", encodedPolicy);
// 根据编码后的policy和secretKey计算签名
COSSigner cosSigner = new COSSigner();
String signature = cosSigner.buildPostObjectSignature(seretKey,
      keyTime, policy);
// 设置签名
formFields.put("q-signature", signature);
// 根据以上表单参数，构造最开始的body部分
String formBody = buildPostObjectBody(boundary, formFields,
      localFilePath, contentType);
HttpURLConnection conn = null;
try {
  String urlStr = "http://" + bucketName + "." + endpoint;
  URL url = new URL(urlStr);
  conn = (HttpURLConnection) url.openConnection();
  conn.setRequestMethod("POST");
  conn.setRequestProperty("User-Agent", VersionInfoUtils.getUserAgent());
  conn.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
  conn.setDoOutput(true);
  conn.setDoInput(true);
   OutputStream out = new DataOutputStream(conn.getOutputStream());
  // 写入表单的最开始部分
  out.write(formBody.getBytes());
   // 将文件内容写入到输出流中
  File file = new File(localFilePath);
  DataInputStream in = new DataInputStream(new FileInputStream(file));
  int readBytes;
  byte[] bytes = new byte[4096];
  while ((readBytes = in.read(bytes)) != -1) {
      out.write(bytes, 0, readBytes);
  }
  in.close();
   // 添加最后一个分割符，行首和行尾都是--
  byte[] endData = ("\r\n--" + boundary + "--\r\n").getBytes();
  out.write(endData);
  out.flush();
  out.close();
   // 读取响应头部
  for (Map.Entry<String, List<String>> entries : conn.getHeaderFields().entrySet()) {
      String values = "";
      for (String value : entries.getValue()) {
          values += value + ",";
      }
      if(entries.getKey() == null) {
          System.out.println("reponse line:" +  values );
      } else {
          System.out.println(entries.getKey() + ":" +  values );
      }
  }
} catch (Exception e) {
  e.printStackTrace();
  throw e;
} finally {
  if (conn != null) {
      conn.disconnect();
  }
}

分块操作

分块操作是大文件上传时，使用一系列分块，改善大文件上传耗时太久可能导致的各种中断问题。

说明：

如果要上传的文件或者流可以完整获取，推荐使用高级接口。

操作流程

分块上传的流程

1. 初始化分块上传（Initiate Multipart Upload），得到 UploadId
2. 使用 UploadId 上传分块（Upload Part）
3. 完成分块上传（Complete Multipart Upload）

分块继续上传的流程

1. 如果没有记录 UploadId，则要先查询分块上传任务（List Multipart Uploads），得到对应文件的 UploadId
2. 使用 UploadId 列出已上传的分块（List Parts）
3. 使用 UploadId 上传剩余的分块（Upload Part）
4. 完成分块上传（Complete Multipart Upload）

终止分块上传的流程

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

初始化分块上传

初始化分块上传操作，获取对应的 uploadId 用于后续的操作。

方法原型

public InitiateMultipartUploadResult initiateMultipartUpload(
  InitiateMultipartUploadRequest request) throws CosClientException, CosServiceException;

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, key);
// 分块上传的过程中，仅能通过初始化分块指定文件上传之后的metadata
// 需要的头部可以在这里指定
ObjectMetadata objectMetadata = new ObjectMetadata();
request.setObjectMetadata(objectMetadata);
try {
  InitiateMultipartUploadResult initResult = cosClient.initiateMultipartUpload(request);
  // 获取uploadid
  String uploadId = initResult.getUploadId();
  System.out.println(uploadId);
} catch (CosServiceException e) {
  throw e;
} catch (CosClientException e) {
  throw e;
}

参数说明

参数名称	描述	类型
initiateMultipartUploadRequest	请求	InitiateMultipartUploadRequest

Request 成员说明：

参数名称	设置方法	描述	类型
bucketName	构造函数或 set 方法	Bucket 的命名格式为 BucketName-APPID ，详情请参见 命名规范	String
key	构造函数或 set 方法	指定分块上传到 COS 上的路径，即 对象键。例如对象键为 folder/picture.jpg	String

返回结果说明

• 成功：返回 InitiateMultipartUploadResult ，包含标志本次分块上传的 uploadId。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

查询分块上传任务

查询分块上传任务（List Multipart Uploads），获取当前正在进行的所有上传任务，从中找到需要处理的 uploadId。

方法原型

public MultipartUploadListing listMultipartUploads(
          ListMultipartUploadsRequest listMultipartUploadsRequest)
          throws CosClientException, CosServiceException

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 需要查询的分块上传任务对应的 key
String targetKey = "targetKey";
ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
// 每次请求最多列出多少个
listMultipartUploadsRequest.setMaxUploads(100);
// 设置要查询的分块上传任务的目标前缀，直接设置要查询的 key
listMultipartUploadsRequest.setPrefix("targetKey");
MultipartUploadListing multipartUploadListing = null;
boolean found = false;
do {
  multipartUploadListing = cosclient.listMultipartUploads(listMultipartUploadsRequest);
  List<MultipartUpload> multipartUploads = multipartUploadListing.getMultipartUploads();
   for (MultipartUpload mUpload : multipartUploads) {
      if (mUpload.getKey().equals(targetKey)) {
          System.out.println(mUpload.getUploadId());
          found = true;
          break;
      }
  }
   if (found) {
      break;
  }
} while (multipartUploadListing.isTruncated());
if (!found) {
  System.out.printf("do not found upload task with key: %s\n", targetKey);
}

参数说明

参数名称	描述	类型
listMultipartUploadsRequest	请求	ListMultipartUploadsRequest

Request 成员说明：

参数名称	描述	类型
bucketName	Bucket 的命名格式为 BucketName-APPID ，详情请参见 命名规范	String
keyMarker	列出条目从该 Key 值开始	String
delimiter	定界符为一个符号，如果有 Prefix，则将 Prefix 到 delimiter 之间的相同路径归为一类，定义为 Common Prefix，然后列出所有 Common Prefix。如果没有 Prefix，则从路径起点开始	String
prefix	限定返回的 Object key 必须以 Prefix 作为前缀。注意使用 prefix 查询时，返回的 key 中仍会包含 Prefix	String
uploadIdMarker	列出条目从该 UploadId 值开始	String
maxUploads	设置最大返回的 multipart 数量，合法值1到1000	String
encodingType	规定返回值的编码方式，可选值：url	String

返回结果说明

• 成功：返回 MultipartUploadListing，包含正在进行分块上传的信息。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

上传分块

分块上传对象（Upload Part）。

方法原型

public UploadPartResult uploadPart(UploadPartRequest uploadPartRequest) throws CosClientException, CosServiceException;

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// uploadId 是一次分块上传任务的唯一标识，通过初始化分块上传或者查询分块上传任务获得
String uploadId = "exampleuploadid";
// 每个分块上传之后都会得到一个返回值 etag，保存起来用于最后合并分块时使用
List<PartETag> partETags = new LinkedList<>();
// 上传数据, 这里上传 10 个 1M 的分块数据
for (int i = 1; i <= 10; i++) {
  byte data[] = new byte[1024 * 1024];
  // 这里创建一个 ByteArrayInputStream 来作为示例，实际中这里应该是您要上传的 InputStream 类型的流
  long inputStreamLength = 1024 * 1024;
  byte data[] = new byte[inputStreamLength];
  InputStream inputStream = new ByteArrayInputStream(data);
   UploadPartRequest uploadPartRequest = new UploadPartRequest();
  uploadPartRequest.setBucketName(bucketName);
  uploadPartRequest.setKey(key);
  uploadPartRequest.setUploadId(uploadId);
  uploadPartRequest.setInputStream(inputStream(data));
  // 设置分块的长度
  uploadPartRequest.setPartSize(data.length);
  // 设置要上传的分块编号，从 1 开始
  uploadPartRequest.setPartNumber(i);
   try {
      UploadPartResult uploadPartResult = cosClient.uploadPart(uploadPartRequest);
      PartETag partETag = uploadPartResult.getPartETag();
      partETags.add(partETag);
  } catch (CosServiceException e) {
      throw e;
  } catch (CosClientException e) {
      throw e;
  }
}
System.out.println(partETags);

参数说明

参数名称	描述	类型
uploadPartRequest	请求	UploadPartRequest

Request 成员说明：

参数名称	设置方法	描述	类型
bucketName	set 方法	Bucket 的命名格式为 BucketName-APPID ，详情请参见 命名规范	String
key	set 方法	指定分块上传到 COS 上的路径，即 对象键。例如对象键为 folder/picture.jpg	String
uploadId	set 方法	标识指定分块上传的 uploadId	String
partNumber	set 方法	标识指定分块的编号，必须 >= 1	int
inputStream	set 方法	待上传分块的输入流	InputStream
trafficLimit	set 方法	用于对上传分块进行流量控制，单位：bit/s，默认不进行流量控制	Int

返回结果说明

• 成功：返回 UploadPartResult，包含上传分块的 eTag 信息。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

返回参数说明

UploadPartResult 类用于返回结果信息，其主要成员说明如下：

成员名称	描述	类型
partNumber	标识指定分块的编号	String
eTag	返回上传分块的 MD5 值	String
crc64Ecma	服务端根据分块内容计算出来的 CRC64	String

查询已上传的分块

查询特定分块上传操作中的已上传的块（List Parts）。

方法原型

public PartListing listParts(ListPartsRequest request)
          throws CosClientException, CosServiceException;

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// uploadId 是一次分块上传任务的唯一标识，通过初始化分块上传或者查询分块上传任务获得
String uploadId = "exampleuploadid";
// 用于保存已上传的分片信息
List<PartETag> partETags = new LinkedList<>();
PartListing partListing = null;
ListPartsRequest listPartsRequest = new ListPartsRequest(bucketName, key, uploadId);
do {
  try {
      partListing = cosClient.listParts(listPartsRequest);
  } catch (CosServiceException e) {
      throw e;
  } catch (CosClientException e) {
      throw e;
  }
   for (PartSummary partSummary : partListing.getParts()) {
      partETags.add(new PartETag(partSummary.getPartNumber(), partSummary.getETag()));
  }
   listPartsRequest.setPartNumberMarker(partListing.getNextPartNumberMarker());
} while (partListing.isTruncated());

参数说明

参数名称	设置方法	描述	类型
bucketName	构造函数或 set 方法	Bucket 的命名格式为 BucketName-APPID，详情请参见 命名规范	String
key	构造函数或 set 方法	对象的名称	String
uploadId	构造函数或 set 方法	本次要查询的分块上传的 uploadId	String
maxParts	set 方法	单次返回最大的条目数量，默认1000	String
partNumberMarker	set 方法	默认以 UTF-8 二进制顺序列出条目，所有列出条目从 marker 开始	String
encodingType	set 方法	规定返回值的编码方式	String

返回结果说明

• 成功：返回 PartListing，包含每一分块的 ETag 和编号，以及下一次 list 的起点 marker。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

完成分块上传

完成整个文件的分块上传（Complete Multipart Upload）。

说明：

完成分块上传之后，分块上传任务将删除，任务对应的 uploadId 不再有效。

方法原型

public CompleteMultipartUploadResult completeMultipartUpload(CompleteMultipartUploadRequest request) throws CosClientException, CosServiceException;

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// uploadId 是一次分块上传任务的唯一标识，通过初始化分块上传或者查询分块上传任务获得
String uploadId = "exampleuploadid";
// 保存已上传的分片信息，实际情况里，这里的内容是从上传分块接口中获取到的
List<PartETag> partETags = new LinkedList<>();
// 分片上传结束后，调用complete完成分片上传
CompleteMultipartUploadRequest completeMultipartUploadRequest =
      new CompleteMultipartUploadRequest(bucketName, key, uploadId, partETags);
try {
  CompleteMultipartUploadResult completeResult =
          cosClient.completeMultipartUpload(completeMultipartUploadRequest);
  System.out.println(completeResult.getRequestId());
} catch (CosServiceException e) {
  throw e;
} catch (CosClientException e) {
  throw e;
}
// 确保不再使用 cosClient 之后，关闭之
cosClient.shutdown();

参数说明

参数名称	设置方法	描述	类型
bucketName	构造函数或 set 方法	Bucket 的命名格式为 BucketName-APPID ，详情请参见 命名规范	String
key	构造函数或 set 方法	指定分块上传到 COS 上的路径，即 对象键。例如对象键为 folder/picture.jpg	String
uploadId	构造函数或 set 方法	标识指定分块上传的 uploadId	String
partETags	构造函数或 set 方法	标识分块块的编号和上传返回的 eTag	List<PartETag>

返回结果说明

• 成功：返回 CompleteMultipartUploadResult，包含完成对象的 eTag 信息。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

终止分块上传

终止一个分块上传操作并删除已上传的分块（Abort Multipart Upload）。

说明：

终止分块上传之后，分块上传任务和已经上传的分块都会被删除，对应的 uploadId 不再有效。

方法原型

public void abortMultipartUpload(AbortMultipartUploadRequest request)  throws CosClientException, CosServiceException;

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// uploadId 是一次分块上传任务的唯一标识，通过初始化分块上传或者查询分块上传任务获得
String uploadId = "exampleuploadid";
AbortMultipartUploadRequest abortMultipartUploadRequest = new AbortMultipartUploadRequest(bucketName, key, uploadId);
try {
  cosClient.abortMultipartUpload(abortMultipartUploadRequest);
} catch (CosServiceException e) {
  e.printStackTrace();
} catch (CosClientException e) {
  e.printStackTrace();
}
// 确保不再使用 cosClient 之后，关闭之
cosClient.shutdown();

参数说明

参数名称	设置方法	描述	类型
bucketName	构造函数或 set 方法	Bucket 的命名格式为 BucketName-APPID，详情请参见 命名规范	String
key	构造函数或 set 方法	分块上传到 COS 上的路径，即 对象键。例如对象键为 folder/picture.jpg	String
uploadId	构造函数或 set 方法	标识指定分块上传的 uploadId	String

返回结果说明

• 成功：无返回值。
• 失败：发生错误（例如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。 详情请参见 异常处理。