对象存储 > 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 应用程序的 Gemfile 文件中，添加如下一行代码：

gem 'qiniu', '~> 6.9.1'

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

$ bundle

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

$ gem install qiniu

初始化

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

可以通过如下步骤获得：

点击注册开通七牛开发者帐号
如果已有账号，直接登录七牛开发者后台，点击这里查看 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 框架，我们建议您在应用初始化启动的过程中，调用上述方法即可，操作如下：

在应用初始化脚本加载的目录中新建一个文件：YOUR_RAILS_APP/config/initializers/qiniu_sdk.rb
编辑 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

但这个只是将转码这个耗时的操作提交到队列中，要想知道转码操作现在的状态，需要根据返回的 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参考手册

贡献代码

Fork
创建您的特性分支 git checkout -b my-new-feature
提交您的改动 git commit -am ‘Added some feature’
将您的修改记录提交到远程 git 仓库 git push origin my-new-feature
然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

许可证

基于 MIT 协议发布:

www.opensource.org/licenses/MIT

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

对象存储