快速入门

最近更新时间:2019-07-19 16:06:05

下载与安装

相关资源

环境依赖

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

说明:

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

安装 SDK

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

手动安装

复制源码文件中的 cos-wx-sdk-v5.js 到自己小程序代码目录里,代码可以通过相对路径引用:

var COS = require('./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. 如果标准请求可以配置 Bucket 域名作为白名单域名,例如:
    examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
  2. 如果小程序使用的存储桶多,可以选择后缀式请求 COS,只需要在 SDK 实例化时传入ForcePathStyle: true,这种方式需要配置地域域名作为白名单,例如:cos.ap-guangzhou.myqcloud.com

初始化

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: 'text',
            success: function (result) {
                var data = result.data;
                var credentials = data.credentials;
                callback({
                    TmpSecretId: credentials.tmpSecretId,
                    TmpSecretKey: credentials.tmpSecretKey,
                    XCosSecurityToken: credentials.sessionToken,
                    ExpiredTime: data.expiredTime,
                });
            }
        });
    }
});

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

配置项

使用示例

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

  • 格式一(推荐):后端通过获取临时密钥给到前端,前端计算签名。
var COS = require('cos-nodejs-sdk-v5');
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://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.credentials;
                callback({
                    TmpSecretId: credentials.tmpSecretId,
                    TmpSecretKey: credentials.tmpSecretKey,
                    XCosSecurityToken: credentials.sessionToken,
                    ExpiredTime: data.expiredTime,
                });
            }
        });
    }
});
  • 格式二(推荐):细粒度控制权限,后端通过获取临时密钥给到前端,前端只有相同请求才重复使用临时密钥,后端可以通过 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.credentials;
                callback({
                    TmpSecretId: credentials.tmpSecretId,
                    TmpSecretKey: credentials.tmpSecretKey,
                    XCosSecurityToken: credentials.sessionToken,
                    ExpiredTime: data.expiredTime,
                    ScopeLimit: true, // 细粒度控制权限需要设为 true,会限制密钥只在相同请求时重复使用
                });
            }
        });
    }
});
  • 格式三(不推荐):前端每次请求前都需要通过 getAuthorization 获取签名,后端使用固定密钥或临时密钥计算签名返回给前端。该格式分片上传权限不易控制,不推荐您使用此格式。
var cos = new COS({
    // 必选参数
    getAuthorization: function (options, callback) {
        // 服务端获取签名,请参考对应语言的 COS SDK:https://cloud.tencent.com/document/product/436/6474
        // 注意:这种有安全风险,后端需要通过 method、pathname 严格控制好权限,例如不允许 put / 等
        wx.request({
            url: 'https://example.com/server/auth.php',
            data: JSON.stringify(options.Scope),
            success: function (result) {
                var data = result.data;
                callback({
                    Authorization: data.authorization,
                    // XCosSecurityToken: data.sessionToken, // 如果使用临时密钥,需要把 sessionToken 传给 XCosSecurityToken
                });
            }
        });
    },
});
  • 格式四(不推荐):前端使用固定密钥计算签名,该格式适用于前端调试,若使用此格式,请避免泄露密钥。
var cos = new COS({
    SecretId: 'COS_SECRETID',
    SecretKey: 'COS_SECRETKEY',
});

构造函数参数说明

参数名 参数描述 类型 必填
SecretId 用户的 SecretId String
SecretKey 用户的 SecretKey,建议只在前端调试时使用,避免暴露密钥 String
CopyChunkParallelLimit 同一个上传文件的分片并发数,默认值3 Number
CopyChunkSize 分片上传时,出错重试次数,默认值3(加第一次,请求共4次) Number
CopySliceSize 分片上传时,每片的大小字节数,默认值1048576 (1MB) Number
Protocol 发请求时用的协议,可选项https:http:,默认判断当前页面是http:时使用http:,否则使用https: String
ServiceDomain 调用 getService 方法时,请求的域名
例如cos.ap-beijing.myqcloud.com
String
Domain 调用 Bucket 的请求域名,可以使用模版
例如"{Bucket}.cos.{Region}.myqcloud.com
String
ForcePathStyle 强制使用后缀式发请求,后缀式 Bucket 会放在域名后的 pathname 里,并且 Bucket 会加入签名 pathname 计算,默认为 false Boolean
UploadCheckContentMd5 强制上传文件也校验 Content-MD5,会对文件请求 Body 计算 md5 放在 header 的 Content-MD5 字段里,默认为 false Boolean
getAuthorization 获取签名的回调方法,如果没有 SecretId、SecretKey 时,这个参数必选 Function

getAuthorization 回调函数说明的函数说明(使用格式一)

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

getAuthorization 的回调参数说明:

参数名 参数描述 类型
options 获取临时密钥需要的参数对象 Function
- Bucket Bucket 的名称,命名规则为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
- Region Bucket 所在地域,枚举值请见 Bucket 地域信息 String
callback 临时密钥获取完成后的回传方法 Function

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

属性名 参数描述 类型 必填
TmpSecretId 获取回来的临时密钥的 tmpSecretId String
TmpSecretKey 获取回来的临时密钥的 tmpSecretKey String
XCosSecurityToken 获取回来的临时密钥的 sessionToken,对应 header 的 x-cos-security-token 字段 String
ExpiredTime 获取回来的临时密钥的 expiredTime,超时时间 String

getAuthorization 回调函数说明(使用格式二)

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

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

参数名 参数描述 类型 必填
options 获取签名需要的参数对象 Object
- Method 当前请求的 Method Object
- Pathname 请求路径,用于签名计算 String
- Key 对象键(Object 的名称),对象在存储桶中的唯一标识,了解更多可参见 对象概述 String
- Query 当前请求的 query 参数对象,{key: 'val'} 的格式 Object
- Headers 当前请求的 header 参数对象,{key: 'val'} 的格式 Object
callback 临时密钥获取完成后的回调 Function

getAuthorization 计算完成后,callback 回传一个签名字符串或一个对象:
回传签名字符串时,回传字符串类型,是请求要用的鉴权 Header 凭证字段 Authorization。
回传对象时,回传对象属性列表如下:

属性名 参数描述 类型 必填
Authorization 获取回来的临时密钥的 String
XCosSecurityToken 获取回来的临时密钥的 sessionToken,对应 header 的 x-cos-security-token 字段 String

获取鉴权凭证

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

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

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

创建存储桶

cos.putBucket({
    Bucket: 'examplebucket-1250000000',
    Region: 'ap-beijing',
    Key: filename,
}, 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);
});