iwillwen / node-qiniu

Qiniu Cloud Storage SDK for Node.js

七牛 Node.js SDK

该 SDK 适用于 Node.js 0.4.7 及其以上版本，基于 七牛云存储官方API 构建。 若您的服务端是一个基于 Node.js 编写的网络程序，使用此 SDK ， 能让您以非常便捷地方式将数据安全地存储到七牛云存储上。 以便让您应用的终端用户进行高速上传和下载，同时也使得您的服务端更加轻盈。

安装

你可以从 npm 进行安装

npm install node-qiniu

也可以从 Github 进行下载安装

$ git clone git://github.com/qiniu/node-qiniu
$ cd node-qiniu
$ npm install .

测试

七牛 Node.js SDK 使用 Mocha 进行单元测试。

$ npm install -g mocha
$ make test

使用

配置 qiniu.config()

设置全局参数，包括必须的 AccessKey 和 SecretKey，还可以设置其他如 CallbackURL 等参数，将会顺延至所有空间。

qiniu.config({
  access_key: '------',
  secret_key: '------'
});

Bucket

获得空间对象并进行操作。

var imagesBucket = qiniu.bucket('qiniu-sdk-test');
// 也可以这样操作
// var imagesBucket = new qiniu.Bucket('qiniu-sdk-test');

上传文件

1. Bucket.putFile()

上传一个文件，参数为将要上传的 Key，文件地址(可以是绝对地址，也可以是相对地址)，第三个为可选参数 options，即本次上传中所使用 PutToken 的特殊设置，第四个为可选参数回调(callback)，若不传入回调函数，将由 putFile 函数所返回的 Promise 对象进行响应。

// 普通上传
imagesBucket.putFile('exampleKey', __dirname + '/assets/example.jpg', function(err, reply) {
  if (err) {
    return console.error(err);
  }

  console.dir(reply);
});
// 特殊参数
imagesBucket.putFile('exampleKey_1', __dirname + '/assets/example.jpg', {
  // 为本次上传中所使用的 Token 进行设置，此处为设置上传者标识
  endUser: 'foobar'
}, function(err, reply) {
  if (err) {
    return console.error(err);
  }

  console.dir(reply);
});
// 七牛 Node.js SDK 所提供的 Promise 对象遵循 Promise/A(+) 标准，使用 .then 方法进行响应
imagesBucket.putFile('exampleKey_2', __dirname + '/assets/example.jpg')
  .then(
    function(reply) {
      // 上传成功
      console.dir(reply);
    },
    function(err) {
      // 上传失败
      console.error(err);
    }
  );

2. Bucket.createPutStream()

七牛 Node.js SDK 提供基于流(Stream)的操作方式，为熟悉 Node.js 流式操作的开发者提供方便快捷的高性能 API。

var puttingStream = imagesBucket.createPutStream('exampleKey_3');
var readingStream = fs.createReadStream(__dirname + '/assets/example.jpg');

readingStream.pipe(puttingStream)
  .on('error', function(err) {
    console.error(err);
  })
  .on('end', function(reply) {
    console.dir(reply);
  });

下载文件

Bucket.getFile()和Bucket.createGetStream()

获取文件与上传文件同样简单，和 Node.js 中原生的文件系统(File System)的 API 有相似之处。

imagesBucket.getFile('exampleKey', function(err, data) {
  if (err) {
    return console.error(err);
  }

  // data 为包含文件数据的 Buffer 对象
});

同样的，获取文件也可以使用流式操作进行

var gettingStream = imagesBucket.createGetStream('exampleKey');
var writingStream = fs.createWriteStream(__dirname + '/assets/example_tmp.jpg');

gettingStream.pipe(writingStream)
  .on('error', function(err) {
    console.error(err);
  })
  .on('finish', function() {
    // 文件数据已写入本地文件系统
  });

Image 图片操作

七牛 Node.js SDK 提供Image类，用于对图片资源进行操作。

使用 Bucket.image() 方法获取一个图像对象

var image = imagesBucket.image('exampleKey');

Image.imageInfo()

Image.imageInfo 方法可以用于获取图片资源的图片信息。 详细请看：http://docs.qiniu.com/api/v6/image-process.html#imageInfo

image.imageInfo(function(err, info) {
  if (err) {
    return console.error(err);
  }

  console.dir(info);
});

Image.exif()

