有奖捉虫:办公协同&微信生态&物联网文档专题 HOT

简介

本文档提供关于对象的高级上传、简单上传、分块上传等操作相关的 API 概览以及 SDK 示例代码。
说明
常见上传错误排查,请参考 常见问题
简单操作
API
操作名
操作描述
简单上传对象
上传一个对象至存储桶
表单上传对象
使用表单请求上传对象
分块操作
API
操作名
操作描述
查询分块上传
查询正在进行中的分块上传信息
初始化分块上传
初始化分块上传任务
上传分块
分块上传对象
查询已上传块
查询特定分块上传操作中已上传的块
完成分块上传
完成整个对象的分块上传
终止分块上传
终止一个分块上传操作并删除已上传的块

高级接口(推荐)

强烈建议您使用高级接口,该类方法是对上面原生方法的封装,实现了分块上传的全过程,支持并发分块上传,支持断点续传,支持上传任务的取消,暂停和重新开始等。

高级上传

功能说明

Upload File 实现高级上传,传入参数 SliceSize 可以控制文件大小超出一个数值(默认1MB)时自动使用分块上传(sliceUploadFile),否则使用简单上传(putObject)。

使用示例

cos.uploadFile({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Body: fileObject, /* 必须,上传文件对象,可以是input[type="file"]标签选择本地文件后得到的file对象 */
SliceSize: 1024 * 1024 * 5, /* 触发分块上传的阈值,超过5MB使用分块上传,非必须 */
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);
});

参数说明

参数名
参数描述
类型
是否必填
Bucket
存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String
Region
存储桶所在地域,枚举值请参见 地域和访问域名
String
Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
Body
上传文件的内容,可以为 File 对象 或者 Blob 对象
File\\Blob
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
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述,仅在触发分块上传时返回
String
- ETag
合并后文件的唯一 ID,格式:"uuid-<分块数>"
例如"22ca88419e2ed4721c23807c678adbe4c08a7880-3"注意前后携带双引号
String
- VersionId
在开启过版本控制的存储桶中上传对象返回对象的版本 ID,存储桶从未开启则不返回该参数。需要 Expose-Headers 里设置 VersionId 字段,详情请参见 文档
String

分块上传对象(断点续传)

功能说明

Slice Upload File 可用于实现文件的分块上传,适用于大文件上传。
说明
浏览器未关闭的情况下,可以对上传任务进行暂停、重新开始或取消操作。
浏览器刷新后,如果将同一个文件上传到同一个存储桶路径下,则会根据 UploadId 校验内容,校验通过后,续传文件。

使用示例

cos.sliceUploadFile({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Body: fileObject, /* 必须,上传文件对象,可以是input[type="file"]标签选择本地文件后得到的file对象 */
onTaskReady: function(taskId) { /* 非必须 */
console.log(taskId);
},
onHashProgress: function (progressData) { /* 非必须 */
console.log(JSON.stringify(progressData));
},
onProgress: function (progressData) { /* 非必须 */
console.log(JSON.stringify(progressData));
},
// 支持自定义headers 非必须
Headers: {
'x-cos-meta-test': 123
},
}, function(err, data) {
console.log(err || data);
});

参数说明

参数名
参数描述
类型
是否必填
Bucket
存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String
Region
存储桶所在地域,枚举值请参见 地域和访问域名
String
Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
Body
上传文件的内容,可以为 File 对象 或者 Blob 对象
File\\Blob
SliceSize
分块大小
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
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,存储桶从未开启则不返回该参数。需要 Expose-Headers 里设置 VersionId 字段,详情请参见 文档
String

批量上传

功能说明

方法一: 批量上传可以直接多次调用 putObject 和 sliceUploadFile,达到批量上传效果。通过实例化参数 FileParallelLimit 控制文件并发数,默认3个并发。
方法二: 可以调用 cos.uploadFiles 实现批量上传,方法参数 SliceSize 可以控制文件。以下是 uploadFiles 方法说明。

方法原型

