开发者中心 开发者资源 官方 SDKs Node.js SDK 使用指南
Node.js SDK 使用指南

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

Node.js SDK 主要包含对七牛云API的包装,遵循qiniu sdkspec 涉及到以下几个方面:

安装

通过 npm 以 node 模块化的方式安装:

npm install qiniu

初始化

在使用SDK 前,您需要一对有效的 AccessKey 和 SecretKey 签名授权。

可以通过如下步骤获得:

  1. 开通七牛开发者帐号
  2. 登录七牛开发者平台,查看 Access Key 和 Secret Key

对于服务端而言,常规程序流程是:

qiniu.conf.ACCESS_KEY = '<Your Access Key>'
qiniu.conf.SECRET_KEY = '<Your Secret Key>'

服务端操作时请务必初始化这两个变量

文件上传

上传流程

为了尽可能地改善终端用户的上传体验,七牛云存储首创了客户端直传功能。更多信息请参阅业务流程

上传代码:

var qiniu = require("qiniu");

//需要填写你的 Access Key 和 Secret Key
qiniu.conf.ACCESS_KEY = 'Access_Key';
qiniu.conf.SECRET_KEY = 'Secret_Key';

//要上传的空间
bucket = 'Bucket_Name';

//上传到七牛后保存的文件名
key = 'my-nodejs-logo.png';

//构建上传策略函数
function uptoken(bucket, key) {
  var putPolicy = new qiniu.rs.PutPolicy(bucket+":"+key);
  return putPolicy.token();
}

//生成上传 Token
token = uptoken(bucket, key);

//要上传文件的本地路径
filePath = './ruby-logo.png'

//构造上传函数
function uploadFile(uptoken, key, localFile) {
  var extra = new qiniu.io.PutExtra();
    qiniu.io.putFile(uptoken, key, localFile, extra, function(err, ret) {
      if(!err) {
        // 上传成功, 处理返回值
        console.log(ret.hash, ret.key, ret.persistentId);       
      } else {
        // 上传失败, 处理返回代码
        console.log(err);
      }
  });
}

//调用uploadFile上传
uploadFile(token, key, filePath);

上传&回调

var qiniu = require("qiniu");

//需要填写你的 Access Key 和 Secret Key
qiniu.conf.ACCESS_KEY = 'Access_Key';
qiniu.conf.SECRET_KEY = 'Secret_Key';

//要上传的空间
bucket = 'Bucket_Name';

//上传到七牛后保存的文件名
key = 'my-nodejs-logo.png';

//构建上传策略函数,设置回调的url以及需要回调给业务服务器的数据
function uptoken(bucket, key) {
  var putPolicy = new qiniu.rs.PutPolicy(bucket+":"+key);
  putPolicy.callbackUrl = 'http://your.domain.com/callback';
  putPolicy.callbackBody = 'filename=$(fname)&filesize=$(fsize)';
  return putPolicy.token();
}

//生成上传 Token
token = uptoken(bucket, key);

//要上传文件的本地路径
filePath = './nodejs-logo.png'

//构造上传函数
function uploadFile(uptoken, key, localFile) {
  var extra = new qiniu.io.PutExtra();
    qiniu.io.putFile(uptoken, key, localFile, extra, function(err, ret) {
      if(!err) {
        // 上传成功, 处理返回值
        console.log(ret.hash, ret.key, ret.persistentId);       
      } else {
        // 上传失败, 处理返回代码
        console.log(err);
      }
  });
}

//调用uploadFile上传
uploadFile(token, key, filePath);

上传&预转持续化

以视频转码为例:

var qiniu = require("qiniu");

//需要填写你的 Access Key 和 Secret Key
qiniu.conf.ACCESS_KEY = 'Access_Key';
qiniu.conf.SECRET_KEY = 'Secret_Key';

//要上传的空间
bucket = 'Bucket_Name';

//上传到七牛后保存的文件名
key = 'my-nodejs.mp4';

//转码是使用的队列名称。 
pipeline = 'abc' #设定自己账号下的pipleline

//要进行转码的转码操作。 
fops = "avthumb/mp4/s/640x360/vb/1.25m"

//可以对转码后的文件进行使用saveas参数自定义命名,当然也可以不指定文件会默认命名并保存在当间。
saveas_key = qiniu.util.urlsafeBase64Encode(目标Bucket_Name:自定义文件key); 
fops = fops+'|saveas/'+saveas_key;;

//上传策略中设置pipeline以及fops
function uptoken(bucket, key) {
  var putPolicy = new qiniu.rs.PutPolicy(bucket+":"+key);
  putPolicy.persistentOps = fops;
  putPolicy.persistentPipeline = pipleline;
  return putPolicy.token();
}

//生成上传 Token
token = uptoken(bucket, key);

//要上传文件的本地路径
filePath = './nodejs.mp4'

//构造上传函数
function uploadFile(uptoken, key, localFile) {
  var extra = new qiniu.io.PutExtra();
    qiniu.io.putFile(uptoken, key, localFile, extra, function(err, ret) {
      if(!err) {
        // 上传成功, 处理返回值
        console.log(ret.hash, ret.key, ret.persistentId);       
      } else {
        // 上传失败, 处理返回代码
        console.log(err);
      }
  });
}

//调用uploadFile上传
uploadFile(token, key, filePath);

队列pipeline 请参阅创建私有队列;转码操作 具体参数请参阅音视频转码;saveas 请参阅处理结果另存

