简介
本文档提供关于对象的高级上传、简单上传、分块上传等操作相关的 API 概览以及 SDK 示例代码。
简单操作
API | 操作名 | 操作描述 |
简单上传对象 | 上传一个对象至存储桶 | |
追加上传对象 | 将对象以分块追加的方式上传至存储桶 | |
表单上传对象 | 使用表单请求上传对象 |
分块操作
API | 操作名 | 操作描述 |
查询分块上传 | 查询正在进行中的分块上传信息 | |
初始化分块上传 | 初始化分块上传任务 | |
上传分块 | 分块上传对象 | |
查询已上传块 | 查询特定分块上传操作中已上传的块 | |
完成分块上传 | 完成整个对象的分块上传 | |
终止分块上传 | 终止一个分块上传操作并删除已上传的块 |
高级接口(推荐)
该类方法是对上面原生方法的封装,实现了分块上传的全过程,支持并发分块上传,支持断点续传,支持上传任务的取消,暂停和重新开始等。
高级上传
功能说明
Upload File 实现高级上传,传入参数 SliceSize 可以控制文件大小超出一个数值(默认1MB)时自动使用分块上传,否则使用简单上传。
使用示例
const filePath = "temp-file-to-upload" // 本地文件路径cos.uploadFile({Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */Region: 'COS_REGION', /* 存储桶所在地域,例如 ap-beijing,必须字段 */Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */FilePath: filePath, /* 必须 */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 | 是 |
FilePath | 上传文件路径 | String | 是 |
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 可用于实现文件的分块上传,适用于大文件上传。
使用示例
const filePath = "temp-file-to-upload" // 本地文件路径cos.sliceUploadFile({Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */Region: 'COS_REGION', /* 存储桶所在地域,例如 ap-beijing,必须字段 */Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */FilePath: filePath, /* 必须 */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 | 是 |
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 操作:
const filePath1 = "temp-file-to-upload" // 本地文件路径const filePath2 = "temp-file-to-upload" // 本地文件路径cos.uploadFiles({files: [{Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */Region: 'COS_REGION', /* 存储桶所在地域,例如 ap-beijing,必须字段 */Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */FilePath: filePath1,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),必须字段 */FilePath: filePath2,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 | 是 |
- FilePath | 上传文件路径 | 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 | 否 |
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 |
上传队列
Node.js SDK 针对 putObject 和 sliceUploadFile 发起的上传任务都有记录队列里,队列相关方法如下。
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 | 文件上传任务的编号,在调用 sliceUploadFile 方法时,其 TaskReady 回调会返回该上传任务的 taskId | String | 是 |
暂停上传任务
根据 taskId 暂停上传任务。
使用示例
var taskId = 'xxxxx'; /* 必须 */cos.pauseTask(taskId);
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
taskId | 文件上传任务的编号,在调用 sliceUploadFile 方法时,其 TaskReady 回调会返回该上传任务的 taskId | String | 是 |
重启上传任务
根据 taskId 重新开始上传任务,可以用于开启用户手动停止的(调用 pauseTask 停止)或者因为上传错误而停止的上传任务。
使用示例
var taskId = 'xxxxx'; /* 必须 */cos.restartTask(taskId);
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
taskId | 文件上传任务的编号,在调用 sliceUploadFile 方法时,其 TaskReady 回调会返回该上传任务的 taskId | String | 是 |
简单操作
简单上传对象
功能说明
注意
Key(文件名)不能以
/
结尾,否则会被识别为文件夹。Key(文件名)同名上传默认为覆盖操作。若您未开启版本控制且不想覆盖云上文件时,请确保上传时的Key不重复。
每个主账号(即同一个 APPID),存储桶的 ACL 规则数量最多为1000条,对象 ACL 规则数量不限制。如果您不需要进行对象 ACL 控制,请在上传时不要设置,默认继承存储桶权限。
上传之后,您可以用同样的 Key 生成预签名链接(下载请指定 method 为 GET,具体接口说明见下文),分享到其他端来进行下载。但注意如果您的文件是私有读权限,那么预签名链接只有一定的有效期。
使用示例
简单上传文件,适用于小文件上传。
const filePath = "temp-file-to-upload" // 本地文件路径cos.putObject({Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */Region: 'COS_REGION', /* 存储桶所在地域,例如 ap-beijing,必须字段 */Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */StorageClass: 'STANDARD',/* 当 Body 为 stream 类型时,ContentLength 必传,否则 onProgress 不能返回正确的进度信息 */Body: fs.createReadStream(filePath), // 上传文件对象ContentLength: fs.statSync(filePath).size,onProgress: function(progressData) {console.log(JSON.stringify(progressData));}}, function(err, data) {console.log(err || data);});
上传 Buffer 作为文件内容:
cos.putObject({Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */Region: 'COS_REGION', /* 存储桶所在地域,例如 ap-beijing,必须字段 */Key: '1.txt', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */Body: Buffer.from('hello!'), /* 必须 */}, 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.....';// 需要转为 Buffer上传var body = Buffer.from(base64Url.split(',')[1] , 'base64');cos.putObject({Bucket: 'examplebucket-1250000000', /* 必须 */Region: 'COS_REGION', /* 必须 */Key: '1.png', /* 必须 */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);});
自定义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);});
上传文件到指定目录 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, // 上传文件对象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.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */StorageClass: 'STANDARD',Body: fileObject, // 上传文件对象Headers: {'x-cos-traffic-limit':