对象存储

  • Ruby SDK

    最近更新时间:2017-08-01 12:25:12

    此 Ruby SDK 适用于 Ruby 2.1.x,2.2.x,2.3.x,JRuby 9.x 版本。

    状态

    集成测试:Build Status Gem发布:Gem Version 依赖关系:Dependency Status

    代码评分:Code Climate

    维护人员

    liangtao@qiniu.com@无锋之刃

    安装

    在您 Ruby 应用程序的 Gemfile 文件中,添加如下一行代码:

    gem 'qiniu', '~> 6.8.1'
    

    然后,在应用程序所在的目录下,运行 bundle 安装依赖包:

    $ bundle
    

    或者,可以使用 Ruby 的包管理器gem进行安装:

    $ gem install qiniu
    

    初始化

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

    可以通过如下步骤获得:

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

    注意:用户应当妥善保存 SecretKey ,一旦发生泄露,请立刻到开发者平台更新。

    在使用Ruby SDK之前,需要初始化环境,并且设置 AccessKey 和 SecretKey:

    #!/usr/bin/env ruby
    
    require 'qiniu'
    
    Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                                secret_key: '<YOUR_APP_SECRET_KEY>'
    

    如果您使用的是 Ruby on Rails 框架,我们建议您在应用初始化启动的过程中,调用上述方法即可,操作如下:

    1. 在应用初始化脚本加载的目录中新建一个文件:YOUR_RAILS_APP/config/initializers/qiniu_sdk.rb

    2. 编辑 YOUR_RAILS_APP/config/initializers/qiniu_sdk.rb 文件内容如下:

    require 'qiniu'
    
    Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                                secret_key: '<YOUR_APP_SECRET_KEY>'
    

    这样,您就可以在您的 RAILS_APP 中使用七牛云存储 Ruby SDK 提供的其他任意方法了。

    文件上传

    上传流程

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

    上传代码:

    #!/usr/bin/env ruby
    
    require 'qiniu'
    
    # 构建鉴权对象
    Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                                secret_key: '<YOUR_APP_SECRET_KEY>'
    
    # 要上传的空间
    bucket = 'Bucket_Name'
    
    # 上传到七牛后保存的文件名
    key = 'my-ruby-logo.png'
    
    # 构建上传策略,上传策略的更多参数请参照 http://developer.qiniu.com/article/developer/security/put-policy.html
    put_policy = Qiniu::Auth::PutPolicy.new(
        bucket, # 存储空间
        key,    # 指定上传的资源名,如果传入 nil,就表示不指定资源名,将使用默认的资源名
        3600    # token 过期时间,默认为 3600 秒,即 1 小时
    )
    
    # 生成上传 Token
    uptoken = Qiniu::Auth.generate_uptoken(put_policy)
    
    # 要上传文件的本地路径
    filePath = './ruby-logo.png'
    
    # 调用 upload_with_token_2 方法上传
    code, result, response_headers = Qiniu::Storage.upload_with_token_2(
         uptoken,
         filePath,
         key,
         nil, # 可以接受一个 Hash 作为自定义变量,请参照 http://developer.qiniu.com/article/kodo/kodo-developer/up/vars.html#xvar
         bucket: bucket
    )
    
    #打印上传返回的信息
    puts code
    puts result
    

    上传 & 回调

    #!/usr/bin/env ruby
    
    require 'qiniu'
    
    # 构建鉴权对象
    Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                                secret_key: '<YOUR_APP_SECRET_KEY>'
    
    bucket = 'Bucket_Name'
    
    key = 'my-ruby-logo.png'
    
    put_policy = Qiniu::Auth::PutPolicy.new(
        bucket, # 存储空间
        key,    # 指定上传的资源名,如果传入 nil,就表示不指定资源名,将使用默认的资源名
        3600    # token 过期时间,默认为 3600 秒,即 1 小时
    )
    
    # 构建回调策略,这里上传文件到七牛后, 七牛将文件名和文件大小回调给业务服务器.
    callback_url = 'http://your.domain.com/callback'
    callback_body = 'filename=$(fname)&filesize=$(fsize)' # 魔法变量的使用请参照 http://developer.qiniu.com/article/kodo/kodo-developer/up/vars.html#magicvar
    
    put_policy.callback_url= callback_url
    put_policy.callback_body= callback_body
    
    # 生成上传 Token
    uptoken = Qiniu::Auth.generate_uptoken(put_policy)
    
    # 要上传文件的本地路径
    filePath = './ruby-logo.png'
    
    # 调用 upload_with_token_2 方法上传
    code, result, response_headers = Qiniu::Storage.upload_with_token_2(
         uptoken,
         filePath,
         key,
         nil, # 可以接受一个 Hash 作为自定义变量,请参照 http://developer.qiniu.com/article/kodo/kodo-developer/up/vars.html#xvar
         bucket: bucket
    )
    
    #打印上传返回的信息
    puts code
    puts result
    

    上传 & 预转持续化

    以视频转码为例:

    #!/usr/bin/env ruby
    
    require 'qiniu'
    
    # 构建鉴权对象
    Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                                secret_key: '<YOUR_APP_SECRET_KEY>'
    
    bucket = 'Bucket_Name'
    
    key = 'my-ruby-logo.png'
    
    put_policy = Qiniu::Auth::PutPolicy.new(
        bucket, # 存储空间
        key,    # 指定上传的资源名,如果传入 nil,就表示不指定资源名,将使用默认的资源名
        3600    # token 过期时间,默认为 3600 秒,即 1 小时
    )
    
    # 转码时使用的队列名称。
    pipeline = 'abc' # 设定自己账号下的队列名称
    
    # 要进行的转码操作。
    fops = "avthumb/mp4/s/640x360/vb/1.25m"
    
    # 可以对转码后的文件进行使用 saveas 参数自定义资源名,当然也可以不指定会默认命名并保存在上传文件所在的存储空间。
    saveas_key = Qiniu::Utils.urlsafe_base64_encode('<目标 Bucket_Name>:<自定义资源名>')
    fops = fops+'|saveas/'+saveas_key
    
    put_policy.persistent_ops = fops
    put_policy.persistent_pipeline = pipeline
    
    # 生成上传 Token
    uptoken = Qiniu::Auth.generate_uptoken(put_policy)
    
    # 要上传文件的本地路径
    filePath = './ruby-logo.png'
    
    # 调用upload_with_token_2方法上传
    code, result, response_headers = Qiniu::Storage.upload_with_token_2(
         uptoken,
         filePath,
         key,
         nil, # 可以接受一个 Hash 作为自定义变量,请参照 http://developer.qiniu.com/article/kodo/kodo-developer/up/vars.html#xvar
         bucket: bucket
    )
    
    #打印上传返回的信息
    puts code
    puts result
    

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

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

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

    文件下载

    生成下载链接:

    #!/usr/bin/env ruby
    
    require 'qiniu'
    
    Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                                secret_key: '<YOUR_APP_SECRET_KEY>'
    
    # 构建私有空间的链接
    primitive_url = 'http://domain/key'
    download_url = Qiniu::Auth.authorize_download_url(primitive_url)
    puts download_url
    

    空间资源管理

    获取文件信息

    #!/usr/bin/env ruby
    
    require 'qiniu'
    
    Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                                secret_key: '<YOUR_APP_SECRET_KEY>'
    
    # 要测试的存储空间,并且这个资源名在存储空间中存在
    bucket = 'Bucket_Name'
    key = 'ruby-logo.png'
    
    # 获取文件信息
    code, result, response_headers = Qiniu::Storage.stat(
        bucket,     # 存储空间
        key         # 资源名
    )
    puts code
    puts result
    puts response_headers
    

    移动单个文件

    #!/usr/bin/env ruby
    
    require 'qiniu'
    
    Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                                secret_key: '<YOUR_APP_SECRET_KEY>'
    
    # 要移动的存储空间,并且这个资源名在存储空间中存在
    bucket = 'Bucket_Name'
    key = 'ruby-logo.png'
    
    # 移动到的目标存储空间名和目标资源名
    dst_bucket = 'dst_bucket'
    dst_key = 'dst_key'
    
    # 移动文件
    code, result, response_headers = Qiniu::Storage.move(
        bucket,         # 原存储空间
        key,            # 原资源名
        dst_bucket,     # 目标存储空间
        dst_key         # 目标资源名
    )
    puts code
    puts result
    puts response_headers
    

    复制单个文件

    #!/usr/bin/env ruby
    
    require 'qiniu'
    
    Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                                secret_key: '<YOUR_APP_SECRET_KEY>'
    
    # 要复制的存储空间,并且这个资源名在存储空间中存在
    bucket = 'Bucket_Name'
    key = 'ruby-logo.png'
    
    # 复制到的目标存储空间名和目标资源名
    dst_bucket = 'dst_bucket'
    dst_key = 'dst_key'
    
    # 复制文件
    code, result, response_headers = Qiniu::Storage.copy(
        bucket,         # 原存储空间
        key,            # 原资源名
        dst_bucket,     # 目标存储空间
        dst_key         # 目标资源名
    )
    puts code
    puts result
    puts response_headers
    

    删除单个文件

    #!/usr/bin/env ruby
    
    require 'qiniu'
    
    Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                                secret_key: '<YOUR_APP_SECRET_KEY>'
    
    # 要删除的存储空间,并且这个资源名在存储空间中存在
    bucket = 'Bucket_Name'
    key = 'ruby-logo.png'
    
    # 删除资源
    code, result, response_headers = Qiniu::Storage.delete(
        bucket,     # 存储空间
        key         # 资源名
    )
    
    puts code
    puts result
    puts response_headers
    

    列举文件条目

    #!/usr/bin/env ruby
    
    require 'qiniu'
    
    Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                                secret_key: '<YOUR_APP_SECRET_KEY>'
    
    # 要列举的存储空间名
    bucket = 'Bucket_Name'
    
    # 调用 list 接口,参数可以参考 http://developer.qiniu.com/code/v6/api/kodo-api/rs/list.html#list-specification
    code, result, response_headers, s, d = Qiniu::Storage.list(Qiniu::Storage::ListPolicy.new(
        bucket,   # 存储空间
        100,      # 列举的条目数
        'photo/', # 指定前缀
        ''        # 指定目录分隔符
    ))
    
    # 打印出返回的状态码和信息
    puts code
    puts result
    puts response_headers
    

    抓取文件

    #!/usr/bin/env ruby
    
    require 'qiniu'
    
    Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                                secret_key: '<YOUR_APP_SECRET_KEY>'
    
    # 需要抓取操作保存到的空间名
    bucket = 'Bucket_Name'
    
    # 抓取的 URL,需要外网可以访问到
    target_url = 'https://oerugfbxb.qnssl.com/wp-content/themes/Earthshaker-1/images/logo.png'
    
    # 抓取后保存的资源名
    key = 'qiniu.png'
    
    # 调用fetch方法
    code, result, response_headers = Qiniu::Storage.fetch(
        bucket,
        target_url,
        key
    )
    
    # 打印返回的状态码以及信息
    puts code
    puts result
    puts response_headers
    

    触发持久化操作

    以视频转码为例:

    #!/usr/bin/env ruby
    
    require 'qiniu'
    require 'qiniu/utils'
    
    # 构建鉴权对象
    Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                                secret_key: '<YOUR_APP_SECRET_KEY>'
    
    # 要转码的文件所在的存储空间和资源名。
    bucket = 'Bucket_Name'
    key = '1.mp4'
    
    # 转码时使用的队列名称。
    pipeline = 'abc' # 设定自己账号下的队列名称
    
    # 要进行的转码操作。
    fops = "avthumb/mp4/s/640x360/vb/1.25m"
    
    # 可以对转码后的文件进行使用 saveas 参数自定义资源名,当然也可以不指定会默认命名并保存在原文件所在的存储空间。
    saveas_key = Qiniu::Utils.urlsafe_base64_encode('<目标 Bucket_Name>:<自定义资源名>')
    fops = fops+'|saveas/'+saveas_key
    
    pfops = Qiniu::Fop::Persistance::PfopPolicy.new(
        bucket,         # 存储空间
        key,            # 指定上传的资源名,如果传入 nil,就表示不指定资源名,将使用默认的资源名
        fops,
        'http://www.baidu.com/notify' # 处理结果通知接收 URL
    )
    pfops.pipeline = pipeline
    
    code, result, response_headers = Qiniu::Fop::Persistance.pfop(pfops)
    puts code
    puts result
    puts response_headers
    

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

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

    错误处理

    如果遇到错误,请将各个方法返回的 code、result、response_headers 以如下格式输出,并将输出结果通过邮件发送给我们。

    #!/usr/bin/env ruby
    
    require 'qiniu'
    
    # 已在某处调用某个SDK方法
    
    puts code.inspect
    puts result.inspect
    puts response_headers.inspect
    

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

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