@pagoda-tools/cos

针对腾讯 COS JS SDK cos-js-sdk-v5，二次封装工具。

安装

yarn add @pagoda-tools/cos

初始化

Note:

参数 cosOptions: 查看 cos 初始化

//
import { PagodaCos } from '@pagoda-tools/cos';
const cosOptions = {
  // ...
};
const pdOptions = {
  // ...
};

const pagodaCos = new PagodaCOS({
  getConfig() {
    // 调用接口获取相关配置信息
    return Promise.resolve({
      region: 'ap-guangzhou',
      bucket: 'instance-xxxx',
      prefix: 'a1',
    });
  },
  getAuthorization() {
    // 调用接口获取 token 相关鉴权信息
    return Promise.resolve({
      startTime: 1633764822, // 该参数会影响，getObjectUrl Ex
      expiredTime: 1633766622,
      credentials: {
        tmpSecretId: 'xxxxx',
        tmpSecretKey: 'xxxxx',
        sessionToken: 'xxxx',
        ScopeLimit: true,
      },
    });
  },
  cosOptions,
  pdOptions,
});

构造函数参数说明

参数名	参数描述	类型	是否必填
getConfig	获取存储桶配置的回调方法	Function	是
getAuthorization	获取签名的回调方法，如果没有`SecretId`、`SecretKey` 时，这个参数必选。注意: 该回调方法在初始化实例时传入，在使用实例调用接口时才会执行并获取签名。,可参考	Function	是
cosOptions	腾讯 COS 构造函数参数	Object	否
pdOptions	PagodaCos 扩展参数	Object	否
- pdFileHash	是否对`path`做`hash`处理，作用：防止新上传文件覆盖原上传文件，默认`false`；注意: 在各个上传函数方法中，params.pdFileHash，会独立控制，不与该实例参数的限制。	boolean	否
- pdCarryFileName	计算 hash 时，是否携带文件名，默认`false`	boolean	否
- pdSimplifyHash	是否简化`hash`值，默认`false`。注意: 简化`hash`既只有 5 位哈希值，最好配合传值`path`添加时间，如：`a1/test/${dayjs().format('YYYYMMDDHHmmss')}/测试文件.[hash].txt`。	boolean	否
- pdBeforeExpirationTime	设置过期时间之前判断过期（秒），默认 120 秒，单位：秒	number	否

开启pdFileHash情况下，传入path的：

默认生成Key格式：test/111.txt ==> ${prefix}/test/[hash].txt

pdCarryFileName: true时，生成Key格式，如：test/111.txt ==> ${prefix}/test/111.[hash].txt

如果pdSimplifyHash: false的情况下，原有的hash值，由2a97bec793b2838b6ef8a0652e3fabf4 ==> 1554c，及原长hash简化至 5 位哈希值。

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

getAuthorization: function(options) { ... }

getAuthorization 的回调参数说明：

参考腾讯 COS 构造函数参数中 getAuthorization 说明。

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

属性名	参数描述	类型	是否必填
credentials	获取证书数据	Object	是
- tmpSecretId	获取回来的临时密钥的 tmpSecretId	String	是
- tmpSecretKey	获取回来的临时密钥的 tmpSecretKey	String	是
- securityToken	获取回来的临时密钥的 sessionToken，对应 header 的 x-cos-security-token 字段	String	是
startTime	密钥获取的开始时间，即获取时刻的时间戳，单位秒，startTime，如：1580000000，用于签名开始时间，传入该参数可避免前端时间偏差签名过期问题	String	否
expiredTime	获取回来的临时密钥的 expiredTime，超时时刻的时间戳，单位秒，如：1580000900	String	是

案例

简单上传文件，适用于小文件上传：建议使用 uploadFile 或 sliceUploadFile 上传

const { Key, Location } = await pagodaCos
  .putObject('test/test1.txt', file, {
    pdFileHash: true,
    onProgress: function (progressData) {
      console.log(JSON.stringify(progressData));
    },
  })
  .catch((err) => {
    console.log(err);
  });
console.log(Key, Location);
/**
 * {
      Key: 'a1/test/test.1554c.txt',
      statusCode: 200,
      headers: {
        'content-length': '0',
        etag: '"2a97bec793b2838b6ef8a0652e3fabf4"',
        'x-cos-request-id': 'NjIxODgxMjhfYTkxMzc2MGJfZjVkMl9hZGQzMzNh'
      },
      Location: 'instance-xxxx.cos.ap-guangzhou.myqcloud.com/a1/test/test.1554c.txt',
      ETag: '"2a97bec793b2838b6ef8a0652e3fabf4"',
      RequestId: 'NjIxODgxMjhfYTkxMzc2MGJfZjVkMl9hZGQzMzNh'
    }
 */

pagodaCos API

实例方法

以下是可用的实例方法。指定的配置将与实例的配置合并。

Note: params参数中大部分参数是继承至腾讯 COS 实例方法中的参数，详细参数请前往腾讯 COS - 上传对象

