快速入门

下载与安装

相关资源

• 对象存储服务的 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 升级到最新版再重试。

环境依赖

1. 使用 SDK 需要您的运行环境包含 nodejs 以及 npm，其中 nodejs 版本要求 ≥ 6。
2. 登录 对象存储控制台 创建存储桶后，获取存储桶名称和 地域名称。
3. 登录 访问管理控制台 获取您的项目 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 示例。

配置项

构造函数参数说明

getAuthorization 回调函数说明的函数说明（使用格式一）

getAuthorization: function(options, callback) { ... }

getAuthorization 的函数说明：

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

getAuthorization 回调函数说明（使用格式二）

getAuthorization: function(options, callback) { ... }

getAuthorization 的函数说明：

getAuthorization 计算完成后，callback 回传参数支持两种格式：
格式一：回传鉴权凭证字符串 Authorization。
格式二：回传一个对象，对象属性列表如下：

获取鉴权凭证

实例本身鉴权凭证可以通过实例化时传入的参数控制如何或获取，有三种获取方式：

1. 实例化时，传入 SecretId、SecretKey，每次需要签名都由实例内部计算。
2. 实例化时，传入 getAuthorization 回调，每次需要签名通过这个回调计算完返回签名给实例。
3. 实例化时，传入 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);
});