腾讯云对象存储上传对象

简介

本文档提供关于对象的高级上传、简单上传、分块上传等操作相关的 API 概览以及 SDK 示例代码。简单操作

分块操作

SDK API 参考

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

高级接口（推荐）

上传对象

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

示例代码一: 上传本地文件

// 初始化 TransferConfig，这里使用默认配置，如果需要定制，请参考 SDK 接口文档TransferConfig transferConfig = new TransferConfig.Builder().build();// 初始化 TransferManagerTransferManager transferManager = new TransferManager(cosXmlService,        transferConfig);
// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketString bucket = "examplebucket-1250000000";String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即称对象键String srcPath = new File(context.getCacheDir(), "exampleobject")        .toString(); //本地文件的绝对路径//若存在初始化分块上传的 UploadId，则赋值对应的 uploadId 值用于续传；否则，赋值 nullString uploadId = null;
// 上传文件COSXMLUploadTask cosxmlUploadTask = transferManager.upload(bucket, cosPath,        srcPath, 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    }});

说明更多完整示例，请前往 GitHub 查看。上传之后，您可以用同样的 Key 生成文件下载链接，具体使用方法见 生成预签名 URL 文档。但注意如果您的文件是私有读权限，那么下载链接只有一定的有效期。

示例代码二: 上传二进制数据

TransferConfig transferConfig = new TransferConfig.Builder().build();TransferManager transferManager = new TransferManager(cosXmlService,        transferConfig);
// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketString bucket = "examplebucket-1250000000";String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即称对象键
// 上传字节数组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();        }    }});

说明上传二进制数据仅支持普通上传，不支持分块上传。更多完整示例，请前往 GitHub 查看。上传之后，您可以用同样的 Key 生成文件下载链接，具体使用方法见 生成预签名 URL 文档。但注意如果您的文件是私有读权限，那么下载链接只有一定的有效期。

示例代码三: 流式上传

TransferConfig transferConfig = new TransferConfig.Builder().build();TransferManager transferManager = new TransferManager(cosXmlService,        transferConfig);
// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketString bucket = "examplebucket-1250000000";String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即称对象键
// 流式上传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();        }    }});

说明流式上传仅支持普通上传，不支持分块上传。更多完整示例，请前往 GitHub 查看。上传之后，您可以用同样的 Key 生成文件下载链接，具体使用方法见 生成预签名 URL 文档。但注意如果您的文件是私有读权限，那么下载链接只有一定的有效期。

示例代码四: 通过 URI 上传

TransferConfig transferConfig = new TransferConfig.Builder().build();TransferManager transferManager = new TransferManager(cosXmlService,        transferConfig);
// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketString bucket = "examplebucket-1250000000";String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即称对象键
// 文件的 UriUri uri = Uri.parse("exampleObject");// 若存在初始化分块上传的 UploadId，则赋值对应的 uploadId 值用于续传；否则，赋值 nullString 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();        }    }});

说明更多完整示例，请前往 GitHub 查看。上传之后，您可以用同样的 Key 生成文件下载链接，具体使用方法见 生成预签名 URL 文档。但注意如果您的文件是私有读权限，那么下载链接只有一定的有效期。

示例代码五: 设置智能分块阈值

// 默认对大于或等于2M的文件自动进行分块上传，可以通过如下代码修改分块阈值TransferConfig transferConfig = new TransferConfig.Builder()        .setDivisionForUpload(2 * 1024 * 1024) // 设置大于等于 2M 的文件进行分块上传        .build();
TransferManager transferManager = new TransferManager(cosXmlService,        transferConfig);

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

示例代码六: 上传暂停、继续与取消

对于上传任务，可以通过以下方式暂停：

// 如果上传过程中，已经发起了最后的 Complete Multipart Upload 请求，那么暂停会失败boolean pauseSuccess = cosxmlUploadTask.pauseSafely();

暂停之后，可以通过以下方式续传：

// 如果暂停成功，可以恢复上传if (pauseSuccess) {    cosxmlUploadTask.resume();}

也通过以下方式取消上传：

cosxmlUploadTask.cancel();

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

示例代码七: 批量上传

//本地文件的绝对路径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();            }        }    });}

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

示例代码八：创建目录

// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketString 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();        }    }});

