对象存储

  • Node.js SDK V6

    最近更新时间:2017-06-27 11:11:48

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

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

    • 服务端操作,生成上传授权(uptoken),私有bucket下载URL(downloadUrl),文件操作授权
    • 客户端操作,上传文件(qiniu/io.js)
    • 文件管理(qiniu/rs.js)
    • 数据处理(qiniu/fop.js)
    • 公共库(qiniu/rpc.js, qiniu/util.js)

    安装

    通过 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 协议发布:

    以上内容是否对您有帮助?
  • 提交工单