Image.imageView 方法用于生成指定规格的缩略图。 详细请看：http://docs.qiniu.com/api/v6/image-process.html#imageView

image.exif(function(err, exif) {
  if (err) {
    return console.error(err);
  }

  console.dir(exif);
});

Image.imageView()

Image.imageView 方法用于生成指定规格的缩略图。 详细请看：http://docs.qiniu.com/api/v6/image-process.html#imageView

image.imageView({
  mode    : 2,
  width   : 180,
  height  : 180,
  quality : 85,
  format  : 'jpg'
}, function(err, imageData) {
  if (err) {
    return console.error(err);
  }

  // imageData 为处理过后的图像数据
});

其中，图片对象中的所有含图片数据返回的方法可以使用流式操作。不传入第二个的 callback 参数，而在调用方法的括弧后再调用.stream()方法，则会返回一个会不断输出数据的 IO 流。

var imageViewStream = image.imageView({
  mode    : 2,
  width   : 180,
  height  : 180,
  quality : 85,
  format  : 'jpg'
}).stream();
var writingStream = fs.createWriteStream(__dirname + '/assets/example_thumbnail.jpg');

imageViewStream.pipe(writingStream)
  .on('error', function(err) {
    console.error(err);
  })
  .on('finish', function() {
    // 缩略图已写入本地文件系统
  });

诸如此类：

image.imageMogr(...).stream();
image.watermark(...).stream();
image.alias(...).stream();

Image.imageMogr()

Image.imageMogr 方法用于调用高级图像处理接口，并返回处理后的图片数据。 详细请看：http://docs.qiniu.com/api/v6/image-process.html#imageMogr

image.imageMogr({
  thumbnail : '300x500',
  gravity   : 'NorthWest',
  crop      : '!300x400a10a10',
  quality   : 85,
  rotate    : 90,
  format    : 'jpg'
}, function(err, imageData) {
  if (err) {
    return console.error(err);
  }

  // 使用 imageData 进行操作
});

Image.watermark()

Image.watermark 方法用于生成一个带有水印的图片，图片水印 API 支持图片水印和文字水印两种模式。 详细请看：http://docs.qiniu.com/api/v6/image-process.html#watermark

image.watermark({
  mode: 1,
  image: 'http://www.b1.qiniudn.com/images/logo-2.png',
  dissolve: 70,
  gravity: 'SouthEast',
  dx: 20,
  dy: 20
}, function(err, imageData) {
  if (err) {
    return console.error(err);
  }

  // 使用 imageData 进行操作
});

Image.alias()

Image.alias 方法用于返回既定的数据处理格式的数据，使用此方法需要在七牛开发者平台中对设置进行操作。 其中，Image.alias()方法继承于 key 所用的Asset类。

image.alias('testalias', function(err, imageData) {
  if (err) {
    return console.error(err);
  }

  // 使用 imageData 进行操作
});

Asset 资源操作

七牛 Node.js SDK 提供一个Asset类，用于对所属资源进行操作。

获取 key 所对应资源对象

var picture = imagesBucket.key('exampleKey');

Asset.url()

Asset.url()方法可以获得该资源的 URL 地址以用于访问

var picUrl = picture.url();

Asset.entryUrl()

Asset.entryUrl()方法可以获得该资源用于 API 调用时所需的 EncodedEntryURL。 但是在 Node.js SDK 中，大部分 API 都不需要开发者自行使用。:)

var encodedPicUrl = picture.entryUrl();

Asset.stat()

Asset.stat 方法可以获得该资源的如文件大小、MIME 类型等 stat 数据。

picture.stat(function(err, stat) {
  if (err) {
    return console.error(err);
  }

  console.dir(stat);
  /**
   * {
   *   hash     : <FileEtag>, // string 类型，文件的Hash值
   *   fsize    : <FileSize>, // int 类型，文件的大小(单位: 字节)
   *   mimeType : <MimeType>, // string 类型，文件的媒体类型，比如"image/gif"
   *   putTime  : <PutTime>   // int64 类型，文件上传到七牛云的时间(Unix时间戳)
   * }
   */
});

Asset.move()

Asset.move()方法用于移动该资源到指定的位置。 第一个参数可以是来自其他 Bucket 所属的资源对象。

picture.move(imagesBucket.key('exampleKey_4'), function(err) {
  if (err) {
    return console.error(err);
  }

  // 此处没有返回值，如果没有错误，则为操作成功，以下方法相同
});