Tips:上面的Demo只是针对视频转码功能,如果您需要使用比如音视频切片、视频截图、视频拼接等功能只需要修改上面 fops 后面的参数即可,如:fops = vframe/jpg/offset/1/w/480/h/360/rotate/90 就表示视频截图了。

可以看到上传成功后的行为主要是由上传凭证中的 上传策略 来指定。其中 上传策略 可以指定的行为不止这些,具体请参阅 上传策略

文件下载

生成下载链接:

var qiniu = require("qiniu");

qiniu.conf.ACCESS_KEY = 'Access_Key';
qiniu.conf.SECRET_KEY = 'Secret_Key';

//构建私有空间的链接
url = 'http://domain/key';
var policy = new qiniu.rs.GetPolicy();

//生成下载链接url
var downloadUrl = policy.makeRequest(url);

//打印下载的url
console.log(downloadUrl);

空间资源管理

获取文件信息

var qiniu = require("qiniu");

qiniu.conf.ACCESS_KEY = 'Access_Key';
qiniu.conf.SECRET_KEY = 'Secret_Key';

//构建bucketmanager对象
var client = new qiniu.rs.Client();

//你要测试的空间, 并且这个key在你空间中存在
bucket = 'Bucket_Name';
key = 'nodejs-logo.png';

//获取文件信息
client.stat(bucket, key, function(err, ret) {
  if (!err) {
    console.log(ret.hash, ret.fsize, ret.putTime, ret.mimeType);
  } else {
    console.log(err);
  }
});

移动单个文件

var qiniu = require("qiniu");

qiniu.conf.ACCESS_KEY = 'Access_Key';
qiniu.conf.SECRET_KEY = 'Secret_Key';

//构建bucketmanager对象
var client = new qiniu.rs.Client();

//你要测试的空间, 并且这个key在你空间中存在
bucket = 'Bucket_Name';
key = 'nodejs-logo.png';

//移动到的目标空间名和重命名的key
dstbucket = 'dst_bucket'
dstkey = 'dst_key'

//移动资源
client.move(bucket, key, dstbucket, deskey, function(err, ret) {
  if (!err) {
    // ok
  } else {
    console.log(err);
  }
});

复制单个文件

var qiniu = require("qiniu");

qiniu.conf.ACCESS_KEY = 'Access_Key';
qiniu.conf.SECRET_KEY = 'Secret_Key';

//构建bucketmanager对象
var client = new qiniu.rs.Client();

//你要测试的空间, 并且这个key在你空间中存在
bucket = 'Bucket_Name';
key = 'nodejs-logo.png';

//复制到的目标空间名和重命名的key
dstbucket = 'dst_bucket'
dstkey = 'dst_key'

//复制资源
client.copy(bucket, key, dstbucket, deskey, function(err, ret) {
  if (!err) {
    // ok
  } else {
    console.log(err);
  }
});

删除单个文件

var qiniu = require("qiniu");

qiniu.conf.ACCESS_KEY = 'Access_Key';
qiniu.conf.SECRET_KEY = 'Secret_Key';

//构建bucketmanager对象
var client = new qiniu.rs.Client();

//你要测试的空间, 并且这个key在你空间中存在
bucket = 'Bucket_Name';
key = 'nodejs-logo.png';

//删除资源
client.remove(bucket, key, function(err, ret) {
  if (!err) {
    // ok
  } else {
    console.log(err);
  }
});

触发持久化操作

以视频转码为例:

var qiniu = require("qiniu");

//
qiniu.conf.ACCESS_KEY = 'Access_Key';
qiniu.conf.SECRET_KEY = 'Secret_Key';

//要转码的文件所在的空间和文件名
bucket = 'Bucket_Name';
key = '1.mp4';

//转码所使用的队列名称。 
pipeline = 'abc';

//要进行转码的转码操作。   
fops = "avthumb/mp4/s/640x360/vb/1.25m"

//可以对转码后的文件进行使用saveas参数自定义命名,当然也可以不指定文件会默认命名并保存在当前空间
saveas_key = qiniu.util.urlsafeBase64Encode(saved_bucket+':'+saved_key);
fops = fops+'|saveas/'+saveas_key;

opts = {
    pipeline: pipleline
};

var PFOP = qiniu.fop.pfop(bucket, key, fops, opts, function(err, ret) {
      if(!err) {
        // 上传成功, 处理返回值
        console.log('curl '+'http://api.qiniu.com/status/get/prefop?id='+ret.persistentId);       
      } else {
        // 上传失败, 处理返回代码
        console.log(err);
      }
  });

Tips:上面的Demo只是针对视频转码功能,如果您需要使用比如音视频切片、视频截图、视频拼接等功能只需要修改上面 fops 后面的参数即可,如:fops = vframe/jpg/offset/1/w/480/h/360/rotate/90 就表示视频截图了。

但这个只是将转码这个耗时的操作提交到队列中,要想知道转码操作现在的状态, 需要根据返回的 persitentId 进行查询。如果您不方便持续轮询每个异步处理的进度和状态,七牛可以异步处理完成后通知您们的业务服务器。这样就需要您在视频转码的例子中, 初始化 PersistentFop 时添加上 notifyUrl , 来通知您们的业务服务器。

API参考手册

相关资源

如果您有任何关于我们文档或产品的建议和想法,欢迎到我们的技术论坛参与讨论。

贡献代码

  1. Fork

  2. 创建您的特性分支 git checkout -b my-new-feature

  3. 提交您的改动 git commit -am 'Added some feature'

  4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature

  5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

许可证

Copyright (c) 2014 qiniu.com

基于 MIT 协议发布:

提交工单