human: 如何处理七牛云的对象存储Ruby SDK

gpt: [对象存储](https://developer.qiniu.com/kodo) > SDK 下载 > Ruby SDK

#  Ruby SDK

最近更新时间: 2023-04-04 11:42:05

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

  * [Ruby SDK 下载地址 __](https://github.com/qiniu/ruby-sdk/releases)
  * [Ruby SDK 源码地址 __](https://github.com/qiniu/ruby-sdk)

# 安装

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

    
    
    gem 'qiniu', '~> 6.9.1'
    

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

    
    
    $ bundle
    

或者，可以使用 Ruby 的包管理器`gem`进行安装：

    
    
    $ gem install qiniu
    

**初始化**

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

可以通过如下步骤获得：

  1. 点击[注册 __](https://portal.qiniu.com/signup)开通 七牛开发者帐号
  2. 如果已有账号，直接登录七牛开发者后台，点击[这里 __](https://portal.qiniu.com/user/key)查看 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
__](http://rubyonrails.org/)框架，我们建议您在应用初始化启动的过程中，调用上述方法即可，操作如下：

  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 提供的其他任意方法了。

# 文件上传

## 上传流程

为了尽可能地改善终端用户的上传体验，七牛云存储首创了客户端直传功能。更多信息请参阅[业务流程](https://developer.qiniu.com/kodo/manual/1205/programming-
model)。

**上传代码：**

    
    
    #!/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 请参阅[创建私有队列 __](https://portal.qiniu.com/dora/media-
gate/pipeline)；转码操作 具体参数请参阅[音视频转码](https://developer.qiniu.com/dora/api/audio-
and-video-transcoding-avthumb)；saveas
请参阅[处理结果另存](https://developer.qiniu.com/dora/api/processing-results-save-
saveas)。

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

可以看到上传成功后的行为主要是由[上传凭证](https://developer.qiniu.com/kodo/manual/1208/upload-
token)中的 **上传策略** 来指定。其中 **上传策略** 可以指定的行为不止这些，具体请参阅
[上传策略](https://developer.qiniu.com/kodo/manual/1206/put-policy) 。

# 文件下载

生成下载链接：

    
    
    #!/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 以如下格式输出，并将输出结果 [提交工单
__](https://support.qiniu.com/tickets/category)给我们 。

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

# API参考手册

  * [对象存储API参考手册](https://developer.qiniu.com/kodo/api/3939/overview-of-the-api)
  * [数据处理API参考手册](https://developer.qiniu.com/dora)

# 相关资源

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

  * [技术论坛 __](http://segmentfault.com/qiniu)\- 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
  * [提交工单 __](https://support.qiniu.com/tickets/new)\- 如果您的问题不适合在论坛讨论或得不到回答，您也可以提交一个工单，技术支持人员会尽快回复您
  * [博客 __](http://blog.qiniu.com)\- 这里会持续发布市场活动和技术分享文章
  * [微博 __](http://weibo.com/qiniutek)
  * [常见问题 __](https://support.qiniu.com/question)

# 贡献代码

  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 © 2014 qiniu.com

基于 MIT 协议发布:

  * [www.opensource.org/licenses/MIT __](http://www.opensource.org/licenses/MIT)

以上内容是否对您有帮助？