说明:如果您在使用 XML 版本 SDK 时遇到函数或方法不存在等错误,请先将 XML 版本 SDK 升级到最新版再重试。
*
,ExposeHeaders 需要 ETag、Content-Length 以及其他 js 需要读取的 header 字段,如下图所示。操作详情请参见 设置跨域访问 文档。说明:
- 关于本文中出现的 SecretId、SecretKey、Bucket 等名称的含义和获取方式请参见 COS 术语信息。
- 关于跨端框架(例如 uni-app)的使用说明,使用 JavaScript SDK 开发后无法打包成正常使用的移动应用,例如安卓 App、iOS App,需要使用对应的安卓 SDK、iOS SDK。
您可以通过以下方式安装 SDK:
说明:单击此处 下载最新 cos-js-sdk-v5.min.js。
<script src="https://cdn.jsdelivr.net/npm/cos-js-sdk-v5/dist/cos-js-sdk-v5.min.js"></script>
在 script 标签引用 SDK 时,SDK 占用了全局变量名 COS,通过它的构造函数可以创建 SDK 实例。
通过npm i cos-js-sdk-v5 --save
安装 SDK 依赖,支持 webpack 打包的场景,您可以用 npm 引入作为模块,代码如下:
var COS = require('cos-js-sdk-v5');
由于固定密钥放在前端会有安全风险,正式部署时我们推荐使用临时密钥的方式,实现过程为:前端首先请求服务端,服务端使用固定密钥调用 STS 服务申请临时密钥(具体内容请参见 临时密钥生成和使用指引 文档),然后返回临时密钥到前端使用。
注意:如果站点有登录态,这个获取临时密钥接口,还需要加上登录态校验。
<input id="file-selector" type="file">
<script src="dist/cos-js-sdk-v5.min.js"></script>
<script>
// 存储桶名称,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
var Bucket = 'examplebucket-1250000000'; /* 存储桶,必须字段 */
// 存储桶region可以在COS控制台指定存储桶的概览页查看 https://console.cloud.tencent.com/cos5/bucket/
// 关于地域的详情见 https://intl.cloud.tencent.com/document/product/436/6224
var Region = 'COS_REGION'; /* 存储桶所在地域,必须字段 */
// 初始化实例
var cos = new COS({
// getAuthorization 必选参数
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://intl.cloud.tencent.com/document/product/436/14048
var url = 'http://example.com/server/sts.php'; // url替换成您自己的后端服务
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.onload = function (e) {
try {
var data = JSON.parse(e.target.responseText);
var credentials = data.credentials;
} catch (e) {
}
if (!data || !credentials) {
return console.error('credentials invalid:\n' + JSON.stringify(data, null, 2))
};
callback({
TmpSecretId: credentials.tmpSecretId,
TmpSecretKey: credentials.tmpSecretKey,
SecurityToken: credentials.sessionToken,
// 建议返回服务器时间作为签名的开始时间,避免用户浏览器本地时间偏差过大导致签名错误
StartTime: data.startTime, // 时间戳,单位秒,如:1580000000
ExpiredTime: data.expiredTime, // 时间戳,单位秒,如:1580000000
});
};
xhr.send();
}
});
// 接下来可以通过 cos 实例调用 COS 请求。
</script>
创建一个 COS SDK 实例,COS SDK 支持以下格式创建:
var COS = require('cos-js-sdk-v5');
var cos = new COS({
// getAuthorization 必选参数
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://intl.cloud.tencent.com/document/product/436/14048
var url = 'http://example.com/server/sts.php'; // url替换成您自己的后端服务
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.onload = function (e) {
try {
var data = JSON.parse(e.target.responseText);
var credentials = data.credentials;
} catch (e) {
}
if (!data || !credentials) {
return console.error('credentials invalid:\n' + JSON.stringify(data, null, 2))
};
callback({
TmpSecretId: credentials.tmpSecretId,
TmpSecretKey: credentials.tmpSecretKey,
SecurityToken: credentials.sessionToken,
// 建议返回服务器时间作为签名的开始时间,避免用户浏览器本地时间偏差过大导致签名错误
StartTime: data.startTime, // 时间戳,单位秒,如:1580000000
ExpiredTime: data.expiredTime, // 时间戳,单位秒,如:1580000000
});
};
xhr.send();
}
});
var COS = require('cos-js-sdk-v5');
var cos = new COS({
// getAuthorization 必选参数
getAuthorization: function (options, callback) {
// 服务端例子:https://github.com/tencentyun/qcloud-cos-sts-sdk/blob/master/scope.md
// 异步获取临时密钥
var url = 'http://example.com/server/sts.php'; // url替换成您自己的后端服务
var xhr = new XMLHttpRequest();
xhr.open('POST', url, true);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onload = function (e) {
try {
var data = JSON.parse(e.target.responseText);
var credentials = data.credentials;
} catch (e) {
}
if (!data || !credentials) {
return console.error('credentials invalid:\n' + JSON.stringify(data, null, 2))
};
callback({
TmpSecretId: credentials.tmpSecretId,
TmpSecretKey: credentials.tmpSecretKey,
SecurityToken: credentials.sessionToken,
// 建议返回服务器时间作为签名的开始时间,避免用户浏览器本地时间偏差过大导致签名错误
StartTime: data.startTime, // 时间戳,单位秒,如:1580000000
ExpiredTime: data.expiredTime, // 时间戳,单位秒,如:1580000000
ScopeLimit: true, // 细粒度控制权限需要设为 true,会限制密钥只在相同请求时重复使用
});
};
xhr.send(JSON.stringify(options.Scope));
}
});
var COS = require('cos-js-sdk-v5');
var cos = new COS({
// getAuthorization 必选参数
getAuthorization: function (options, callback) {
// 异步获取签名
var url = 'http://example.com/server/sts.php'; // url替换成您自己的后端服务
var method = (options.Method || 'get').toLowerCase();
var query = options.Query || {};
var headers = options.Headers || {};
var pathname = options.Pathname || '/';
var xhr = new XMLHttpRequest();
var data = {
method: method,
pathname: pathname,
query: query,
headers: headers,
};
xhr.open('POST', url, true);
xhr.setRequestHeader('content-type', 'application/json');
xhr.onload = function (e) {
try {
var data = JSON.parse(e.target.responseText);
} catch (e) {
}
if (!data || !data.authorization) return console.error('authorization invalid');
callback({
Authorization: data.authorization,
// SecurityToken: data.sessionToken, // 如果使用临时密钥,需要把 sessionToken 传给 SecurityToken
});
};
xhr.send(JSON.stringify(data));
},
});
var COS = require('cos-js-sdk-v5');
// SECRETID 和 SECRETKEY请登录 https://console.cloud.tencent.com/cam/capi 进行查看和管理
var cos = new COS({
SecretId: 'SECRETID',
SecretKey: 'SECRETKEY',
});
参数名 | 参数描述 | 类型 | 是否必填 |
---|---|---|---|
SecretId | 用户的 SecretId | String | 否 |
SecretKey | 用户的 SecretKey,建议只在前端调试时使用,避免暴露密钥 | String | 否 |
FileParallelLimit | 同一个实例下上传的文件并发数,默认值3 | Number | 否 |
ChunkParallelLimit | 同一个上传文件的分块并发数,默认值3 | Number | 否 |
ChunkRetryTimes | 分块上传及分块复制时,出错重试次数,默认值3(加第一次,请求共4次) | 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 | 否 |
ForcePathStyle | 强制使用后缀式模式发请求。后缀式模式中 Bucket 会放在域名后的 pathname 里,并且 Bucket 会加入签名 pathname 计算,默认 false | Boolean | 否 |
UploadCheckContentMd5 | 上传文件时校验 Content-MD5,默认 false。如果开启,上传文件时会对文件内容计算 MD5,大文件耗时较长 | Boolean | 否 |
getAuthorization | 获取签名的回调方法,如果没有 SecretId、SecretKey 时,这个参数必选。 注意: 该回调方法在初始化实例时传入,在使用实例调用接口时才会执行并获取签名。 |
Function | 否 |
Timeout | 超时时间,单位毫秒,默认为0,即不设置超时时间 | Number | 否 |
UseAccelerate | 是否启用全球加速域名,默认为 false。若改为 true,需要存储桶开启全球加速功能,详情请参见 开启全球加速。 | Boolean | 否 |
getAuthorization: function(options, callback) { ... }
getAuthorization 的回调参数说明:
参数名 | 参数描述 | 类型 |
---|---|---|
options | 获取临时密钥需要的参数对象 | Object |
- Bucket | 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 | String |
- Region | 存储桶所在地域,枚举值请参见 存储桶地域信息 | String |
callback | 临时密钥获取完成后的回传方法 | Function |
获取完临时密钥后,callback 回传一个对象,回传对象的属性列表如下:
属性名 | 参数描述 | 类型 | 是否必填 |
---|---|---|---|
TmpSecretId | 获取回来的临时密钥的 tmpSecretId | String | 是 |
TmpSecretKey | 获取回来的临时密钥的 tmpSecretKey | String | 是 |
SecurityToken | 获取回来的临时密钥的 sessionToken,对应 header 的 x-cos-security-token 字段 | String | 是 |
StartTime | 密钥获取的开始时间,即获取时刻的时间戳,单位秒,startTime,如:1580000000,用于签名开始时间,传入该参数可避免前端时间偏差签名过期问题 | String | 否 |
ExpiredTime | 获取回来的临时密钥的 expiredTime,超时时刻的时间戳,单位秒,如:1580000900 | String | 是 |
getAuthorization: function(options, callback) { ... }
getAuthorization 的函数说明回调参数说明:
参数名 | 参数描述 | 类型 |
---|---|---|
options | 获取签名需要的参数对象 | Object |
- Method | 当前请求的 Method | String |
- Pathname | 请求路径,用于签名计算 | String |
- Key | 对象键(Object 的名称),对象在存储桶中的唯一标识,了解更多可参见 对象概述。 注意:当使用实例请求的接口不是对象操作相关接口时,该参数为空。 |
String |
- Query | 当前请求的 query 参数对象,{key: 'val'} 的格式 | Object |
- Headers | 当前请求的 header 参数对象,{key: 'val'} 的格式 | Object |
callback | 临时密钥获取完成后的回调 | Function |
getAuthorization 计算完成后,callback 回传参数支持两种格式:
格式一:回传鉴权凭证字符串 Authorization。
格式二:回传一个对象,对象属性列表如下:
属性名 | 参数描述 | 类型 | 是否必填 |
---|---|---|---|
Authorization | 计算得到的签名字符串 | String | 是 |
SecurityToken | 获取回来的临时密钥的 sessionToken,对应 header 的 x-cos-security-token 字段 | String | 否 |
实例本身鉴权凭证可以通过实例化时传入的参数控制如何或获取,有三种获取方式:
通常情况下我们只需要创建一个 COS SDK 实例,然后在需要调用SDK方法的地方直接使用这个实例即可,示例代码如下:
var cos = new COS({
....
});
/* 自己封装的上传方法 */
function myUpload() {
// 不需要在每个方法里创建一个 COS SDK 实例
// var cos = new COS({
// ...
// });
cos.putObject({
....
});
}
/* 自己封装的删除方法 */
function myDelete() {
// 不需要在每个方法里创建一个 COS SDK 实例
// var cos = new COS({
// ...
// });
cos.deleteObject({
....
});
}
以下是部分常用接口例子,更详细的初始化方法请参见 demo 示例。
简单上传接口适用于小文件上传,大文件请使用分块上传接口,详情请参见 对象操作 文档。
cos.putObject({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 存储桶所在地域,必须字段 */
Key: 'exampleobject', /* 必须 */
StorageClass: 'STANDARD',
Body: fileObject, // 上传文件对象
onProgress: function(progressData) {
console.log(JSON.stringify(progressData));
}
}, function(err, data) {
console.log(err || data);
});
cos.getBucket({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 存储桶所在地域,必须字段 */
Prefix: 'a/', /* 非必须 */
}, function(err, data) {
console.log(err || data.Contents);
});
注意:该接口用于读取对象内容,如果需要发起浏览器下载文件,可以通过 cos.getObjectUrl 获取 url 再触发浏览器下载,具体请参见 预签名 URL 文档。
cos.getObject({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 存储桶所在地域,必须字段 */
Key: 'exampleobject', /* 必须 */
}, function(err, data) {
console.log(err || data.Body);
});
cos.deleteObject({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 存储桶所在地域,必须字段 */
Key: 'exampleobject' /* 必须 */
}, function(err, data) {
console.log(err || data);
});
本页内容是否解决了您的问题?