说明更多完整示例，请前往 GitHub 查看。上传之后，您可以用同样的 Key 生成文件下载链接，具体使用方法见 生成预签名 URL 文档。但注意如果您的文件是私有读权限，那么下载链接只有一定的有效期。

示例代码九：设置低优先级任务

// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketString 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) {}});

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

简单操作

简单上传对象

功能说明

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

示例代码

// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketString bucket = "examplebucket-1250000000";String cosPath = "exampleobject"; //对象位于存储桶中的位置标识符，即对象键。String srcPath = new File(context.getCacheDir(), "exampleobject")        .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();        }    }});

说明更多完整示例，请前往 GitHub 查看。上传之后，您可以用同样的 Key 生成文件下载链接，具体使用方法见 生成预签名 URL 文档。但注意如果您的文件是私有读权限，那么下载链接只有一定的有效期。

追加上传对象

功能说明

将对象以分块追加的方式上传至存储桶（APPEND Object）。注意对象属性为 appendable 时才能使用本接口追加上传。对象首次使用 APPEND Object 接口上传时，该对象的属性自动为 appendable。可以使用 GET Object 或 HEAD Object 接口获取 x-cos-object-type 响应头来判断对象属性。

示例代码

// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketString bucket = "examplebucket-1250000000";String cosPath = "exampleobject"; //对象位于存储桶中的位置标识符，即对象键。String srcPath = new File(context.getCacheDir(), "exampleobject")        .toString();//"本地文件的绝对路径";AppendObjectRequest request = new AppendObjectRequest(bucket,                    cosPath, srcPath, 0);// 设置追加操作的起始点，单位：字节// 首次追加 position=0，后续追加 position= 当前 Object 的 content-lengthrequest.setPosition(1024);
request.setProgressListener(new CosXmlProgressListener() {    @Override    public void onProgress(long progress, long max) {        // todo Do something to update progress...    }});cosXmlService.appendObjectAsync(request, new CosXmlResultListener() {    @Override    public void onSuccess(CosXmlRequest cosXmlRequest, CosXmlResult result) {        AppendObjectResult appendObjectResult = (AppendObjectResult) result;        // 下一次追加操作的起始点，单位：字节        String nextAppendPosition = appendObjectResult.nextAppendPosition;    }
    // 如果您使用 kotlin 语言来调用，请注意回调方法中的异常是可空的，否则不会回调 onFail 方法，即：    // clientException 的类型为 CosXmlClientException?，serviceException 的类型为 CosXmlServiceException?    @Override    public void onFail(CosXmlRequest cosXmlRequest,                       @Nullable CosXmlClientException clientException,                       @Nullable CosXmlServiceException serviceException) {        if (clientException != null) {            clientException.printStackTrace();        } else {            serviceException.printStackTrace();        }    }});

说明以上代码示例为通过文件追加上传，SDK还支持通过字节数组和流进行追加上传，更多完整示例，请前往 GitHub 查看。

表单上传对象

功能说明

使用表单请求上传对象。

示例代码

String bucket = "examplebucket-1250000000"; //存储桶名称，格式：BucketName-APPIDString cosPath = "exampleobject"; //对象位于存储桶中的位置标识符，即对象键。String srcPath = new File(context.getCacheDir(), "exampleobject")        .toString();//"本地文件的绝对路径";
PostObjectRequest postObjectRequest = new PostObjectRequest(bucket, cosPath,        srcPath);
postObjectRequest.setProgressListener(new CosXmlProgressListener() {    @Override    public void onProgress(long progress, long max) {        // todo Do something to update progress...    }});cosXmlService.postObjectAsync(postObjectRequest, 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();        }    }});

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

分块操作

关于分块上传的更多说明请参见 分块上传。分块上传对象的操作流程如下。

分块上传的流程

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）。

查询分块上传

功能说明

查询指定存储桶中正在进行的分块上传（List Multipart Uploads）。

示例代码

// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketString 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();        }    }});

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

初始化分块上传

功能说明

初始化 Multipart Upload 上传操作，获取对应的 uploadId（Initiate Multipart Upload）。

示例代码

// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketString bucket = "examplebucket-1250000000";String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即对象键。
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();        }    }});

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

上传分块

分块上传对象（Upload Part）。

示例代码

// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketString bucket = "examplebucket-1250000000";String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即对象键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();        }    }});