Asset.copy()

Asset.copy()方法用于为该资源创建一个拷贝，并保存到指定的资源位置。

imagesBucket.key('exampleKey_4').copy(picture, function(err) {
  if (err) {
    return console.error(err);
  }
});

Asset.remove()

Asset.remove()方法用于删除当前资源。

imagesBucket.key('exampleKey_4').remove(function(err) {
  if (err) {
    return console.error(err);
  }
});

Asset.token()

Asset.token()方法用于生成当前资源的下载凭证。

var getToken = imagesBucket.key('exampleKey').token();

console.dir(getToken);
/*=>
  {
    url: '<Full download url>',
    token: '<Get token>',
    requestUrl: 'URL without token'
  }
 */
  }

Asset.download()

Asset.download()方法用于生成当前资源的下载链接。(不包含下载凭证)

var url = imagesBucket.key('exampleKey').download();

Batch 资源批量操作

在支持对单个文件资源操作的同时，七牛云存储还支持批量地对多个文件进行查看、删除、复制和移动操作。 详细请看：http://docs.qiniu.com/api/v6/rs.html#batch

生成一个批量操作的控制器

var batch = qiniu.batch();

Batch中大部分参数与资源对象Asset类似，支持查看、移动、复制和删除操作。

batch
  // 获取文件信息
  .stat(imagesBucket.key('exampleKey'))
  // 移动资源
  .move(imagesBucket.key('exampleKey'), imagesBucket.key('exampleKey_5'))
  // 复制资源
  .copy(imagesBucket.key('exampleKey_5'), imagesBucket.key('exampleKey'))
  // 删除资源
  .remove(imagesBucket.key('exampleKey_5'))
  // 执行操作
  // 每一个操作都按照前后顺序进行执行
  .exec(function(err, results) {
    if (err) {
      return console.error(err);
    }

    console.dir(results);
    // results 为每一个操作的结果
  });

Fop 管道操作

七牛云存储提供一个非常实用的资源处理 API，可以用于对资源进行多种处理的操作。

例: 将一个原图缩略，然后在缩略图上打上另外一个图片作为水印

使用Asset.fop()方法创建 Fop 管道操作器，并进行操作。

var image = imagesBucket.key('exampleKey');
// Image.fop 方法继承于 Asset 类

image.fop()
  // 对图片进行缩略
  .imageView({
    mode   : 2,
    height : 200
  })
  // 为图片打上水印
  .watermark({
    mode  : 1,
    image : 'http://www.b1.qiniudn.com/images/logo-2.png'
  })
  // 执行操作
  .exec(function(err, imageData) {
    if (err) {
      return console.error(err);
    }

    // imageData 为已打上水印的缩略图数据
  });

Fop.token()

该方法用于生成当前 Fop 的下载凭证。

var image = imagesBucket.key('exampleKey');
// Image.fop 方法继承于 Asset 类

var getToken = image.fop()
  // 对图片进行缩略
  .imageView({
    mode   : 2,
    height : 200
  })
  // 为图片打上水印
  .watermark({
    mode  : 1,
    image : 'http://www.b1.qiniudn.com/images/logo-2.png'
  })
  .token();

console.log(getToken.url);

模块结构

License

(The MIT License)

Copyright (c) 2010-2013 Will Wen Gunn <[email protected]> and other contributors

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

node-qiniu's Issues

用steam put文件，请问怎样自动生成key。

我希望key 自动变成hash值，请问怎么调用
var key ="test"
return new Promise(function(resolve,reject){
var puttingStream = imagesBucket.createPutStream(key);
request.get(url).pipe(puttingStream)
.on('error', function(err) {
console.error(err);
reject(err)
})
.on('end', function(reply) {
console.dir(reply);
resolve(reply)
});
})

在远程VPS上传图片后台报错：Unexpected token u

在远程VPS上传图片后台报错：Unexpected token u:
at Object.parse (native)
at Request._callback (/var/www/thaisse.com/site/node_modules/node-qiniu/lib/bucket.js:87:23)
本地没有这个问题，请问这是为什么呢？

图片上传成功，但是文件为空

RT

这里的安装 readme 有误...

安装 readme 有误...

是否可以支持Buffer直传？

有时base64过来的文件没必要往本地存一下……

Asset.stat方法bug：当AK或SK错误，会导致异常

Asset.stat 方法没有对request返回的http状态码进行检查，导致在AK或SK错误的情况下会报错：

