JavaScript SDK

注意：

目前查阅的是历史版本 SDK 文档，后续不再更新和维护，我们建议您查阅新版 SDK 文档 。

开发准备

SDK 获取

COS 服务的 JS SDK V4 版本的 GitHub 地址。

开发环境

1. 使用 SDK 需要浏览器支持 HTML 5。
2. 请您登录 腾讯云控制台 获取您的项目 ID（APPID），bucket，secret_id 和 secret_key。
3. 请您登录 对象存储控制台 针对您要操作的 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>

初始化

    //初始化逻辑
    //特别注意: JS-SDK使用之前请先到console.cloud.tencent.com/cos 对相应的Bucket进行跨域设置
    var cos = new CosCloud({
        appid: appid,// APPID 必填参数
        bucket: bucket,//bucketName 必填参数
        region: 'sh',//地域信息 必填参数 华南地区填gz 华东填sh 华北填tj
        getAppSign: function (callback) {//获取签名 必填参数

            //下面介绍获取签名的几种办法

            //1.搭建一个鉴权服务器，自己构造请求参数获取签名，推荐实际线上业务使用，优点是安全性好，不会暴露自己的私钥
            //拿到签名之后记得调用callback
            /**
             $.ajax('SIGN_URL').done(function (data) {
                var sig = data.sign;
                callback(sig);
            });
             **/

            //2.直接在浏览器前端计算签名，需要获取自己的accessKey和secretKey, 一般在调试阶段使用
            //拿到签名之后记得调用callback
            //var res = getAuth(); //这个函数自己根据签名算法实现
            //callback(res);


            //3.直接复用别人算好的签名字符串, 一般在调试阶段使用
            //拿到签名之后记得调用callback
            //callback('YOUR_SIGN_STR')
            //

        },
        getAppSignOnce: function (callback) {//单次签名，必填参数，参考上面的注释即可
            //填上获取单次签名的逻辑
        }
    });

初始化参数说明

返回结果说明

返回值：cos object 对象，初始化之后可以用这个 cos object 对象进行内置接口调用例如 uploadFile，deleteFile 等。

文件操作

普通文件上传

接口说明：通常用于较小文件（一般小于20MB）的上传，可以通过此接口上传较小的文件并获得文件的 url，如果文件大于20M则本接口内部会去调用分片上传接口。

方法原型

cos.uploadFile(successCallBack, errorCallBack, progressCallBack, bucket, path, file, insertOnly);

参数说明

返回结果说明（json字符串）

示例

    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);

参数说明

返回结果说明(json字符串)

需要注意的是大文件上传会经多个接口处理，以下是最后一片上传成功才会触发的回调

示例

    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];
        //大文件也可以直接调用uploadFile
        cos.uploadFile(successCallBack, errorCallBack, progressCallBack, bucket, myFolder+file.name, file, 0);
        //也可以用sliceUploadFile，选一个即可
        //cos.sliceUploadFile(successCallBack, errorCallBack, progressCallBack, bucket, myFolder+file.name, file, 0);
        return false;
    });

删除文件

接口说明：删除文件

方法原型

cos.deleteFile(successCallBack, errorCallBack, bucket, path);

参数说明

返回结果说明(json字符串)

示例

    //删除文件
    $('#deleteFile').on('click', function () {
        var myFile = myFolder+'2.txt';//填您自己实际存在的文件
        cos.deleteFile(successCallBack, errorCallBack, bucket, myFile);
    });

获取文件属性

接口说明：通过此接口查询文件的各项属性信息。

方法原型

cos.getFileStat(successCallBack, errorCallBack, bucket, path);

参数说明

返回结果说明（json字符串）

示例

    //获取文件属性
    $('#getFileStat').on('click', function () {
        var myFile = myFolder+'2.txt';//填您自己实际存在的文件
        cos.getFileStat(successCallBack, errorCallBack, bucket, myFile);
    });

更新文件属性

接口说明：通过此接口更新文件的属性信息。

方法原型

