产品动态
产品公告
*,ExposeHeaders 需要 ETag、Content-Length 以及其他 JS 需要读取的 header 字段,如下图所示。操作详情请参见 设置跨域访问 文档。
<!--src 为本地路径 根据自己项目目录结构来调整--><script src="../dist/cos-js-sdk-v5.min.js"></script>
npm i cos-js-sdk-v5 --save 安装 SDK 依赖,支持 Webpack 打包的场景,您可以用 npm 引入作为模块,代码如下:const COS = require('cos-js-sdk-v5');// 或import COS from 'cos-js-sdk-v5';
import COS from 'cos-js-sdk-v5';// console.log(COS.version); sdk 版本需要不低于 1.8.3const cos = new COS({SecretId: 'your_tmpSecretId', // sts服务下发的临时 secretIdSecretKey: 'your_tmpSecretKey', // sts服务下发的临时 secretKeySecurityToken: 'your_sessionToken', // sts服务下发的临时 SessionTokenStartTime: 1720770679403, // 建议传入服务端时间,可避免客户端时间不准导致的签名错误ExpiredTime: 1720771991367, // 临时密钥过期时间});
import COS from 'cos-js-sdk-v5';const cos = new COS({getAuthorization: async function (options, callback) {const data = await fetchSts('xxxx'); // 需自行实现获取临时密钥逻辑callback({TmpSecretId: data.credentials.tmpSecretId,TmpSecretKey: data.credentials.tmpSecretKey,SecurityToken: data.credentials.sessionToken,// 建议返回服务器时间作为签名的开始时间,避免客户端本地时间偏差过大导致签名错误StartTime: data.startTime, // 时间戳,单位秒,如:1580000000ExpiredTime: data.expiredTime, // 时间戳,单位秒,如:1580000000ScopeLimit: true, // 细粒度控制权限需要设为 true,会限制密钥只在相同请求时重复使用});}});
import COS from 'cos-js-sdk-v5';const cos = new COS({// 其他配置项可参考下方 初始化配置项// getAuthorization 必选参数getAuthorization: function (options, callback) {// 初始化时不会调用,只有调用 cos 方法(例如 cos.putObject)时才会进入// 异步获取临时密钥// 服务端 JS 示例:https://github.com/tencentyun/cos-js-sdk-v5/blob/master/server/// 服务端其他语言参考 COS STS SDK :https://github.com/tencentyun/qcloud-cos-sts-sdk// STS 详细文档指引看:https://www.tencentcloud.com/document/product/436/14048const stsUrl = 'http://example.com/server/sts'; // stsUrl 替换成您自己的后端服务fetch(stsUrl).then(response => response.json()).then(data => {if (!data || !data.credentials) {return console.error('credentials invalid:\\n' + JSON.stringify(data, null, 2))}// 检查credentials格式const { credentials } = data;console.log(credentials);callback({TmpSecretId: credentials.tmpSecretId,TmpSecretKey: credentials.tmpSecretKey,SecurityToken: credentials.sessionToken,// 建议返回服务器时间作为签名的开始时间,避免客户端本地时间偏差过大导致签名错误StartTime: data.startTime, // 时间戳,单位秒,如:1580000000ExpiredTime: data.expiredTime, // 时间戳,单位秒,如:1580000000ScopeLimit: true, // 细粒度控制权限需要设为 true,会限制密钥只在相同请求时重复使用});}).catch(error => {console.error('获取临时密钥失败', error);});}});export default cos;
import cos from 'utils/cos';let taskId;// 上传文件,file为选择的文件async function upload(file) {try {const data = await cos.uploadFile({Bucket: 'examplebucket-1250000000', // 填写自己的 bucket,必须字段Region: 'COS_REGION', // 存储桶所在地域,必须字段Key: '1.jpg', // 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段Body: file, // 上传文件对象SliceSize: 1024 * 1024 * 5, // 触发分块上传的阈值,超过5MB 使用分块上传,小于5MB使用简单上传。可自行设置,非必须onProgress: function(progressData) {console.log('上传进度:', progressData);},onTaskReady: function(id) { // 非必须taskId = id;},});console.log('上传成功', data);} catch (e) {console.error('上传失败', e);}}// 监听上传队列cos.on('update-list', data => {console.log(data);});// 暂停上传任务cos.pauseTask(taskId);// 重启上传任务cos.restartTask(taskId);// 取消上传任务cos.cancelTask(taskId)
import COS from 'cos-js-sdk-v5';// SECRETID 和 SECRETKEY 请登录 https://console.tencentcloud.com/cam/capi 进行查看和管理const cos = new COS({SecretId: process.env.SecretId, // 推荐使用环境变量获取;用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参考https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1SecretKey: process.env.SecretKey, // 推荐使用环境变量获取;用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参考https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1});
参数名 | 参数描述 | 类型 | 是否必填 |
SecretId | 用户的 SecretId,传永久密钥时建议只在前端调试时使用,避免暴露密钥。 | String | 否 |
SecretKey | 用户的 SecretKey,传永久密钥时建议只在前端调试时使用,避免暴露密钥。 | String | 否 |
SecurityToken | 获取回来的临时密钥的 sessionToken(v1.8.3 版本开始支持)。当 SecretId、SecretKey 传入临时密钥时,SecurityToken 必填。 | String | 否 |
StartTime | 获取回来的临时密钥的有效起始时间戳(v1.8.3 版本开始支持),单位:秒。当 SecretId、SecretKey 传入临时密钥时,建议传入 StartTime。 | Number | 否 |
ExpiredTime | 获取回来的临时密钥的有效过期时间戳(v1.8.3 版本开始支持),单位:秒。当 SecretId、SecretKey 传入临时密钥时,建议传入 ExpiredTime。 | Number | 否 |
FileParallelLimit | 同一个实例下上传的文件并发数,默认值3。 | Number | 否 |
ChunkParallelLimit | 同一个上传文件的分块并发数,默认值3。 | Number | 否 |
ChunkRetryTimes | 分块上传及分块复制时,出错重试次数,默认值2(加第一次,请求共3次)。 | Number | 否 |
ChunkSize | 分块上传时,每片的字节数大小,默认值1048576(1MB)。 | Number | 否 |
SliceSize | 使用 uploadFiles 批量上传时,文件大小大于该数值将使用分块上传,否则将调用简单上传,单位 Byte,默认值1048576(1MB)。 | Number | 否 |
CopyChunkParallelLimit | 进行分块复制操作中复制分块上传的并发数,默认值20。 | Number | 否 |
CopyChunkSize | 使用 sliceCopyFile 分块复制文件时,每片的大小字节数,默认值10485760(10MB)。 | Number | 否 |
CopySliceSize | 使用 sliceCopyFile 分块复制文件时,文件大小大于该数值将使用分块复制 ,否则将调用简单复制,默认值10485760(10MB)。 | Number | 否 |
ProgressInterval | 上传进度的回调方法 onProgress 的回调频率,单位 ms ,默认值1000。 | Number | 否 |
Protocol | 发请求时用的协议,可选项 https:、http:,默认判断当前页面是 http: 时使用 http:,否则使用 https:。 | String | 否 |
Domain | 调用操作存储桶和对象的 API 时自定义请求域名。可以使用模板,如 "{Bucket}.cos.{Region}.myqcloud.com" ,即在调用 API 时会使用参数中传入的 Bucket 和 Region 进行替换。 | String | 否 |
UploadQueueSize | 上传队列最长大小,超出的任务如果状态不是 waiting、checking、uploading 会被清理,默认10000。 | Number | 否 |
UploadCheckContentMd5 | 上传文件时校验 Content-MD5,默认 false。如果开启,上传文件时会对文件内容计算 MD5,大文件耗时较长。 | Boolean | 否 |
UploadAddMetaMd5 | 上传文件时校验 Content-MD5,默认 false。开启后上传请求头里会新增 x-cos-meta-md5。 | Boolean | 否 |
getAuthorization | 获取签名的回调方法,如果没有 SecretId、SecretKey 时,这个参数必选。 注意: 该回调方法在初始化实例时传入,在使用实例调用接口时才会执行并获取签名。 | Function | 否 |
Timeout | 超时时间,单位毫秒,默认为0,即不设置超时时间。 | Number | 否 |
UseAccelerate | Boolean | 否 |
getAuthorization: function(options, callback) { ... }
参数名 | 参数描述 | 类型 |
options | 获取临时密钥需要的参数对象 | Object |
- Bucket | 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 | String |
- Region | String | |
callback | 临时密钥获取完成后的回传方法 | Function |
属性名 | 参数描述 | 类型 | 是否必填 |
TmpSecretId | 获取回来的临时密钥的 tmpSecretId | String | 是 |
TmpSecretKey | 获取回来的临时密钥的 tmpSecretKey | String | 是 |
SecurityToken | 获取回来的临时密钥的 sessionToken,对应 header 的 x-cos-security-token 字段 | String | 是 |
StartTime | 密钥获取的开始时间,即获取时刻的时间戳,单位秒,startTime,如:1580000000,用于签名的开始时间,传入该参数可避免前端时间偏差签名过期问题 | String | 否 |
ExpiredTime | 获取回来的临时密钥的 expiredTime,超时时刻的时间戳,单位秒,如:1580000900 | String | 是 |
// 完整demo可参考:https://github.com/tencentyun/cos-js-sdk-v5/blob/master/demo/index.htmlconst Beacon = require('./lib/beacon_mp.min');new COS({...BeaconReporter: Beacon,})
// 这里省略初始化过程和上传参数var cos = new COS({ ... });cos.uploadFile({ ... }, function(err, data) {if (err) {console.log('上传出错', err);} else {console.log('上传成功', data);}});
// 这里省略初始化过程和上传参数var cos = new COS({ ... });cos.uploadFile({ ... }).then(data => {console.log('上传成功', data);}).catch(err => {console.log('上传出错', err);});
async function upload() {// 这里省略初始化过程和上传参数var cos = new COS({ ... });try {var data = await cos.uploadFile({ ... });return { err: null, data: data }} catch (err) {return { err: err, data: null };}}// 可以同步拿到请求的返回值,这里举例说明,实际返回的数据格式可以自定义var uploadResult = await upload();if (uploadResult.err) {console.log('上传出错', uploadResult.err);} else {console.log('上传成功', uploadResult.data);}// JavaScript 的 async 和 await(使用时请注意浏览器兼容性)
/* vue 项目举例 *//* 新建一个 cos.js,导出 cos 实例 */import COS from 'cos-js-sdk-v5'; // 通过 npm 安装的 SDKconst cos = new COS({SecretId: '您的 SecretId',SecretKey: '您的 SecretKey',});export default cos;/* 单页面里 page.vue */<template><div><button @click="getBucketFiles">查询目录a下的文件</button><div v-if="fileList.length"><h4>目录a下的文件列表:</h4><ul><li v-for="(file, i) in fileList" :key="i">{{ file.Key }}</li></ul></div><p v-if="error" style="color: red;">{{ error }}</p></div></template><script>import cos from '@/utils/cos';export default {data() {return {fileList: [],error: ''};},methods: {getBucketFiles() {cos.getBucket({Bucket: 'examplebucket-1250000000', // 您的bucketRegion: 'COS_REGION', // 您的地域(如ap-guangzhou)Prefix: 'a/' // 只查a目录下的文件}, (err, data) => {if (err) {this.error = '查询失败:' + err.Message;this.fileList = [];} else {this.error = '';this.fileList = data.Contents || []; // 展示文件路径(Key)}});}}};</script>
<template><div><input type="file" @change="handleUpload" /></div></template><script>// 直接引入cos-js-sdk-v5(npm 安装)import COS from 'cos-js-sdk-v5';export default {methods: {handleUpload(e) {const file = e.target.files[0];if (!file) return;// 直接在组件内初始化 COS 实例const cos = new COS({SecretId: '您的 SecretId', // 替换实际 SecretIdSecretKey: '您的 SecretKey' // 替换实际 SecretKey});// 调用上传方法cos.uploadFile({Bucket: 'examplebucket-1250000000',Region: 'ap-guangzhou',Key: `upload/${Date.now()}-${file.name}`,Body: file,SliceSize: 1024 * 1024 * 5}, (err, data) => {err ? console.error('上传失败', err) : console.log('上传成功', data);e.target.value = ''; // 清空选择});}}};</script>
<template><div><input type="text" v-model="fileKey" placeholder="输入文件Key(如a/1.jpg)" /><button @click="getDownloadUrl">下载</button></div></template><script>import COS from 'cos-js-sdk-v5';export default {data() {return {fileKey: '',cos: new COS({SecretId: '您的 SecretId',SecretKey: '您的 SecretKey'})};},methods: {getDownloadUrl() {if (!this.fileKey) return;this.cos.getObjectUrl({Bucket: 'examplebucket-1250000000',Region: 'COS_REGION',Key: this.fileKey}, (err, data) => {if (err) return console.error(err);// 构建强制下载链接const downloadUrl = data.Url + (data.Url.includes('?') ? '&' : '?') + 'response-content-disposition=attachment';window.open(downloadUrl);});}}};</script>
<template><div><input type="text" v-model="fileKey" placeholder="输入要删除的文件Key(如a/1.jpg)" /><button @click="deleteFile">删除文件</button></div></template><script>import COS from 'cos-js-sdk-v5';export default {data() {return {fileKey: '',cos: new COS({SecretId: '您的 SecretId',SecretKey: '您的 SecretKey'})};},methods: {deleteFile() {if (!this.fileKey.trim()) return;this.cos.deleteObject({Bucket: 'examplebucket-1250000000',Region: 'COS_REGION',Key: this.fileKey.trim()}, (err, data) => {if (err) {console.error('删除失败', err);} else {console.log('删除成功', data);this.fileKey = ''; // 清空输入}});}}};</script>
文档反馈