针对腾讯 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: function(options) { ... }
参考腾讯 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'
}
*/
以下是可用的实例方法。指定的配置将与实例的配置合并。
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"
}
请求参数
属性名 | 参数描述 | 类型 | 是否必填 |
---|---|---|---|
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"
}
方法: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
头
- 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 {}"
// ...
}
const { Bucket, Region, Prefix } = await pagodaCos.getUploadFileConfig({
type: 'config',
});
const result = await pagodaCos.cos.getBucket({
Bucket,
Region,
Prefix: `${Prefix}/test`,
});