cos.updateFile(successCallBack, errorCallBack, bucket, path, bizAttr);

参数说明

返回结果说明（json字符串）

示例

    //更新文件属性
    $('#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);

参数说明

返回结果说明（json字符串）

示例

    //拷贝文件，从源文件地址复制一份到新地址
    $('#copyFile').on('click', function () {

        var myFile = '111/2.txt';//填您自己实际存在的文件

        //注意目标的路径，这里如果填333/2.txt 则表示文件复制到111/333/2.txt
        //如果填/333/2.txt 则表示文件复制到bucket根目录下的333/2.txt
        var newFile = '/333/2.txt';
        var overWrite = 1;//0 表示不覆盖 1表示覆盖
        cos.copyFile(successCallBack, errorCallBack, bucket, myFile, newFile, overWrite);
    });

移动文件

接口说明：通过此接口把文件移动（剪切）到另一个路径，如果是移动到相同路径的话，可以达到修改文件名的效果。

方法原型

cos.moveFile(successCallBack, errorCallBack, bucket, path, destPath, overWrite);

参数说明

返回结果说明（json字符串）

示例

    //移动文件，把源文件移动到新地址，如果是同一个目录移动且文件名不同的话，相当于改了一个文件名
    //如果是移动到新目录，相当于剪切当前的文件，粘贴到了新目录
    $('#moveFile').on('click', function () {

        var myFile = '/111/2.txt';//填您自己实际存在的文件

        //注意目标的路径，这里如果填333/2.txt 则表示文件移动到111/333/2.txt
        //如果填/333/2.txt 则表示文件移动到bucket根目录下的333/2.txt
        //如果填/111/3.txt 则相当于把2.txt改名成3.txt
        var newFile = '/333/2.txt';
        var overWrite = 1;//0 表示不覆盖 1表示覆盖
        cos.moveFile(successCallBack, errorCallBack, bucket, myFile, newFile, overWrite);
    });

文件夹（目录）操作

新增文件夹

接口说明：通过此接口增加一个指定的文件夹。

方法原型

cos.createFolder(successCallBack, errorCallBack, bucket, path);

参数说明

返回结果说明（json字符串）

示例

    $('#createFolder').on('click', function () {
        var newFolder = '/333/';//填您需要创建的文件夹
        cos.createFolder(successCallBack, errorCallBack, bucket, newFolder);
    });

删除文件夹

接口说明：通过此接口删除指定的文件夹。

方法原型

cos.deleteFolder(successCallBack, errorCallBack, bucket, path);

参数说明

返回结果说明（json字符串）

示例

    //删除文件夹
    $('#deleteFolder').on('click', function () {
        var newFolder = '/333/';//填您需要删除的文件夹
        cos.deleteFolder(successCallBack, errorCallBack, bucket, newFolder);
    });

获取文件夹属性

接口说明：通过此接口获取指定的文件夹属性。

方法原型

cos.getFolderStat(successCallBack, errorCallBack, bucket, path);

参数说明

返回结果说明（json字符串）

示例

    //获取文件夹属性
    $('#getFolderStat').on('click', function () {
        cos.getFolderStat(successCallBack, errorCallBack, bucket, '/333/');
    });

更新文件夹属性

接口说明：通过此接口更新指定的文件夹属性。

方法原型

cos.updateFolder(successCallBack, errorCallBack, bucket, path, bizAttr);

参数说明

返回结果说明（json字符串）

示例

    //更新文件夹属性
    $('#updateFolder').on('click', function () {
        cos.updateFolder(successCallBack, errorCallBack, bucket, '/333/', 'new attr');
    });

获取文件夹内列表

接口说明：通过此接口获取指定的文件夹内的文件列表。

方法原型

cos.getFolderList(successCallBack, errorCallBack, bucket, path);

参数说明

返回结果说明（json字符串）

示例

    //获取指定文件夹内的列表,默认每次返回20条
    $('#getFolderList').on('click', function () {
        cos.getFolderList(successCallBack, errorCallBack, bucket, myFolder);
    });