快速入门

最近更新时间:2019-07-16 14:37:51

下载与安装

相关资源

准备环境

  1. JavaScript SDK 需浏览器支持基本的 HTML5 特性(支持 IE10 以上浏览器),以便支持 ajax 上传文件和计算文件 MD5 值。
  2. 登录 对象存储控制台创建存储桶。获取存储桶名称和 地域名称
  3. 登录 访问管理控制台 ,获取您的项目 SecretId 和 SecretKey。
  4. 配置 CORS 规则,AllowHeader 需配成*,ExposeHeaders 需要 ETag、Content-Length 以及其他 js 需要读取的 header 字段,如下图所示。操作详情请参见 设置跨域访问 文档。
    CORS示例

说明:

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

安装 SDK

您可以通过以下方式安装 SDK:

script 引入

<script src="./cos-auth.min.js"></script>

在 script 标签引用 SDK 时,SDK 占用了全局变量名 COS,通过它的构造函数可以创建 SDK 实例。

webpack 引入方式

通过npm i cos-js-sdk-v5 --save安装 SDK 依赖,支持 webpack 打包的场景,您可以用 npm 引入作为模块,代码如下:

var COS = require('cos-js-sdk-v5');

开始使用

获取临时密钥

由于密钥放在前端会暴露 SecretId 和 SecretKey,我们把永久密钥过程放在后端,前端通过 ajax 向后端获取一个临时密钥,正式部署时请再后端加一层您网站本身的权限检验。具体内容请参见 临时密钥生成及使用指引 文档。

初始化

  1. 创建 web.html,填入如下代码,并修改 web.html 中的存储桶名称和 Region。
  2. 部署好后端的临时密钥服务,并修改 getAuthorization 里的密钥服务地址。
  3. 把 web.html 放在 Web 服务器下,然后在浏览器访问页面,测试文件上传。web.html 文件示例代码如下:
<input id="file-selector" type="file">
<script src="dist/cos-js-sdk-v5.min.js"></script>
<script>
var Bucket = 'examplebucket-1250000000';
var Region = 'ap-beijing';

// 初始化实例
var cos = new COS({
    getAuthorization: function (options, callback) {
        // 异步获取临时密钥
        $.get('http://example.com/server/sts.php', {
            bucket: options.Bucket,
            region: options.Region,
        }, function (data) {
            var credentials = data.credentials;
            callback({
                 TmpSecretId: credentials.tmpSecretId, 
                 TmpSecretKey: credentials.tmpSecretKey, 
                 XCosSecurityToken: credentials.sessionToken, 
                 ExpiredTime: data.expiredTime
            });
        });
    }
});

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

</script>

配置项

使用示例

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

  • 格式一(推荐):后端通过获取临时密钥给到前端,前端计算签名。
    var COS = require('cos-js-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
          $.get('http://example.com/server/sts.php', {
              // 可从 options 取需要的参数
          }, function (data) {
              callback({
                  TmpSecretId: data.TmpSecretId,
                  TmpSecretKey: data.TmpSecretKey,
                  XCosSecurityToken: data.XCosSecurityToken,
                  ExpiredTime: data.ExpiredTime, // SDK 在 ExpiredTime 时间前,不会再次调用 getAuthorization
              });
          });
      }
    });
  • 格式二(推荐):细粒度控制权限,后端通过获取临时密钥给到前端,只有在相同请求时,前端才重复使用临时密钥,后端可以通过 Scope 细粒度控制权限。
    var COS = require('cos-js-sdk-v5');
    var cos = new COS({
      // 必选参数
      getAuthorization: function (options, callback) {
          // 服务端例子:https://github.com/tencentyun/qcloud-cos-sts-sdk/edit/master/scope.md
          $.ajax({
              method: 'POST',
              url: ' http://example.com/server/sts-scope.php',
              data: JSON.stringify(options.Scope),
              beforeSend: function () {
                  xhr.setRequestHeader('Content-Type', 'application/json');
              },
              dataType: 'json',
              success: function (data) {
                  var credentials = data.credentials;
                  callback({
                      TmpSecretId: credentials.tmpSecretId,
                      TmpSecretKey: credentials.tmpSecretKey,
                      XCosSecurityToken: credentials.sessionToken, // 需要提供把 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 / 等
          $.get('http://example.com/server/auth.php', {
              method: options.Method,
              pathname: '/' + options.Key,
          }, function (data) {
              callback({
                  Authorization: data.authorization,
                  // XCosSecurityToken: data.sessionToken, // 如果使用临时密钥,需要把 sessionToken 传给 XCosSecurityToken
              });
          });
      },
      // 可选参数
      FileParallelLimit: 3,    // 控制文件上传并发数
      ChunkParallelLimit: 3,   // 控制单个文件下分片上传并发数
      ProgressInterval: 1000,  // 控制上传的 onProgress 回调的间隔
    });
  • 格式四(不推荐):前端使用固定密钥计算签名,该格式适用于前端调试,若使用此格式,请避免泄露密钥。
    var cos = new COS({
      SecretId: 'COS_SECRETID',
      SecretKey: 'COS_SECRETKEY',
    });

构造函数参数说明

参数名 参数描述 类型 必填
SecretId 用户的 SecretId String
SecretKey 用户的 SecretKey,建议只在前端调试时使用,避免暴露密钥 String
FileParallelLimit 同一个实例下上传的文件并发数,默认值3 Number
ChunkParallelLimit 同一个上传文件的分片并发数,默认值3 Number
ChunkRetryTimes 分片上传时,出错重试次数,默认值3(加第一次,请求共4次) Number
ChunkSize 分片上传时,每片的大小字节数,默认值1048576(1MB) Number
SliceSize 使用 uploadFiles 批量上传时,文件大小大于该数值就使用分片上传 sliceUploadFile,否则使用简单上传 putObject Number
CopyChunkParallelLimit 同一个上传文件的分片并发数,默认值3 Number
CopyChunkSize 分片上传时,出错重试次数,默认值3(加第一次,请求共4次) Number
CopySliceSize 分片上传时,每片的大小字节数,默认值1048576(1MB) Number
ProgressInterval 上传进度的回调方法 onProgress 的回调频率,单位 ms ,默认值1000 Number
Protocol 发请求时用的协议,可选项https:http:,默认判断当前页面是http: 时使用http:,否则使用https: String
ServiceDomain 调用 getService 方法时,请求的域名,例如cos.ap-beijing.myqcloud.com String
Domain 调用 Bucket 的请求域名,可以使用模版,例如"{Bucket}.cos.{Region}.myqcloud.com" String
UploadQueueSize 上传队列最长大小,超出的任务如果状态不是 waiting、checking、uploading 会被清理,默认10000 Number
ForcePathStyle 强制使用后缀式发请求,后缀式 Bucket 会放在域名后的 pathname 里,并且 Bucket 会加入签名 pathname 计算,默认 false Boolean
UploadCheckContentMd5 上传文件时校验 Content-MD5,默认 false。如果开启,上传文件时会对文件内容计算 MD5,大文件耗时较长 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. 实例化时,传入 getAuthorization 回调,调用回调时返回临时密钥凭证,在临时密钥凭证过期后会再次调用该回调。

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

上传对象

简单上传接口适用于小文件上传,大文件请使用分块上传接口,详情请参见 对象操作 文档。

document.getElementById('file-selector').onchange = function () {
    var file = this.files[0];
    if (!file) return;
    cos.putObject({
        Bucket: 'examplebucket-1250000000',
        Region: 'ap-beijing',
        Key: '目标路径/' + file.name,
        Body: file,
    }, 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);
});