调用 uploadFiles 操作:
cos.uploadFiles({
files: [{
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Body: fileObject1, /* 必须,上传文件对象,可以是input[type="file"]标签选择本地文件后得到的file对象 */
onTaskReady: function(taskId) {
/* taskId可通过队列操作来取消上传cos.cancelTask(taskId)、停止上传cos.pauseTask(taskId)、重新开始上传cos.restartTask(taskId) */
console.log(taskId);
},
// 支持自定义headers 非必须
Headers: {
'x-cos-meta-test': 123
},
}, {
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '2.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Body: fileObject2, /* 必须,上传文件对象,可以是input[type="file"]标签选择本地文件后得到的file对象 */
onTaskReady: function(taskId) {
/* taskId可通过队列操作来取消上传cos.cancelTask(taskId)、停止上传cos.pauseTask(taskId)、重新开始上传cos.restartTask(taskId) */
console.log(taskId);
},
// 支持自定义headers 非必须
Headers: {
'x-cos-meta-test': 123
},
}],
SliceSize: 1024 * 1024 * 10, /* 设置大于10MB采用分块上传 */
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);
});

参数说明

参数名
参数描述
类型
是否必填
files
文件列表,每一项是传给 putObject 和 sliceUploadFile 的参数对象
Object
- Bucket
存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String
- Region
存储桶所在地域,枚举值请参见 地域和访问域名
String
- Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
- Body
上传文件的内容,可以为 File 对象 或者 Blob 对象
File\\Blob
- 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
AsyncLimit
分块的并发量,仅在触发分块上传时有效
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

上传队列

JavaScript SDK 针对 putObject 和 sliceUploadFile 发起的上传任务都有在记录队列里,队列相关方法如下。
1. const taskList = cos.getTaskList() 可以获取任务列表。
2. cos.pauseTask()、cos.restartTask()、cos.cancelTask() 操作任务。
3. cos.on('list-update', callback); 可以监听列表和进度变化。
完整的队列使用示例请参见 demo-queue
注意:队列仅限相同的cos实例才能访问和操作
const cos1 = new COS({ ... });
const cos2 = new COS({ ... });
let taskId;
// 【!!注意!!】由cos1发起的上传,无法使用cos2来访问和操作
cos1.uploadFile({
....,
onTaskReady(id) {
taskId = id;
},
});

// 1. 获取任务列表
const list = cos2.getTaskList(); // list为空[],cos2实例无法获取cos1的队列
// 2. 暂停任务
cos2.pauseTask(taskId); // 暂停无效,cos2实例无法操作cos1的队列

取消上传任务

根据 taskId 取消上传任务。无法通过 cos.restartTask(taskId) 重新上传,可以重新选择文件进行上传。
使用示例
// taskId通过上传时回调(onTaskReady)获取
cos.cancelTask(taskId);
参数说明
参数名
参数描述
类型
是否必填
taskId
文件上传任务的编号,在调用 uploadFile/putObjec/sliceUploadFile 方法时,其 onTaskReady 回调会返回该上传任务的 taskId
String

暂停上传任务

根据 taskId 暂停上传任务。暂停后可通过 cos.restartTask(taskId) 重新上传,分块上传任务将自动续传。
使用示例
// taskId通过上传时回调(onTaskReady)获取
cos.pauseTask(taskId);
参数说明
参数名
参数描述
类型
是否必填
taskId
文件上传任务的编号,在调用 uploadFile/putObject/sliceUploadFile 方法时,其 onTaskReady 回调会返回该上传任务的 taskId
String

重启上传任务

根据 taskId 重新开始上传任务,可以用于开启用户手动停止的(调用 pauseTask 停止)或者因为上传错误而停止的上传任务。
使用示例
// taskId通过上传时回调(onTaskReady)获取
cos.restartTask(taskId);
参数说明
参数名
参数描述
类型
是否必填
taskId
文件上传任务的编号,在调用 uploadFile/putObject/sliceUploadFile 方法时,其 onTaskReady 回调会返回该上传任务的 taskId
String

简单操作

简单上传对象

功能说明

