简介
本文档提供关于对象的上传操作相关的 API 概览以及 SDK 示例代码。
简单操作
API | 操作名 | 操作描述 |
简单上传对象 | 上传一个对象至存储桶 |
分块操作
API | 操作名 | 操作描述 |
查询分块上传 | 查询正在进行中的分块上传信息 | |
初始化分块上传 | 初始化分块上传操作 | |
上传分块 | 分块上传对象 | |
查询已上传块 | 查询特定分块上传操作中的已上传的块 | |
完成分块上传 | 完成整个文件的分块上传 | |
终止分块上传 | 终止一个分块上传操作并删除已上传的块 |
上传对象
封装了简单上传、分块上传接口,根据文件大小智能的选择上传方式,同时支持续传功能。
示例代码: 上传本地文件
// 存储桶所在地域简称,例如广州地区是 ap-guangzhouString region = "COS_REGION";// 创建 CosXmlServiceConfig 对象,根据需要修改默认的配置参数CosXmlServiceConfig serviceConfig = CosXmlServiceConfig(region: region,isDebuggable: true,isHttps: true,);// 创建 TransferConfig 对象,根据需要修改默认的配置参数// TransferConfig 可以设置智能分块阈值 默认对大于或等于2M的文件自动进行分块上传,可以通过如下代码修改分块阈值TransferConfig transferConfig = TransferConfig(forceSimpleUpload: false,enableVerification: true,divisionForUpload: 2097152, // 设置大于等于 2M 的文件进行分块上传sliceSizeForUpload: 1048576, //设置默认分块大小为 1M);// 注册默认 COS TransferMangerawait Cos().registerDefaultTransferManger(serviceConfig, transferConfig);// 获取 TransferManagerCosTransferManger transferManager = Cos().getDefaultTransferManger();//CosTransferManger transferManager = Cos().getTransferManger("newRegion");// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketString bucket = "examplebucket-1250000000";String cosPath = "exampleobject"; //对象在存储桶中的位置标识符,即称对象键String srcPath = "本地文件的绝对路径"; //本地文件的绝对路径//若存在初始化分块上传的 UploadId,则赋值对应的 uploadId 值用于续传;否则,赋值 nullString? _uploadId;// 上传成功回调successCallBack(Map<String?, String?>? header, CosXmlResult? result) {// todo 上传成功后的逻辑}//上传失败回调failCallBack(clientException, serviceException) {// todo 上传失败后的逻辑if (clientException != null) {print(clientException);}if (serviceException != null) {print(serviceException);}}//上传状态回调, 可以查看任务过程stateCallback(state) {// todo notify transfer state}//上传进度回调progressCallBack(complete, target) {// todo Do something to update progress...}//初始化分块完成回调initMultipleUploadCallback(String bucket, String cosKey, String uploadId) {//用于下次续传上传的 uploadId_uploadId = uploadId;}//开始上传TransferTask transferTask = await transferManager.upload(bucket, cosPath,filePath: srcPath,uploadId: _uploadId,resultListener: ResultListener(successCallBack, failCallBack),stateCallback: stateCallback,progressCallBack: progressCallBack,initMultipleUploadCallback: initMultipleUploadCallback);//暂停任务//transferTask.pause();//恢复任务//transferTask.resume();//取消任务//transferTask.cancel();
参数说明
TransferConfig 用于配置 COS 上传服务,其主要成员说明如下:
参数名称 | 描述 | 类型 | 默认值 | 支持平台 |
divisionForUpload | 设置启用分块上传的最小对象大小 | Int | 2097152 | Android和iOS |
sliceSizeForUpload | 设置分块上传时的分块大小 | Int | 1048576 | Android和iOS |
enableVerification | 分片上传时是否整体校验 | Bool | true | Android和iOS |
forceSimpleUpload | 是否强制使用简单上传 | Bool | false | Android |
upload 方法参数
参数名称 | 描述 | 类型 | 是否必选 |
bucket | 桶名称,Bucket 的命名规则为 BucketName-APPID,详情请参见 存储桶概述 | String | 是 |
cosPath | 对象键 是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.c om/doc/picture.jpg 中,对象键为 doc/picture.jpg | String | 是 |
filePath | 需要上传的本地文件路径(和 byteArr 必选一个) | String | 否 |
byteArr | 需要上传的字节数组(和 filePath 必选一个) | Uint8List | 否 |
uploadId | 若存在初始化分块上传的 UploadId,则赋值对应的 uploadId 值用于续传 | String | 否 |
stroageClass | 存储类型 | String | 否 |
trafficLimit | 单链接限速(限速值设置范围为 819200 - 838860800,单位为 bit/s,即800Kb/s - 800Mb/s) | Int | 否 |
ResultListener | 上传结果回调(包括成功回调和失败回调) | ResultListener | 否 |
StateCallBack | 上传状态回调 | StateCallBack | 否 |
ProgressCallBack | 上传进度回调 | ProgressCallBack | 否 |
InitMultipleUploadCallback | 初始化分块完成回调 | InitMultipleUploadCallback | 否 |
返回结果说明
成功:返回 TransferTask,可以对 TransferTask 进行暂停、恢复、取消操作。
失败:发生错误(如身份认证失败),会在 ResultListener 的失败回调中抛出异常 CosXmlClientException 或者 CosXmlServiceException。详情请参见 异常处理。