下载与安装

相关资源

• 对象存储 COS 的 XML 小程序 SDK 源码下载地址：XML 小程序 SDK。
• SDK 快速下载地址：XML 小程序 SDK。
• 演示示例 Demo 下载地址：XML 小程序 SDK Demo。
• SDK 文档中的所有示例代码请参见 SDK 代码示例。
• SDK 更新日志请参见 ChangeLog。

环境依赖

1. 该 SDK 只适用于微信小程序环境。
2. 登录 对象存储控制台 创建存储桶后，获取存储桶名称和 地域信息。
3. 登录 访问管理控制台 获取您的项目 SecretId 和 SecretKey。

说明：

关于本文中出现的 SecretId、SecretKey、Bucket 等名称的含义和获取方式请参见 COS 术语信息。

安装 SDK

安装小程序 SDK 有两种方式：手动安装和 npm 安装，具体安装方法如下。

手动安装

复制源码文件中的 cos-wx-sdk-v5.js 到自己小程序代码根目录下任意路径，并用相对路径引用：

var COS = require('./lib/cos-wx-sdk-v5.js')

npm 安装

如果小程序代码使用了 webpack 打包，则通过 npm 安装依赖即可：

npm install cos-wx-sdk-v5

其中小程序代码使用var COS = require('cos-wx-sdk-v5');进行引用。

开始使用

小程序域名白名单配置

小程序里请求 COS 需要登录到 微信公众平台，选择【开发】>【开发设置】>【服务器域名】，配置域名白名单。SDK 使用到了两个接口：

1. cos.postObject 使用 wx.uploadFile 方法。
2. 其他方法使用 wx.request 方法。

需要在对应白名单里，配置 COS 域名，白名单域名格式有两种：

1. 如果是标准请求，可以配置存储桶域名作为白名单域名，例如：
   examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com。
2. 如果小程序使用的存储桶多，可以选择后缀式请求 COS，只需要在 SDK 实例化时传入ForcePathStyle: true，这种方式需要配置地域域名作为白名单，例如：cos.ap-guangzhou.myqcloud.com。

初始化

var COS = require('./lib/cos-wx-sdk-v5.js')

var cos = new COS({
    // ForcePathStyle: true, // 如果使用了很多存储桶，可以通过打开后缀式，减少配置白名单域名数量，请求时会用地域域名
    getAuthorization: function (options, callback) {
        // 异步获取临时密钥
        wx.request({
            url: 'https://example.com/server/sts.php',
            data: {
                bucket: options.Bucket,
                region: options.Region,
            },
            dataType: 'json',
            success: function (result) {
                var data = result.data;
                var credentials = data && data.credentials;
                if (!data || !credentials) return console.error('credentials invalid');
                callback({
                    TmpSecretId: credentials.tmpSecretId,
                    TmpSecretKey: credentials.tmpSecretKey,
                    XCosSecurityToken: credentials.sessionToken,
                    // 建议返回服务器时间作为签名的开始时间，避免用户浏览器本地时间偏差过大导致签名错误
                    StartTime: data.startTime, // 时间戳，单位秒，如：1580000000
                    ExpiredTime: data.expiredTime, // 时间戳，单位秒，如：1580000900
                });
            }
        });
    }
});

// 接下来可以通过 cos 实例调用 COS 请求。
// TODO

配置项

使用示例

创建一个 COS SDK 实例，COS SDK 支持以下几种格式创建：

• 格式一（推荐）：后端通过获取临时密钥给到前端，前端计算签名。

var cos = new COS({
    // 必选参数
    getAuthorization: function (options, callback) {
        // 服务端 JS 和 PHP 示例：https://github.com/tencentyun/cos-js-sdk-v5/blob/master/server/
        // 服务端其他语言参考 COS STS SDK ：https://github.com/tencentyun/qcloud-cos-sts-sdk
        // STS 详细文档指引看：https://intl.cloud.tencent.com/document/product/436/14048
        wx.request({
            url: 'https://example.com/server/sts.php',
            data: {
                // 可从 options 取需要的参数
            },
            success: function (result) {
                var data = result.data;
                var credentials = data && data.credentials;
                if (!data || !credentials) return console.error('credentials invalid');
                callback({
                    TmpSecretId: credentials.tmpSecretId,
                    TmpSecretKey: credentials.tmpSecretKey,
                    XCosSecurityToken: credentials.sessionToken,
                    // 建议返回服务器时间作为签名的开始时间，避免用户浏览器本地时间偏差过大导致签名错误
                    StartTime: data.startTime, // 时间戳，单位秒，如：1580000000
                    ExpiredTime: data.expiredTime, // 时间戳，单位秒，如：1580000900
                });
            }
        });
    }
});

说明：

临时密钥生成和使用可参见 临时密钥生成及使用指引。

• 格式二（推荐）：细粒度控制权限，后端通过获取临时密钥给到前端，前端只有相同请求才重复使用临时密钥，后端可以通过 Scope 细粒度控制权限。