SyntaxError: Unexpected end of input
    at Object.parse (native)
    at Request._callback (E:\..................\node_modules\node-qiniu\lib\asset.js:132:29)

查了一下资料并进行对比了一下，好像这个其实是七牛官方那边接口有点问题，官方的文档标注：

如果请求失败，返回包含如下内容的JSON字符串（已格式化，便于阅读）：

{
    "error":   "<errMsg    string>"
}

字段名称	必填	说明
error	是	与HTTP状态码对应的消息文本

响应状态码

HTTP状态码	含义
200	获取Metadata成功
400	请求报文格式错误
401	管理凭证无效
599	服务端操作失败 如遇此错误，请将完整错误信息（包括所有HTTP响应头部）通过邮件发送给我们
612	目标资源不存在

另外，还有一些没有标注出来

但实际上，631确实返回了包含error的json格式内容{"error":"no such bucket"}。
但401却没有返回json格式内容，内容长度是0

request err: null
request statusCode: 401
request body.length: 0
request body:

SyntaxError: Unexpected end of input
    at Object.parse (native)
    at Request._callback (E:\..................\node_modules\node-qiniu\lib\asset.js:132:29)

七牛官方接口固然是一方面，但这个库是否也该增加一层对res.statusCode的检查呢？

fetch接口 怎么调用

文档:http://developer.qiniu.com/docs/v6/api/reference/rs/fetch.html#fetch-request-syntax
node sdk 没发现

fetch方法参数url和url模块冲突

Asset.prototype.fetch = function(url, callback) {
  var self = this
  return new Promise(function(resolve, reject) {
    callback = callback || noop;

    var path = util.format('/fetch/%s/to/%s', utils.safeEncode(url), self.entryUrl());
    var _url = url.format({
      protocol: 'http',
      hostname: config.vipUrl,
      pathname: path
    });

    var token = self.access_token.token(path, null);

    request({
      url: _url, 
      method: 'POST',
      headers: {
        'Authorization': token,
        'Content-Type': 'application/x-www-form-urlencoded'
      }
    }, function(err, res, body) {
      if (err) {
        reject(err);
        return callback(err);
      }

      resolve();
      callback(null);
    });
  })
};

Asset.prototype.fetch = function(url, callback) {
var _url = url.format({ //此处url和参数url有冲突
      protocol: 'http',
      hostname: config.vipUrl,
      pathname: path
    });
}

dataStream 理论上会导致溢出

粗略看了一下，依赖了你自己写的 dataStream 模块。Stream 本身的目的就是让数据更快地被下游使用，但是 dataStream 的实现却会把这个 stream 的数据全部缓存起来给 .body() 方法使用。可能会导致溢出哦。。。

bucket.pubFile 方法错误提示不准确

bucket.pubFile 方法在 accessKey 或 secretKey 错误导致认证错误时，会返回 [TypeError: Not a buffer] 提示信息，而不是认证错误类似的提示

请更新 package.json 的 Repository 和 Homepage

需要改成： https://www.npmjs.org/package/node-qiniu

putFile方法：当传入options且未传callback时报错

当使用返回Promise的模式时，比如 await $bucket.putFile( key, filePath, policy )

这时应该不需要传callback，但会报错：callback不是一个function

不传入policy时没问题，我看了下源码，是否应在arguments.length为3时也处理callback指向noop？

如何获取下载外链

asset.url
asset.entryUrl
asset.download
都没有得到我要的外链

默认上传地址失效

在调用API时遇到上传数据后返回结果不是JSON导致解析错误的状况，经过调查发现是因为upload.qiniu.com这个地址已经失效，现在需要根据bucket的地区来设置不同的地址。

七牛的官方文档说明：上传到华东一区的域名为up.qiniu.com、up-z0.qiniu.com和upload.qiniu.com；上传到华北一区的域名为up-z1.qiniu.com和upload-z1.qiniu.com。

读过源码并测试时发现可以用set(key, value)来设置上传地址，如果可能，希望把这个细节附加在说明文件里，谢谢。

文件已经存在时，putFile调用后无法更新文件

当文件已经存在时（key相同），调用putFile后无err，但没有更新文件。删除存储空间中的key后才可以（以前不会，近1个月出现的）

readingStream.pipe 上传文件end事件触发了2次

大大看到了麻烦加下我扣扣:513540913
让我交流学习下 谢谢！