上传对象

pagodaCos.putObject(path, file, params); // 简单上传
pagodaCos.sliceUploadFile(path, file, params); // 分片上传
pagodaCos.uploadFile(path, file, params); // (推荐) 单文件上传高级接口，会根据SliceSize参数，择优使用 `putObject` 或 'sliceUploadFile' 上传

请求参数

属性名	参数描述	类型	是否必填
path	储存到的子目录	string	是
file	上传的文件	File、Blob、String、ArrayBuffer	是
params	...	Object	否
- pdFileHash	同`初始实例方法`参数一致	Boolean	否
- ...其它	其它参数，前往腾讯 COS 文档，查看实例方法参数说明	any	否

响应参数（基本一致）

{
  "Key": "a1/test/test.1554c.txt",
  "statusCode": 200,
  "headers": {
    "content-length": "0",
    "etag": "\"2a97bec793b2838b6ef8a0652e3fabf4\"",
    "x-cos-request-id": "NjIxODgxMjhfYTkxMzc2MGJfZjVkMl9hZGQzMzNh"
  },
  "Location": "instance-xxxx.cos.ap-guangzhou.myqcloud.com/a1/test/test.1554c.txt",
  "ETag": "\"2a97bec793b2838b6ef8a0652e3fabf4\"",
  "RequestId": "NjIxODgxMjhfYTkxMzc2MGJfZjVkMl9hZGQzMzNh"
}

pagodaCos.uploadFiles(files[, params])

请求参数

属性名	参数描述	类型	是否必填
files	多文件配置	Array	是
- path	同上`上传对象`参数一致	String	是
- file	同上`上传对象`参数一致	File、Blob、String、ArrayBuffer	是
- pdFileHash	同上`上传对象`参数一致	Boolean	否
params	同上`上传对象`参数一致	Object	否

响应参数

{
  "files": [
    {
      "options": {
        "Index": "0",
        "TaskId": "66dc56d8-fbd7-15ca-3611-f541f1c214b2",
        "Bucket": "instance-xxxx",
        "Region": "ap-guangzhou",
        "Key": "a1/test/test.edf95.txt",
        "SliceSize": 5242880
      },
      "error": null,
      "data": {
        "statusCode": 200,
        "headers": {
          "content-length": "0",
          "etag": "\"2a97bec793b2838b6ef8a0652e3fabf4\"",
          "x-cos-request-id": "NjIxODhlNGNfNzMwMmMwYl8yMzNlZF9iYWYxMTUz"
        },
        "Location": "instance-xxxx.cos.ap-guangzhou.myqcloud.com/a1/test/test.edf95.txt",
        "ETag": "\"2a97bec793b2838b6ef8a0652e3fabf4\""
      }
    },
    {
      "options": {
        "Index": "1",
        "TaskId": "cbebb248-8903-9fde-aecf-992423e4edf2",
        "Bucket": "instance-xxxx",
        "Region": "ap-guangzhou",
        "Key": "a1/test/tes1.txt",
        "SliceSize": 5242880
      },
      "error": null,
      "data": {
        "statusCode": 200,
        "headers": {
          "content-length": "0",
          "etag": "\"2a97bec793b2838b6ef8a0652e3fabf4\"",
          "x-cos-request-id": "NjIxODhlNGNfZWIxNDZiMGJfN2FhY19hYmQ2YWQ1"
        },
        "Location": "instance-xxxx.cos.ap-guangzhou.myqcloud.com/a1/test/tes1.txt",
        "ETag": "\"2a97bec793b2838b6ef8a0652e3fabf4\""
      }
    },
    {
      "options": {
        "Index": "2",
        "TaskId": "a57a5591-7233-3d3f-2670-9285d4e8d6cf",
        "Bucket": "instance-xxxx",
        "Region": "ap-guangzhou",
        "Key": "a1/test/test2.ed095.txt",
        "SliceSize": 5242880
      },
      "error": null,
      "data": {
        "statusCode": 200,
        "headers": {
          "content-length": "0",
          "etag": "\"2a97bec793b2838b6ef8a0652e3fabf4\"",
          "x-cos-request-id": "NjIxODhlNGNfNzgxMzc2MGJfMTk0M2VfYWE0N2IzNA=="
        },
        "Location": "instance-xxxx.cos.ap-guangzhou.myqcloud.com/a1/test/test2.ed095.txt",
        "ETag": "\"2a97bec793b2838b6ef8a0652e3fabf4\""
      }
    }
  ]
}

读取对象内容

方法：pagodaCos.getObjectUrl(path, params);

请求参数

属性名	参数描述	类型	是否必填
path	要下载的的文件子路径	string	是
params	...	Object	否
- pdVerify	如果 path 传值为带域名的链接，会验证是否符合配置域名	boolean	否
- ...其它	其它参数，前往腾讯 COS - 对象访问 URL ，查看参数说明	any	否

// 支持3种path传值
const { Url } = await pagodaCos.getObjectUrl('test/test.txt'); // 兼容`1.0.8`以前的版本

