下载与安装
相关资源
- 对象存储服务的 XML JS SDK 资源 github 地址:XML Node.js SDK。
- SDK 快速下载地址:XML Node.js SDK。
- 演示示例 Demo 下载地址:XML Node.js SDK Demo。
- SDK 文档中的所有示例代码请参见 SDK 代码示例。
- SDK 更新日志请参见 ChangeLog。
说明:
如果您在使用 SDK 时遇到函数或方法不存在等错误,请先将 SDK 升级到最新版再重试。
环境依赖
- 使用 SDK 需要您的运行环境包含 nodejs 以及 npm,其中 nodejs 版本要求 ≥ 6。
- 登录 对象存储控制台 创建存储桶后,获取存储桶名称和 地域名称。
- 登录 访问管理控制台 获取您的项目 SecretId 和 SecretKey。
说明:
关于本文中出现的 SecretId、SecretKey、Bucket 等名称的含义和获取方式请参见 COS 术语信息。
安装 SDK
通过 npm 安装环境 SDK: npm 地址。
npm i cos-nodejs-sdk-v5 --save
开始使用
初始化
使用永久密钥初始化
请先在访问管理控制台中的 API 密钥管理 页面获取 SecretId、SecretKey。
将 SecretId、SecretKey、Bucket 和 Region 修改为您实际开发环境下的值,测试上传文件,请参考以下示例代码:
// SECRETID 和 SECRETKEY请登录 https://console.cloud.tencent.com/cam/capi 进行查看和管理
var COS = require('cos-nodejs-sdk-v5');
var cos = new COS({
SecretId: 'SECRETID',
SecretKey: 'SECRETKEY'
});
使用临时密钥初始化
临时密钥生成和使用请参见 临时密钥生成及使用指引。Node.js SDK 支持通过传入临时密钥进行初始化,请参考以下示例代码:
var request = require('request');
var COS = require('cos-nodejs-sdk-v5');
var cos = new COS({
getAuthorization: function (options, callback) {
// 异步获取临时密钥
request({
url: 'https://example.com/sts',
data: {
// 可从 options 取需要的参数
}
}, function (err, response, body) {
try {
var data = JSON.parse(body);
var credentials = data.credentials;
} catch(e) {}
if (!data || !credentials) return console.error('credentials invalid');
callback({
TmpSecretId: credentials.tmpSecretId, // 临时密钥的 tmpSecretId
TmpSecretKey: credentials.tmpSecretKey, // 临时密钥的 tmpSecretKey
SecurityToken: credentials.sessionToken, // 临时密钥的 sessionToken
ExpiredTime: data.expiredTime, // 临时密钥失效时间戳,是申请临时密钥时,时间戳加 durationSeconds
});
});
}
});
以下是部分常用接口例子,更详细的初始化方法请参见 demo 示例。
配置项
构造函数参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
---|---|---|---|
SecretId | 用户的 SecretId | String | 是 |
SecretKey | 用户的 SecretKey | String | 是 |
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 | 否 |
ServiceDomain | 调用 getService 方法时,请求的域名,例如service.cos.myqcloud.com |
String | 否 |
Domain | 调用操作存储桶和对象的 API 时自定义请求域名。可以使用模板, 例如 "{Bucket}.cos.{Region}.myqcloud.com" ,即在调用 API 时会使用参数中传入的 Bucket 和 Region 进行替换 |
String | 否 |
UploadQueueSize | 上传队列最长大小,超出队列大小并失败/已完成/已取消状态的任务会被清理,默认1000 | Number | 否 |
ForcePathStyle | 强制使用后缀式模式发请求。后缀式模式中 Bucket 会放在域名后的 pathname 里,并且 Bucket 会加入签名 pathname 计算,默认 false | Boolean | 否 |
UploadCheckContentMd5 | 强制上传文件也校验 Content-MD5,会对文件请求 Body 计算 md5 放在 header 的 Content-MD5 字段里,默认 false | Boolean | 否 |
Timeout | 超时时间,单位毫秒,默认为0,即不设置超时时间 | Number | 否 |
KeepAlive | 多个请求同用 TCP 连接,默认 true,若请求并发量大建议 打开 | Boolean | 否 |
StrictSsl | 严格校验 HTTPS 证书,默认 true | Boolean | 否 |
Proxy | 请求时使用 HTTP 代理,例如:http://127.0.0.1:8080 |
String | 否 |
getAuthorization | 获取签名的回调方法,如果没有 SecretId、SecretKey 时,这个参数必选 | Function | 否 |
UseAccelerate | 是否启用全球加速域名,默认为 false。若改为 true,需要存储桶开启全球加速功能,详情请参见 开启全球加速。 | Boolean | 否 |
getAuthorization 回调函数说明的函数说明(使用格式一)
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 回调函数说明(使用格式二)
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 | 否 |
获取鉴权凭证
实例本身鉴权凭证可以通过实例化时传入的参数控制如何或获取,有三种获取方式:
- 实例化时,传入 SecretId、SecretKey,每次需要签名都由实例内部计算。
- 实例化时,传入 getAuthorization 回调,每次需要签名通过这个回调计算完返回签名给实例。
- 实例化时,传入 getSTS 回调,每次需要临时密钥通过这个回调回去完返回给实例,在每次请求时实例内部使用临时密钥计算得到签名。
使用技巧
通常情况下我们只需要创建一个 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.putBucket({
Bucket: 'examplebucket-1250000000',
Region: 'COS_REGION'
}, function(err, data) {
console.log(err || data);
});
查询存储桶列表
cos.getService(function (err, data) {
console.log(data && data.Buckets);
});
上传对象
该接口适用于小文件上传,大文件请使用分块上传接口,详情请参见 对象操作 文档。
cos.putObject({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 必须 */
Key: 'exampleobject', /* 必须 */
StorageClass: 'STANDARD',
Body: fs.createReadStream('./exampleobject'), // 上传文件对象
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.getObject({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 必须 */
Key: 'exampleobject', /* 必须 */
Output: fs.createWriteStream('./exampleobject'),
}, function(err, data) {
console.log(err || data);
});
删除对象
cos.deleteObject({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 必须 */
Key: 'exampleobject' /* 必须 */
}, function(err, data) {
console.log(err || data);
});