简介
本文档提供关于对象的高级上传、简单上传、分块上传等操作相关的 API 概览以及 SDK 示例代码。
说明
简单操作
API | 操作名 | 操作描述 |
简单上传对象 | 上传一个对象至存储桶 | |
追加上传对象 | 将对象以分块追加的方式上传至存储桶 | |
表单上传对象 | 使用表单请求上传对象 |
分块操作
API | 操作名 | 操作描述 |
查询分块上传 | 查询正在进行中的分块上传信息 | |
初始化分块上传 | 初始化分块上传任务 | |
上传分块 | 分块上传对象 | |
查询已上传块 | 查询特定分块上传操作中已上传的块 | |
完成分块上传 | 完成整个对象的分块上传 | |
终止分块上传 | 终止一个分块上传操作并删除已上传的块 |
高级接口(推荐)
该类方法是对上面原生方法的封装,实现了分块上传的全过程,支持并发分块上传,支持断点续传,支持上传任务的取消,暂停和重新开始等。
高级上传
功能说明
Upload File 实现高级上传,传入参数 SliceSize 可以控制文件大小超出一个数值(默认1MB)时自动使用分块上传,否则使用简单上传。
使用示例
var uploadFile = function(file) {cos.uploadFile({Bucket: 'examplebucket-1250000000', /* 必须 */Region: 'COS_REGION', /* 存储桶所在地域,必须字段 */Key: file.name, /* 必须 */FilePath: file.path, /* 必须 */FileSize: file.size, /* v1.4.3之前的版本必须,v1.4.3及以后的版本非必须 */SliceSize: 1024 * 1024 * 5, /* 触发分块上传的阈值,超过5MB使用分块上传,非必须,按需调整,最小支持1MB */onTaskReady: function(taskId) { /* 非必须 */console.log(taskId);},onProgress: function (progressData) { /* 非必须 */console.log(JSON.stringify(progressData));},onFileFinish: function (err, data, options) { /* 非必须 */console.log(options.Key + '上传' + (err ? '失败' : '完成'));},// 支持自定义headers 非必须Headers: {'x-cos-meta-test': 123},}, function(err, data) {console.log(err || data);});}wx.chooseMessageFile({count: 10,type: 'all',success: function(res) {uploadFile(res.tempFiles[0]);}});
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
Bucket | 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 | String | 是 |
Region | 存储桶所在地域,枚举值请参见 地域和访问域名 | String | 是 |
Key | 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 | String | 是 |
FilePath | 上传文件路径 | String | 是 |
FileSize | 上传文件大小(v1.4.3之前的版本必须,v1.4.3及以后的版本非必须) | Number | 是 |
SliceSize | 表示文件大小超出一个数值时使用分块上传,单位 Byte,默认值1048576(1MB),小于等于该数值会使用 putObject 上传,大于该数值会使用 sliceUploadFile 上传 | Number | 否 |
AsyncLimit | 分块的并发量,仅在触发分块上传时有效 | Number | 否 |
StorageClass | 对象的存储类型,枚举值:STANDARD、STANDARD_IA、ARCHIVE、DEEP_ARCHIVE 等,更多存储类型请参见 存储类型概述 | String | 否 |
UploadAddMetaMd5 | 当上传时,给对象的元数据信息增加 x-cos-meta-md5 赋值为对象内容的 MD5 值,格式为 32 位小写字符串。例如:4d00d79b6733c9cc066584a02ed03410 | String | 否 |
CacheControl | RFC 2616中定义的缓存策略,将作为对象的元数据保存 | String | 否 |
ContentDisposition | RFC 2616中定义的文件名称,将作为对象的元数据保存 | String | 否 |
ContentEncoding | RFC 2616中定义的编码格式,将作为对象的元数据保存 | String | 否 |
ContentLength | RFC 2616中定义的 HTTP 请求内容长度(字节) | String | 否 |
ContentType | RFC 2616中定义的内容类型(MIME),将作为对象的元数据保存 | String | 否 |
Expires | RFC 2616中定义的过期时间,将作为对象的元数据保存 | String | 否 |
Expect | 当使用 Expect: 100-continue 时,在收到服务端确认后,才会发送请求内容 | String | 否 |
onTaskReady | 上传任务创建时的回调函数,返回一个 taskId,唯一标识上传任务,可用于上传任务的取消(cancelTask),停止(pauseTask)和重新开始(restartTask) | Function | 否 |
- taskId | 上传任务的编号 | String | 否 |
onProgress | 上传文件的进度回调函数,回调参数为进度对象 progressData | Function | 否 |
- progressData.loaded | 已经上传的文件部分大小,以字节(Bytes)为单位 | Number | 否 |
- progressData.total | 整个文件的大小,以字节(Bytes)为单位 | Number | 否 |
- progressData.speed | 文件的上传速度,以字节/秒(Bytes/s)为单位 | Number | 否 |
- progressData.percent | 文件的上传百分比,以小数形式呈现,例如,上传50%即为0.5 | Number | 否 |
onFileFinish | 每个文件完成或错误回调 | Function | 否 |
- err | 上传的错误信息 | Object | 否 |
- data | 文件完成的信息 | Object | 否 |
- options | 当前完成文件的参数信息 | Object | 否 |
回调函数说明
function(err, data) { ... }
参数名 | 参数描述 | 类型 |
err | 请求发生错误时返回的对象,包括网络错误和业务错误。如果请求成功则为空,更多详情请参见 错误码 | Object |
- statusCode | 请求返回的 HTTP 状态码,例如200、403、404等 | Number |
- headers | 请求返回的头部信息 | Object |
data | 请求成功时返回的对象,如果请求发生错误,则为空 | Object |
- statusCode | 请求返回的 HTTP 状态码,例如200、403、404等 | Number |
- headers | 请求返回的头部信息 | Object |
- Location | 上传完的文件访问地址 | String |
- Bucket | 分块上传的目标存储桶,仅在触发分块上传时返回 | String |
- Key | String | |
- ETag | 合并后文件的唯一 ID,格式:"uuid-<分块数>" 例如 "22ca88419e2ed4721c23807c678adbe4c08a7880-3" ,注意前后携带双引号 | String |
- VersionId | 在开启过版本控制的存储桶中上传对象返回对象的版本 ID,存储桶从未开启则不返回该参数 | String |
分块上传对象(断点续传)
功能说明
Slice Upload File 可用于实现文件的分块上传,适用于大文件上传。
使用示例
var sliceUploadFile = function (file) {var key = file.name;cos.sliceUploadFile({Bucket: 'examplebucket-1250000000', /* 必须 */Region: 'COS_REGION', /* 必须 */Key: 'exampleobject', /* 必须 */FilePath: file.path, /* 必须 */FileSize: file.size, /* 非必须 */CacheControl: 'max-age=7200', /* 非必须 */// 支持自定义headers 非必须Headers: {'x-cos-meta-test': 123},Query: { /* 非必须 */bb: 123,},onTaskReady: function(taskId) { /* 非必须 */console.log(taskId);},onHashProgress: function(info) { /* 非必须 */console.log('check hash', JSON.stringify(info));},onProgress: function(info) { /* 非必须 */console.log(JSON.stringify(info));}}, requestCallback);};wx.chooseMessageFile({count: 10,type: 'all',success: function(res) {sliceUploadFile(res.tempFiles[0]);}});
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
Bucket | 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 | String | 是 |
Region | 存储桶所在地域,枚举值请参见 地域和访问域名 | String | 是 |
Key | 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 | String | 是 |
FilePath | 上传文件路径 | String | 是 |
SliceSize | 分块大小 | Number | 否 |
AsyncLimit | 分块的并发量,仅在触发分块上传时有效 | Number | 否 |
StorageClass | String | 否 | |
CacheControl | RFC 2616中定义的缓存策略,将作为对象的元数据保存 | String | 否 |
ContentDisposition | RFC 2616中定义的文件名称,将作为对象的元数据保存 | String | 否 |
ContentEncoding | RFC 2616中定义的编码格式,将作为对象的元数据保存 | String | 否 |
ContentLength | RFC 2616中定义的 HTTP 请求内容长度(字节) | String | 否 |
ContentType | RFC 2616中定义的内容类型(MIME),将作为对象的元数据保存 | String | 否 |
Expires | RFC 2616中定义的过期时间,将作为对象的元数据保存 | String | 否 |
Expect | 当使用 Expect: 100-continue 时,在收到服务端确认后,才会发送请求内容 | String | 否 |
onTaskReady | 上传任务创建时的回调函数,返回一个 taskId,唯一标识上传任务,可用于上传任务的取消(cancelTask),停止(pauseTask)和重新开始(restartTask) | Function | 否 |
- taskId | 上传任务的编号 | String | 否 |
onHashProgress | 计算文件 MD5 值的进度回调函数,回调参数为进度对象 progressData | Function | 否 |
- progressData.loaded | 已经校验的文件部分大小,以字节(Bytes)为单位 | Number | 否 |
- progressData.total | 整个文件的大小,以字节(Bytes)为单位 | Number | 否 |
- progressData.speed | 文件的校验速度,以字节/秒(Bytes/s)为单位 | Number | 否 |
- progressData.percent | 文件的校验百分比,以小数形式呈现,例如:校验50%即为0.5 | Number | 否 |
onProgress | 上传文件的进度回调函数,回调参数为进度对象 progressData | Function | 否 |
- progressData.loaded | 已经上传的文件部分大小,以字节(Bytes)为单位 | Number | 否 |
- progressData.total | 整个文件的大小,以字节(Bytes)为单位 | Number | 否 |
- progressData.speed | 文件的上传速度,以字节/秒(Bytes/s)为单位 | Number | 否 |
- progressData.percent | 文件的上传百分比,以小数形式呈现,例如:上传50%即为0.5 | Number | 否 |
回调函数说明
function(err, data) { ... }
参数名 | 参数描述 | 类型 |
err | Object | |
- statusCode | 请求返回的 HTTP 状态码,例如200、403、404等 | Number |
- headers | 请求返回的头部信息 | Object |
data | 请求成功时返回的对象,如果请求发生错误,则为空 | Object |
- statusCode | 请求返回的 HTTP 状态码,例如200、403、404等 | Number |
- headers | 请求返回的头部信息 | Object |
- Location | 创建对象的外网访问域名 | String |
- Bucket | 分块上传的目标存储桶 | String |
- Key | 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 | String |
- ETag | 合并后文件的唯一 ID,格式: "uuid-<分块数>" 例如 "22ca88419e2ed4721c23807c678adbe4c08a7880-3" ,注意前后携带双引号 | String |
- VersionId | 在开启过版本控制的存储桶中上传对象返回对象的版本 ID,存储桶从未开启则不返回该参数 | String |
批量上传
功能说明
方法一:
批量上传可以直接多次调用 putObject 和 sliceUploadFile,达到批量上传效果。通过实例化参数 FileParallelLimit 控制文件并发数,默认3个并发。
方法二:
可以调用 cos.uploadFiles 实现批量上传,传入参数 SliceSize 可以控制文件大小超出一个数值时使用分块上传。以下是 uploadFiles 方法说明。
方法原型
调用 uploadFiles 操作:
var uploadFiles = function(files) {var fileList = files.map(function(file) {return Object.assign(file, {FilePath: file.path, /* 必须 */FileSize: file.size, /* v1.4.3之前的版本必须,v1.4.3及以后的版本非必须 */Bucket: 'examplebucket-1250000000', /* 必须 */Region: 'COS_REGION',/* 存储桶所在地域,必须字段 */Key: file.name, /* 必须 */onTaskReady: function(taskId) {/* taskId可通过队列操作来取消上传cos.cancelTask(taskId)、停止上传cos.pauseTask(taskId)、重新开始上传cos.restartTask(taskId) */console.log(taskId);},// 支持自定义headers 非必须Headers: {'x-cos-meta-test': 123},});});cos.uploadFiles({files: fileList,SliceSize: 1024 * 1024 * 10, /* 设置大于10MB采用分块上传,按需调整,最小支持1MB */onProgress: function (info) {var percent = parseInt(info.percent * 10000) / 100;var speed = parseInt(info.speed / 1024 / 1024 * 100) / 100;console.log('进度:' + percent + '%; 速度:' + speed + 'Mb/s;');},onFileFinish: function (err, data, options) {console.log(options.Key + '上传' + (err ? '失败' : '完成'));},}, function (err, data) {console.log(err || data);});}wx.chooseMessageFile({count: 10,type: 'all',success: function(res) {uploadFiles(res.tempFiles);}});
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
files | 文件列表,每一项是传给 putObject 和 sliceUploadFile 的参数对象 | Object | 是 |
- Bucket | 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 | String | 是 |
- Region | 存储桶所在地域,枚举值请参见 地域和访问域名 | String | 是 |
- Key | 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 | String | 是 |
- FilePath | 上传文件路径 | String | 是 |
- FileSize | 上传文件大小(v1.4.3之前的版本必须,v1.4.3及以后的版本非必须) | Number | 是 |
- CacheControl | RFC 2616中定义的缓存策略,将作为对象的元数据保存 | String | 否 |
- ContentDisposition | RFC 2616中定义的文件名称,将作为对象的元数据保存 | String | 否 |
- ContentEncoding | RFC 2616中定义的编码格式,将作为对象的元数据保存 | String | 否 |
- ContentLength | RFC 2616中定义的 HTTP 请求内容长度(字节) | String | 否 |
- ContentType | RFC 2616中定义的内容类型(MIME),将作为对象的元数据保存 | String | 否 |
- Expires | RFC 2616中定义的过期时间,将作为对象的元数据保存 | String | 否 |
- Expect | 当使用 Expect: 100-continue 时,在收到服务端确认后,才会发送请求内容 | String | 否 |
- onTaskReady | 上传任务创建时的回调函数,返回一个 taskId,唯一标识上传任务,可用于上传任务的取消(cancelTask),停止(pauseTask)和重新开始(restartTask) | Function | 否 |
-- taskId | 上传任务的编号 | String | 否 |
SliceSize | 表示文件大小超出一个数值时使用分块上传,单位 Byte,默认值1048576(1MB),小于等于该数值会使用 putObject 上传,大于该数值会使用 sliceUploadFile 上传 | Number | 是 |
onProgress | 所有任务 进度汇总计算出来的上传进度 | String | 是 |
- progressData.loaded | 已经上传的文件部分大小,以字节(Bytes)为单位 | Number | 否 |
- progressData.total | 整个文件的大小,以字节(Bytes)为单位 | Number | 否 |
- progressData.speed | 文件的上传速度,以字节/秒(Bytes/s)为单位 | Number | 否 |
- progressData.percent | 文件的上传百分比,以小数形式呈现,例如:上传50%即为0.5 | Number | 否 |
onFileFinish | 每个文件完成或错误回调 | Function | 否 |
- err | 上传的错误信息 | Object | 否 |
- data | 文件完成的信息 | Object | 否 |
- options | 当前完成文件的参数信息 | Object | 否 |
回调函数说明
function(err, data) { ... }
参数名 | 参数描述 | 类型 |
err | 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 | Object |
- statusCode | 请求返回的 HTTP 状态码,例如200、403、404等 | Number |
- headers | 请求返回的头部信息 | Object |
data | 请求成功时返回的对象,如果请求发生错误,则为空 | Object |
- files | 每个文件的 error 或 data | ObjectArray |
- - error | 上传的错误信息 | Object |
- - data | 文件完成的信息 | Object |
- - options | 当前完成文件的参数信息 | Object |
上传队列
小程序 SDK 针对 putObject 发起的上传任务都有记录在队列中,队列相关方法如下。
1. var taskList = cos.getTaskList() 可以获取任务列表。
2. cos.pauseTask()、cos.restartTask()、cos.cancelTask() 操作任务。
3. cos.on('list-update', callback); 可以监听列表和进度变化。
取消上传任务
根据 taskId 取消上传任务。
使用示例
var taskId = 'xxxxx'; /* 必须 */cos.cancelTask(taskId);
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
taskId | 文件上传任务的编号,在调用 putObject 方法时,其 TaskReady 回调会返回该上传任务的 taskId | String | 是 |
暂停上传任务
根据 taskId 暂停上传任务。
使用示例
var taskId = 'xxxxx'; /* 必须 */cos.pauseTask(taskId);
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
taskId | 文件上传任务的编号,在调用 putObject 方法时,其 TaskReady 回调会返回该上传任务的 taskId | String | 是 |
重启上传任务
根据 taskId 重新开始上传任务,可以用于开启用户手动停止的(调用 pauseTask 停止)或者因为上传错误而停止的上传任务。
使用示例
var taskId = 'xxxxx'; /* 必须 */cos.restartTask(taskId);
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
taskId | 文件上传任务的编号,在调用 putObject 方法时,其 TaskReady 回调将返回该上传任务的 taskId | String | 是 |
简单操作
简单上传对象
功能说明
PUT Object 接口可以上传一个对象至指定存储桶中。该操作需要请求者对存储桶有 WRITE 权限。
注意
1. Key(文件名)不能以
/
结尾,否则会被识别为文件夹。2. Key(文件名)同名上传默认为覆盖操作。若您未开启版本控制且不想覆盖云上文件时,请确保上传时的 Key 不重复。
3. 每个主账号(即同一个 APPID),存储桶的 ACL 规则数量最多为1000条,对象 ACL 规则数量不限制。如果您不需要进行对象 ACL 控制,请在上传时不要设置,默认继承存储桶权限。
4. 上传之后,您可以用同样的 Key 生成预签名链接(下载请指定 method 为 GET,具体接口说明见下文,分享到其他端来进行下载。但注意如果您的文件是私有读权限,那么预签名链接只有一定的有效期)。
使用示例
选择文件并上传(使用 Body 参数):
// 此处以选择图片api(wx.chooseImage)为参考,其他api请参考小程序官方文档wx.chooseImage({count: 1,success: function(res) {var file = res.tempFiles[0];// 微信小程序里获取文件管理器var wxfs = wx.getFileSystemManager();wxfs.readFile({filePath: file.path,success: function (res) {cos.putObject({Bucket: config.Bucket,Region: config.Region,Key: file.name,Body: res.data, // Body里传入的是文件内容}, function(err, data) {console.log(err || data);});},fail: function(err) {console.error(err)},});},fail: function(err) {console.error(err)},});
选择文件并上传(使用 FilePath 参数需要 sdk 版本至少达到v1.3.0):
// 此处以选择图片api(wx.chooseImage)为参考,其他api请参考小程序官方文档wx.chooseImage({count: 1,success: function(res) {var file = res.tempFiles[0];cos.putObject({Bucket: config.Bucket,