注意:
目前查阅的是历史版本 SDK 文档,后续不再更新和维护,我们建议您查阅新版 SDK 文档 。
开发准备
SDK 获取
COS 服务的 JS SDK V4 版本的 GitHub 地址。
开发环境
- 使用 SDK 需要浏览器支持 HTML 5。
- 请您登录 腾讯云控制台 获取您的项目 ID(APPID),bucket,secret_id 和 secret_key。
- 请您登录 对象存储控制台 针对您要操作的 bucket 进行跨域(CORS)设置。
说明:
本版本 SDK 基于 JSON API 封装组成。
SDK 配置
直接下载 github 上提供的源代码,使用 SDK 之前,加载 dist 目录里的 cos-js-sdk-v4.js 文件即可。
<script type="text/javascript" src="cos-js-sdk-v4.js"></script>
初始化
var cos = new CosCloud({
appid: appid,
bucket: bucket,
region: 'sh',
getAppSign: function (callback) {
},
getAppSignOnce: function (callback) {
}
});
初始化参数说明
参数名 |
类型 |
是否必填 |
默认值 |
参数描述 |
appid |
int |
是 |
无 |
APPID |
bucket |
String |
是 |
无 |
bucket 名称 |
region |
String |
是 |
'gz' |
地域信息,必填参数,华南地区填gz 华东填sh 华北填tj |
getAppSign |
Function |
是 |
无 |
获取多次签名的函数,建议从服务器端获取签名字符串 |
getAppSignOnce |
Function |
是 |
无 |
获取单次签名的函数,建议从服务器端获取签名字符串 |
返回结果说明
返回值:cos object 对象,初始化之后可以用这个 cos object 对象进行内置接口调用例如 uploadFile,deleteFile 等。
文件操作
普通文件上传
接口说明:通常用于较小文件(一般小于20MB)的上传,可以通过此接口上传较小的文件并获得文件的 url,如果文件大于20M则本接口内部会去调用分片上传接口。
方法原型
cos.uploadFile(successCallBack, errorCallBack, progressCallBack, bucket, path, file, insertOnly);
参数说明
参数名 |
类型 |
是否必填 |
默认值 |
参数描述 |
successCallBack |
Function |
是 |
无 |
上传成功的回调 |
errorCallBack |
Function |
是 |
无 |
上传失败的回调 |
progressCallBack |
Function |
是 |
无 |
上传过程进度的回调,例如文件1M已经上传了100K则会回调进度0.1 |
bucket |
String |
是 |
无 |
bucket名称 |
path |
String |
是 |
无 |
文件在COS服务端的路径 |
file |
File |
是 |
无 |
本地要上传文件的文件对象(二进制数据) |
返回结果说明(json字符串)
参数名 |
类型 |
是否必然返回 |
参数描述 |
code |
Int |
是 |
错误码,成功时为0 |
message |
String |
是 |
提示信息 |
data |
Object |
是 |
返回数据 |
data.access_url |
String |
是 |
生成的文件 CDN 下载 url |
data.source_url |
String |
是 |
生成的文件 COS 源站 url |
data.url |
String |
是 |
操作文件的url |
data.resource_path |
String |
是 |
资源路径,格式:/appid/bucket/xxx |
示例
var myFolder = '/111/';
var successCallBack = function (result) {
$("#result").val(JSON.stringify(result));
};
var errorCallBack = function (result) {
result = result || {};
$("#result").val(result.responseText || 'error');
};
var progressCallBack = function(curr){
$("#result").val('uploading... curr progress is '+curr);
};
$('#js-file').off('change').on('change', function (e) {
var file = e.target.files[0];
cos.uploadFile(successCallBack, errorCallBack, progressCallBack, bucket, myFolder+file.name, file, 0);
return false;
});
大文件分片上传
接口说明:通常用于较大文件(一般大于20MB)的上传,可以通过此接口大的文件并获得文件的url。
方法原型
cos.sliceUploadFile(successCallBack, errorCallBack, progressCallBack, bucket, path, file, insertOnly);
参数说明
参数名 |
类型 |
是否必填 |
默认值 |
参数描述 |
successCallBack |
Function |
是 |
无 |
上传成功的回调 |
errorCallBack |
Function |
是 |
无 |
上传失败的回调 |
progressCallBack |
Function |
是 |
无 |
上传过程进度的回调,例如文件1M已经上传了100K则会回调进度0.1 |
bucket |
String |
是 |
无 |
bucket名称 |
path |
String |
是 |
无 |
文件在COS服务端的路径 |
file |
File |
是 |
无 |
本地要上传文件的文件对象(二进制数据) |
返回结果说明(json字符串)
需要注意的是大文件上传会经多个接口处理,以下是最后一片上传成功才会触发的回调
参数名 |
类型 |
是否必然返回 |
参数描述 |
code |
Int |
是 |
错误码,成功时为0 |
message |
String |
是 |
提示信息 |
data |
Object |
是 |
返回数据 |
data.access_url |
String |
是 |
生成的文件CDN下载url |
data.source_url |
String |
是 |
生成的文件COS源站url |
data.url |
String |
是 |
操作文件的url |
data.resource_path |
String |
是 |
资源路径. 格式:/appid/bucket/xxx |
示例
var myFolder = '/111/';
var successCallBack = function (result) {
$("#result").val(JSON.stringify(result));
};
var errorCallBack = function (result) {
result = result || {};
$("#result").val(result.responseText || 'error');
};
var progressCallBack = function(curr){
$("#result").val('uploading... curr progress is '+curr);
};
$('#js-file').off('change').on('change', function (e) {
var file = e.target.files[0];
cos.uploadFile(successCallBack, errorCallBack, progressCallBack, bucket, myFolder+file.name, file, 0);
return false;
});
删除文件
接口说明:删除文件
方法原型
cos.deleteFile(successCallBack, errorCallBack, bucket, path);
参数说明
参数名 |
类型 |
是否必填 |
默认值 |
参数描述 |
successCallBack |
Function |
是 |
无 |
操作成功的回调 |
errorCallBack |
Function |
是 |
无 |
操作失败的回调 |
bucket |
String |
是 |
无 |
bucket名称 |
path |
String |
是 |
无 |
文件在COS服务端的路径 |
返回结果说明(json字符串)
参数名 |
类型 |
是否必然返回 |
参数描述 |
code |
Int |
是 |
错误码,成功时为0 |
message |
String |
是 |
提示信息 |
示例
$('#deleteFile').on('click', function () {
var myFile = myFolder+'2.txt';
cos.deleteFile(successCallBack, errorCallBack, bucket, myFile);
});
获取文件属性
接口说明:通过此接口查询文件的各项属性信息。
方法原型
cos.getFileStat(successCallBack, errorCallBack, bucket, path);
参数说明
参数名 |
类型 |
是否必填 |
默认值 |
参数描述 |
successCallBack |
Function |
是 |
无 |
操作成功的回调 |
errorCallBack |
Function |
是 |
无 |
操作失败的回调 |
bucket |
String |
是 |
无 |
bucket名称 |
path |
String |
是 |
无 |
文件在COS服务端的路径 |
返回结果说明(json字符串)
参数名 |
类型 |
是否必然返回 |
参数描述 |
code |
Int |
是 |
错误码,成功时为0 |
message |
String |
是 |
错误信息 |
data |
Object |
是 |
文件属性数据 |
data.name |
String |
是 |
文件或目录名 |
data.biz_attr |
String |
是 |
文件属性,业务端维护 |
data.ctime |
String |
是 |
文件的创建时间,unix时间戳 |
data.mtime |
String |
是 |
文件的修改时间,unix时间戳 |
data.filesize |
Int |
是 |
文件大小 |
data.filelen |
Int |
是 |
文件已传输大小 |
data.sha |
String |
是 |
文件文件sha |
data.access_url |
String |
是 |
生成的文件下载url |
data.authority |
String |
否 |
eInvalid,eWRPrivate,eWPrivateRPublic,文件可以与 bucket 拥有不同的权限类型,已经设置过权限的文件如果想要撤销,直接赋值为eInvalid,则会采用 bucket 的权限 |
data.custom_headers |
String |
否 |
自定义header对象 |
示例
$('#getFileStat').on('click', function () {
var myFile = myFolder+'2.txt';
cos.getFileStat(successCallBack, errorCallBack, bucket, myFile);
});
更新文件属性
接口说明:通过此接口更新文件的属性信息。
方法原型
cos.updateFile(successCallBack, errorCallBack, bucket, path, bizAttr);
参数说明
参数名 |
类型 |
是否必填 |
默认值 |
参数描述 |
successCallBack |
Function |
是 |
无 |
操作成功的回调 |
errorCallBack |
Function |
是 |
无 |
操作失败的回调 |
bucket |
String |
是 |
无 |
bucket名称 |
path |
String |
是 |
无 |
文件在COS服务端的路径 |
bizAttr |
String |
是 |
无 |
文件的自定义属性 |
返回结果说明(json字符串)
参数名 |
类型 |
是否必然返回 |
参数描述 |
code |
Int |
是 |
错误码,成功时为0 |
message |
String |
是 |
错误信息 |
示例
$('#updateFile').on('click', function () {
var myFile = myFolder+'2.txt';
cos.updateFile(successCallBack, errorCallBack, bucket, myFile, 'my new file attr');
});
拷贝文件
接口说明:通过此接口把文件拷贝(即复制)到另一个路径。
方法原型
cos.copyFile(successCallBack, errorCallBack, bucket, path, destPath, overWrite);
参数说明
参数名 |
类型 |
是否必填 |
默认值 |
参数描述 |
successCallBack |
Function |
是 |
无 |
操作成功的回调 |
errorCallBack |
Function |
是 |
无 |
操作失败的回调 |
bucket |
String |
是 |
无 |
bucket名称 |
path |
String |
是 |
无 |
需要复制的文件在COS服务端的路径 |
destPath |
String |
是 |
无 |
复制的目标的路径 |
overWrite |
Int |
是 |
无 |
是否覆盖同名文件,0表示不覆盖,1表示覆盖 |
返回结果说明(json字符串)
参数名 |
类型 |
是否必然返回 |
参数描述 |
code |
Int |
是 |
错误码,成功时为0 |
message |
String |
是 |
错误信息 |
示例
$('#copyFile').on('click', function () {
var myFile = '111/2.txt';
var newFile = '/333/2.txt';
var overWrite = 1;
cos.copyFile(successCallBack, errorCallBack, bucket, myFile, newFile, overWrite);
});
移动文件
接口说明:通过此接口把文件移动(剪切)到另一个路径,如果是移动到相同路径的话,可以达到修改文件名的效果。
方法原型
cos.moveFile(successCallBack, errorCallBack, bucket, path, destPath, overWrite);
参数说明
参数名 |
类型 |
是否必填 |
默认值 |
参数描述 |
successCallBack |
Function |
是 |
无 |
操作成功的回调 |
errorCallBack |
Function |
是 |
无 |
操作失败的回调 |
bucket |
String |
是 |
无 |
bucket名称 |
path |
String |
是 |
无 |
需要移动的文件在COS服务端的路径 |
destPath |
String |
是 |
无 |
移动的目标的路径 |
overWrite |
Int |
是 |
无 |
是否覆盖同名文件,0表示不覆盖,1表示覆盖 |
返回结果说明(json字符串)
参数名 |
类型 |
是否必然返回 |
参数描述 |
code |
Int |
是 |
错误码,成功时为0 |
message |
String |
是 |
错误信息 |
示例
$('#moveFile').on('click', function () {
var myFile = '/111/2.txt';
var newFile = '/333/2.txt';
var overWrite = 1;
cos.moveFile(successCallBack, errorCallBack, bucket, myFile, newFile, overWrite);
});
文件夹(目录)操作
新增文件夹
接口说明:通过此接口增加一个指定的文件夹。
方法原型
cos.createFolder(successCallBack, errorCallBack, bucket, path);
参数说明
参数名 |
类型 |
是否必填 |
默认值 |
参数描述 |
successCallBack |
Function |
是 |
无 |
操作成功的回调 |
errorCallBack |
Function |
是 |
无 |
操作失败的回调 |
bucket |
String |
是 |
无 |
bucket名称 |
path |
String |
是 |
无 |
需要操作的文件夹在COS服务端的路径 |
返回结果说明(json字符串)
参数名 |
类型 |
是否必然返回 |
参数描述 |
code |
Int |
是 |
错误码,成功时为0 |
message |
String |
是 |
错误信息 |
示例
$('#createFolder').on('click', function () {
var newFolder = '/333/';
cos.createFolder(successCallBack, errorCallBack, bucket, newFolder);
});
删除文件夹
接口说明:通过此接口删除指定的文件夹。
方法原型
cos.deleteFolder(successCallBack, errorCallBack, bucket, path);
参数说明
参数名 |
类型 |
是否必填 |
默认值 |
参数描述 |
successCallBack |
Function |
是 |
无 |
操作成功的回调 |
errorCallBack |
Function |
是 |
无 |
操作失败的回调 |
bucket |
String |
是 |
无 |
bucket名称 |
path |
String |
是 |
无 |
需要操作的文件夹在COS服务端的路径 |
返回结果说明(json字符串)
参数名 |
类型 |
是否必然返回 |
参数描述 |
code |
Int |
是 |
错误码,成功时为0 |
message |
String |
是 |
错误信息 |
示例
$('#deleteFolder').on('click', function () {
var newFolder = '/333/';
cos.deleteFolder(successCallBack, errorCallBack, bucket, newFolder);
});
获取文件夹属性
接口说明:通过此接口获取指定的文件夹属性。
方法原型
cos.getFolderStat(successCallBack, errorCallBack, bucket, path);
参数说明
参数名 |
类型 |
是否必填 |
默认值 |
参数描述 |
successCallBack |
Function |
是 |
无 |
操作成功的回调 |
errorCallBack |
Function |
是 |
无 |
操作失败的回调 |
bucket |
String |
是 |
无 |
bucket名称 |
path |
String |
是 |
无 |
需要操作的文件夹在COS服务端的路径 |
返回结果说明(json字符串)
参数名 |
类型 |
是否必然返回 |
参数描述 |
code |
Int |
是 |
错误码,成功时为0 |
message |
String |
是 |
错误信息 |
data |
Object |
是 |
文件夹属性信息对象 |
data.biz_attr |
String |
是 |
文件夹属性信息字符串 |
示例
$('#getFolderStat').on('click', function () {
cos.getFolderStat(successCallBack, errorCallBack, bucket, '/333/');
});
更新文件夹属性
接口说明:通过此接口更新指定的文件夹属性。
方法原型
cos.updateFolder(successCallBack, errorCallBack, bucket, path, bizAttr);
参数说明
参数名 |
类型 |
是否必填 |
默认值 |
参数描述 |
successCallBack |
Function |
是 |
无 |
操作成功的回调 |
errorCallBack |
Function |
是 |
无 |
操作失败的回调 |
bucket |
String |
是 |
无 |
bucket名称 |
path |
String |
是 |
无 |
需要操作的文件夹在COS服务端的路径 |
bizAttr |
String |
是 |
无 |
新的属性信息 |
返回结果说明(json字符串)
参数名 |
类型 |
是否必然返回 |
参数描述 |
code |
Int |
是 |
错误码,成功时为0 |
message |
String |
是 |
错误信息 |
示例
$('#updateFolder').on('click', function () {
cos.updateFolder(successCallBack, errorCallBack, bucket, '/333/', 'new attr');
});
获取文件夹内列表
接口说明:通过此接口获取指定的文件夹内的文件列表。
方法原型
cos.getFolderList(successCallBack, errorCallBack, bucket, path);
参数说明
参数名 |
类型 |
是否必填 |
默认值 |
参数描述 |
successCallBack |
Function |
是 |
无 |
操作成功的回调 |
errorCallBack |
Function |
是 |
无 |
操作失败的回调 |
bucket |
String |
是 |
无 |
bucket名称 |
path |
String |
是 |
无 |
需要操作的文件夹在COS服务端的路径 |
返回结果说明(json字符串)
参数名 |
类型 |
是否必然返回 |
参数描述 |
code |
Int |
是 |
API 错误码,成功时为0 |
message |
String |
是 |
错误信息 |
data |
Array |
是 |
返回数据 |
data.listover |
Bool |
是 |
是否有内容可以继续往前/往后翻页 |
data.context |
String |
是 |
透传字段,查看第一页,则传空字符串。若需要翻页,需要将前一页返回值中的context透传到参数中。order用于指定翻页顺序。若order填0,则从当前页正序/往下翻页;若order填1,则从当前页倒序/往上翻页 |
data.infos |
Array |
是 |
文件、目录集合,可以为空 |
data.infos.name |
String |
是 |
文件或目录名 |
data.infos.biz_attr |
String |
是 |
目录或文件属性,业务端维护 |
data.infos.ctime |
String |
是 |
目录或文件的创建时间,unix时间戳 |
data.infos.mtime |
String |
是 |
目录或文件的修改时间,unix时间戳 |
data.infos.filesize |
Int |
否(当类型为文件时返回) |
文件大小 |
data.infos.filelen |
Int |
否(当类型为文件时返回) |
文件已传输大小(通过与filesize对比可知文件传输进度) |
data.infos.sha |
String |
否(当类型为文件时返回) |
文件sha |
data.infos.access_url |
String |
否(当类型为文件时返回) |
生成的文件下载url |
data.infos.authority |
String |
否 |
eInvalid,eWRPrivate,eWPrivateRPublic,文件可以与bucket拥有不同的权限类型,已经设置过权限的文件如果想要撤销,直接赋值为eInvalid,则会采用bucket的权限 |
示例
$('#getFolderList').on('click', function () {
cos.getFolderList(successCallBack, errorCallBack, bucket, myFolder);
});