const { Url } = await pagodaCos.getObjectUrl({
  Key: '${prefix}/test/test.txt',
});
const { Url } = await pagodaCos.getObjectUrl(
  'https?://{host}/${prefix}/test/test.txt'
);

COS 生成的Location为https?://${Bucket}.cos.${Region}.myqcloud.com/${Key}

Note: 生成预签名链接 ,请查看链接。

响应参数

{
  "Url": "http://instance-xxxx.cos.ap-guangzhou.myqcloud.com/a1/test/test.txt?q-sign-algorithm=sha1&q-ak=AKIDJxTmcTjw3a-HNNj8_BsIjO2JmowK4JBik0QRwCG0HjmAkzuFkIYGcwGJAVWf_d2x&q-sign-time=1645778968;1645780768&q-key-time=1645778968;1645780768&q-header-list=host&q-url-param-list=&q-signature=c3f0ccdf6d678555236be8d5a2d616126bf1485e&x-cos-security-token=2BQX5UTmbr290Q5AlL2suCT25rIuZoIa8b08c3fb51d1ac9660c53c3d04f2b415zUOAXO6K7fHi8SmXqzEOIYhtH8-KLkmITS7M8hWBVkPFGlF43vfbnrZO-OeJCYiIPycs_ZQuescVgejpOsMMSBcig6LTc58GgxMHj3-H9PfcQF2pG0A5TNRKLreqWuctXeBbddp677P8_qeuE6297rgV--W6JiWUgOoqt7CquxQwojlBhOyD_OIrgzXF3Ww0F3jACeEFnwEM4RXgR7ChQc5HmV4FQ_qcx25APN6ofOsLz91Eg1qxrND3WCZoxF_My8VOM-_EEm9XozEkn3TXXVO3YqRrilXb5A26cJHyKYw"
}

解析 COS`Location`方法：`urlParse`

方法：pagodaCos.urlParse(url);

请求参数

属性名	参数描述	类型	是否必填
url	要解析的链接，如：`https?://${Location}`	string	是

响应参数

// instance-xxxxx.cos.ap-guangzhou.myqcloud.com:8000/a1/test/picture.png
// ==>
{
  host: 'instance-xxxxx.cos.ap-guangzhou.myqcloud.com',
  key: 'a1/test/picture.png',
  prefix: 'a1',
  bucket: 'instance-xxxxx',
  region: 'ap-guangzhou',
  protocol: 'https',
  parseData: {
    preventInvalidHostname: false,
    query: '',
    protocol: 'https',
    username: null,
    password: null,
    hostname: 'instance-xxxxx.cos.ap-guangzhou.myqcloud.com',
    port: '',
    path: '/a1/test/picture.png',
  },
}

url 为*.myqcloud.com域名时，可不要携带protocol头

获取配置 API

pagodaCos.getConfig()

响应参数

{
  "region": "ap-guangzhou",
  "bucket": "instance-xxxx",
  "prefix": "a1"
}

pagodaCos.getUploadFileConfig({path, file, params, type})

请求参数

属性名	参数描述	类型	是否必填
type	返回参数类型	'putObject'、'sliceUploadFile'、'uploadFile'、'uploadFiles'、'config'	否
path	文件路径	String	否
file	文件	File、Blob、String、ArrayBuffer	否
params	同上`上传对象`参数一致	Object	否
- pdFileHash	同上`上传对象`参数一致	Boolean	否
- ...其它	需要合并的参数	any	否

返回参数

{
  "Bucket": "instance-xxxx",
  "Region": "ap-guangzhou",
  "Prefix": "a1",
  "StorageClass": "STANDARD",
  "Body": "File {}"
  // ...
}

腾讯 COS 其它 API 调用示例

const { Bucket, Region, Prefix } = await pagodaCos.getUploadFileConfig({
  type: 'config',
});

const result = await pagodaCos.cos.getBucket({
  Bucket,
  Region,
  Prefix: `${Prefix}/test`,
});

@pagoda-tools/cos

@pagoda-tools/cos

安装

初始化

构造函数参数说明

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

getAuthorization 的回调参数说明：

案例

pagodaCos API

实例方法

上传对象

pagodaCos.uploadFiles(files[, params])

读取对象内容

解析 COS`Location`方法：`urlParse`

响应参数

获取配置 API

腾讯 COS 其它 API 调用示例

Readme

Keywords

Package Sidebar

Install

Repository

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@pagoda-tools/cos

@pagoda-tools/cos

安装

初始化

构造函数参数说明

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

getAuthorization 的回调参数说明：

案例

pagodaCos API

实例方法

上传对象

pagodaCos.uploadFiles(files[, params])

读取对象内容

解析 COSLocation方法：urlParse

响应参数

获取配置 API

腾讯 COS 其它 API 调用示例

Readme

Keywords

Package Sidebar

Install

Repository

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

解析 COS`Location`方法：`urlParse`

Weekly Downloads