var cos = new COS({
    // 必选参数
    getAuthorization: function (options, callback) {
        // 服务端示例：https://github.com/tencentyun/qcloud-cos-sts-sdk/edit/master/scope.md
        wx.request({
            url: 'https://example.com/server/sts-scope.php',
            data: JSON.stringify(options.Scope),
            success: function (result) {
                var data = result.data;
                var credentials = data && data.credentials;
                if (!data || !credentials) return console.error('credentials invalid');
                callback({
                    TmpSecretId: credentials.tmpSecretId,
                    TmpSecretKey: credentials.tmpSecretKey,
                    XCosSecurityToken: credentials.sessionToken,
                    // 建议返回服务器时间作为签名的开始时间，避免用户浏览器本地时间偏差过大导致签名错误
                    StartTime: data.startTime, // 时间戳，单位秒，如：1580000000
                    ExpiredTime: data.expiredTime, // 时间戳，单位秒，如：1580000900
                    ScopeLimit: true, // 细粒度控制权限需要设为 true，会限制密钥只在相同请求时重复使用
                });
            }
        });
    }
});

说明：

临时密钥生成和使用可参见 临时密钥生成及使用指引。

• 格式三（不推荐）：前端每次请求前都需要通过 getAuthorization 获取签名，后端使用固定密钥或临时密钥计算签名返回给前端。该格式分块上传权限不易控制，不推荐您使用此格式。

var cos = new COS({
    // 必选参数
    getAuthorization: function (options, callback) {
        // 服务端获取签名，请参考对应语言的 COS SDK：https://intl.cloud.tencent.com/document/product/436/6474?from_cn_redirect=1
        // 注意：这种有安全风险，后端需要通过 method、pathname 严格控制好权限，例如不允许 put / 等
        wx.request({
            url: 'https://example.com/server/auth.php',
            data: JSON.stringify(options.Scope),
            success: function (result) {
                var data = result.data;
                if (!data || !data.authorization) return console.error('authorization invalid');
                callback({
                    Authorization: data.authorization,
                    // XCosSecurityToken: data.sessionToken, // 如果使用临时密钥，需要把 sessionToken 传给 XCosSecurityToken
                });
            }
        });
    },
});

• 格式四（不推荐）：前端使用固定密钥计算签名，该格式适用于前端调试，若使用此格式，请避免泄露密钥。

var cos = new COS({
    SecretId: 'COS_SECRETID',
    SecretKey: 'COS_SECRETKEY',
});

构造函数参数说明

getAuthorization 回调函数说明的函数说明（使用格式一）

getAuthorization: function(options, callback) { ... }

getAuthorization 的回调参数说明：

获取完临时密钥后，callback 回传一个对象，回传对象的属性列表如下：

getAuthorization 回调函数说明（使用格式二）

getAuthorization: function(options, callback) { ... }

getAuthorization 的函数说明回调参数说明：

getAuthorization 计算完成后，callback 回传参数支持两种格式：
格式一：回传鉴权凭证字符串 Authorization。
格式二：回传一个对象，对象属性列表如下：

获取鉴权凭证

实例本身鉴权凭证可以通过实例化时传入的参数控制如何或获取，有三种获取方式：

1. 实例化时，传入 SecretId、SecretKey，每次需要签名都由实例内部计算。
2. 实例化时，传入 getAuthorization 回调，每次需要签名通过这个回调计算完返回签名给实例。
3. 实例化时，传入 getSTS 回调，每次需要临时密钥通过这个回调回去完返回给实例，在每次请求时实例内部使用临时密钥计算得到签名。

以下是部分常用接口示例，更详细的初始化方法请参见 demo 示例。

创建存储桶

cos.putBucket({
    Bucket: 'examplebucket-1250000000',
    Region: 'ap-beijing',
}, function (err, data) {
    console.log(err || data);
});

注意：

如果需要在小程序创建存储桶，但存储桶名称未知时，无法将存储桶名称配置为域名白名单，可以使用后缀式调用，相关处理措施请参见 常见问题。

查询存储桶列表

cos.getService(function (err, data) {
    console.log(data && data.Buckets);
});

上传对象

小程序上传接口 wx.uploadFile 只支持 POST 请求，SDK 上传文件则需要使用 postObject 接口，如果小程序里只需要用到上传文件接口，建议不引用 SDK，请参见简单示例 demo。

// 先选择文件，得到临时路径
wx.chooseImage({
    count: 1, // 默认9
    sizeType: ['original'], // 可以指定是原图还是压缩图，默认用原图
    sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机，默认二者都有
    success: function (res) {
        var filePath = res.tempFiles[0].path;
        var filename = filePath.substr(filePath.lastIndexOf('/') + 1);
        cos.postObject({
            Bucket: 'examplebucket-1250000000',
            Region: 'ap-beijing',
            Key: '目标路径/' + filename,
            FilePath: filePath,
            onProgress: function (info) {
                console.log(JSON.stringify(info));
            }
        }, function (err, data) {
            console.log(err || data);
        });
    }
});

查询对象列表

cos.getBucket({
    Bucket: 'examplebucket-1250000000',
    Region: 'ap-beijing',
    Prefix: 'exampledir/', // 这里传入列出的文件前缀
}, function (err, data) {
    console.log(err || data.Contents);
});

下载对象

注意：

该接口用于读取对象内容，如果需要发起浏览器下载文件，可以通过 cos.getObjectUrl 获取 url 再触发浏览器下载，具体参见 预签名 URL 文档。

cos.getObject({
    Bucket: 'examplebucket-1250000000',
    Region: 'ap-beijing',
    Key: 'exampleobject.txt',
}, function (err, data) {
    console.log(err || data.Body);
});

删除对象

cos.deleteObject({
    Bucket: 'examplebucket-1250000000',
    Region: 'ap-beijing',
    Key: 'picture.jpg',
}, function (err, data) {
    console.log(err || data);
});