PUT Object 接口可以上传一个对象至指定存储桶中。该操作需要请求者对存储桶有 WRITE 权限。
注意
Key(文件名)不能以/结尾,否则会被识别为文件夹。
Key(文件名)同名上传默认为覆盖操作。若您未开启版本控制且不想覆盖云上文件时,请确保上传时的Key不重复。
每个主账号(即同一个 APPID),存储桶的 ACL 规则数量最多为1000条,对象 ACL 规则数量不限制。如果您不需要进行对象 ACL 控制,请在上传时不要设置,默认继承存储桶权限。
上传之后,您可以用同样的 Key 生成预签名链接(下载请指定 method 为 GET,具体接口说明见下文,分享到其他端来进行下载)。但注意如果您的文件是私有读权限,那么预签名链接只有一定的有效期。
上传进度onProgress依赖于原生的xhr.upload.onprogress方法,如果您发现上传进度不准确,请检查您的项目内是否引用了拦截XHR方法的库,例如 nuysoft/Mock。

使用示例

简单上传文件,适用于小文件上传:
cos.putObject({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Body: fileObject, /* 必须,上传文件对象,可以是input[type="file"]标签选择本地文件后得到的file对象 */
onProgress: function(progressData) {
console.log(JSON.stringify(progressData));
}
}, function(err, data) {
console.log(err || data);
});
上传字符串作为文件内容:
cos.putObject({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.txt', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Body: 'hello!',
}, function(err, data) {
console.log(err || data);
});
上传base64作为文件内容:
var base64Url = 'data:image/png;base64,iVBORw0KGgo.....';
var dataURLtoBlob = function (dataurl) {
var arr = dataurl.split(',');
var mime = arr[0].match(/:(.*?);/)[1];
var bstr = atob(arr[1]);
var n = bstr.length;
var u8arr = new Uint8Array(n);
while (n--) {
u8arr[n] = bstr.charCodeAt(n);
}
return new Blob([u8arr], { type: mime });
};
// 需要转为Blob上传
var body = dataURLtoBlob(base64Url);
cos.putObject({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.png', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Body: body,
}, function(err, data) {
console.log(err || data);
});
创建目录a:
cos.putObject({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: 'a/', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Body: '',
}, function(err, data) {
console.log(err || data);
});
上传文件到指定目录a/b:
cos.putObject({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: 'a/b/1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Body: fileObject, /* 必须,上传文件对象,可以是input[type="file"]标签选择本地文件后得到的file对象 */
onProgress: function(progressData) {
console.log(JSON.stringify(progressData));
}
}, function(err, data) {
console.log(err || data);
});
自定义Headers:
cos.putObject({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'ap-beijing', /* 必须 */
Key: 'a', /* 必须 */
Body: 'hello', /* 必须 */
// 支持自定义headers 非必须
Headers: {
'x-cos-meta-test': 123
},
}, function(err, data) {
console.log(err || data);
});
上传对象(单链接限速):
说明
关于上传对象的限速说明,请参见 单链接限速
cos.putObject({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Body: fileObject, /* 必须,上传文件对象,可以是input[type="file"]标签选择本地文件后得到的file对象 */
Headers: {
'x-cos-traffic-limit': 819200, // 限速值设置范围为819200 - 838860800,单位默认为 bit/s,即800Kb/s - 800Mb/s,如果超出该范围将返回400错误。
},
onProgress: function(progressData) {
console.log(JSON.stringify(progressData));
}
}, function(err, data) {
console.log(err || data);
});

参数说明

参数名
参数描述
类型
是否必填
Bucket
存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String
Region
存储桶所在地域,枚举值请参见 地域和访问域名
String
Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
Body
上传文件的内容,可以为字符串,File 对象或者 Blob 对象
String\\File\\Blob\\ArrayBuffer
CacheControl
RFC 2616中定义的缓存策略,将作为对象的元数据保存
String
ContentDisposition
RFC 2616中定义的文件名称,将作为对象的元数据保存
String
ContentEncoding
RFC 2616中定义的编码格式,将作为对象的元数据保存
String
ContentLength
RFC 2616中定义的 HTTP 请求内容长度(字节)
String
ContentType
RFC 2616中定义的内容类型(MIME),将作为对象的元数据保存
String
Ex