tencent cloud

文档反馈

上传对象

最后更新时间:2022-09-09 10:16:36

    简介

    本文档提供关于对象的上传操作相关的 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);
    //若需要设置对象的自定义 Headers 可参照下列代码,若不需要可省略下面这几行,对象自定义 Headers 的详细信息可参考https://www.tencentcloud.com/document/product/436/13361?from_cn_redirect=1
    ObjectMetadata objectMetadata = new ObjectMetadata();
    //若设置Content-Type、Cache-Control、Content-Disposition、Content-Encoding、Expires这五个字自定义 Headers,推荐采用objectMetadata.setHeader()
    objectMetadata.setHeader(key, value);
    //若要设置 “x-cos-meta-[自定义后缀]” 这样的自定义 Header,推荐采用
    Map<String, String> userMeta = new HashMap<String, String>();
    userMeta.put("x-cos-meta-[自定义后缀]", "value");
    objectMetadata.setUserMetadata(userMeta);
    putObjectRequest.withMetadata(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

    上传流类型

    上传的源是一个 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.tencentcloud.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://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
      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://www.tencentcloud.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://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
      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 值,例如:09cba091df696af91549de27b8e7d0f6,注意:虽然在请求响应头域 ETag 的值是有双引号的,但是这里解析后的字符串 eTag 值是没有双引号的 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 值,例如:09cba091df696af91549de27b8e7d0f6,注意:虽然在请求响应头域 ETag 的值是有双引号的,但是这里解析后的字符串 eTag 值是没有双引号的 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://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
    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://www.tencentcloud.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。 详情请参见 异常处理
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持