--- title: Ruby SDK 使用指南 | 七牛云存储 --- # Ruby SDK 使用指南 此 Ruby SDK 适用于 Ruby 1.8.x, 1.9.x, jruby, rbx, ree 版本，基于 [七牛云存储官方API](/v2/api/) 构建。使用此 SDK 构建您的网络应用程序，能让您以非常便捷地方式将数据安全地存储到七牛云存储上。无论您的网络应用是一个网站程序，还是包括从云端（服务端程序）到终端（手持设备应用）的架构的服务或应用，通过七牛云存储及其 SDK，都能让您应用程序的终端用户高速上传和下载，同时也让您的服务端更加轻盈。 七牛云存储 Ruby SDK 源码地址：[https://github.com/qiniu/ruby-sdk](https://github.com/qiniu/ruby-sdk) **文档大纲** - [安装](#Installation) - [使用](#Usage) - [应用接入](#establish_connection!) - [Ruby On Rails 应用初始化设置](#ror-init) - [获取用于上传文件的临时授权URL](#put_auth) - [上传文件](#upload) - [查看文件属性信息](#stat) - [获取文件下载链接（含文件属性信息）](#get) - [只获取文件下载链接](#download) - [删除指定文件](#delete) - [删除所有文件（单个“表”）](#drop) - [批量操作](#batch) - [批量获取文件属性信息（含下载链接）](#batch_get) - [批量获取文件下载链接](#batch_download) - [批量删除文件](#batch_delete) - [创建公开外链](#publish) - [取消公开外链](#unpublish) - [图像处理](#op-image) - [查看图片属性信息](#image_info) - [获取指定规格的缩略图预览地址](#image_preview_url) - [高级图像处理（缩略、裁剪、旋转、转化）](#image_mogrify_preview_url) - [高级图像处理（缩略、裁剪、旋转、转化）并持久化](#image_mogrify_save_as) - [贡献代码](#Contributing) - [许可证](#License) ## 安装 在您 Ruby 应用程序的 `Gemfile` 文件中，添加如下一行代码： gem 'qiniu-rs' 然后，在应用程序所在的目录下，可以运行 `bundle` 安装依赖包： $ bundle 或者，可以使用 Ruby 的包管理器 `gem` 进行安装： $ gem install qiniu-rs ## 使用 ### 应用接入 要接入七牛云存储，您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得： 1. [开通七牛开发者帐号](https://dev.qiniutek.com/signup) 2. [登录七牛开发者自助平台，查看 Access Key 和 Secret Key](https://dev.qiniutek.com/account/keys) 。 在获取到 Access Key 和 Secret Key 之后，您可以在您的程序中调用如下两行代码进行初始化对接： Qiniu::RS.establish_connection! :access_key => YOUR_APP_ACCESS_KEY, :secret_key => YOUR_APP_SECRET_KEY ### Ruby On Rails 应用初始化设置 如果您使用的是 [Ruby on Rails](http://rubyonrails.org/) 框架，我们建议您在应用初始化启动的过程中，依次调用上述两个函数即可，操作如下： 首先，在应用初始化脚本加载的目录中新建一个文件：`YOUR_RAILS_APP/config/initializers/qiniu-rs.rb` 然后，编辑 `YOUR_RAILS_APP/config/initializers/qiniu-rs.rb` 文件内容如下： Qiniu::RS.establish_connection! :access_key => YOUR_APP_ACCESS_KEY, :secret_key => YOUR_APP_SECRET_KEY 这样，您就可以在您的 `RAILS_APP` 中使用七牛云存储 Ruby SDK 提供的其他任意方法了。 接下来，我们会逐一介绍此 SDK 提供的其他方法。 ### 获取用于上传文件的临时授权URL Qiniu::RS.put_auth(expires_in = nil, callback_url = nil) 要上传一个文件，首先需要调用 SDK 提供的 `Qiniu::RS.put_auth` 函数来获取一个经过授权用于临时匿名上传的 URL 。 “临时” 一词表示该 URL 有一定的时效性，即过一段时间后会过期，有效期由传入的参数 `expires_in` 决定，缺省情况下 `expires_in` 的值是 3600 秒，即 1 小时后该上传链接不再有效（但该上传URL在其生成之后的59分59秒都是可用的）。 **参数** expires_in : 可选，整型，用于设置上传 URL 的有效期，单位：秒，缺省为 3600 秒 callback_url : 可选，字符串类型（String），用于设置文件往这个 URL 上传成功后，七牛云存储服务端要回调客户方的业务服务器地址。 **返回值** 如果请求成功，返回一个字符串类型（String）的用于上传文件的已授权的临时有效 URL ，否则返回 `false` 。 **示例** remote_upload_url = Qiniu::RS.put_auth(60, 'http://api.example.com/notifications/qiniu-rs') 如果您的网络程序是从云端（服务端程序）到终端（手持设备应用）的架构模型，且终端用户有使用您移动端App上传文件（比如照片或视频）的需求，可以把您服务器得到的此 `remote_upload_url` 返回给手持设备端的App，然后您的移动 App 可以使用 [七牛云存储 Objective-SDK （iOS）](http://docs.qiniutek.com/v2/sdk/objc/) 或 [七牛云存储 Java-SDK（Android）](http://docs.qiniutek.com/v2/sdk/java/) 的相关上传函数或参照 [七牛云存储API之文件上传](http://docs.qiniutek.com/v2/api/io/#rs-PutFile) 往该 `remote_upload_url` 上传文件。这样，您的终端用户即可把数据（比如图片或视频）直接上传到七牛云存储服务器上无须经由您的服务端中转，而且在上传之前，七牛云存储做了智能加速，终端用户上传数据始终是离他物理距离最近的存储节点。当终端用户上传成功后，七牛云存储服务端会向您指定的 `callback_url` 发送回调数据。在此示例程序中，七牛云存储服务端会将一组关于终端用户上传的数据的属性信息通过 HTTP POST 以 application/x-www-form-urlencoded 编码的方式发送到 `http://api.example.com/notifications/qiniu-rs` 这个地址，假设该地址是您业务服务器用于接收处理回调信息的地址。 ### 上传文件 通过 `Qiniu::RS.put_auth` 函数取得 `remote_upload_url` 之后，即可往该 URL 上传 multipart/form-data 编码格式的数据流。前面讲解了移动 App 拿到 `remote_upload_url` 之后上传数据的流程，如果您的服务端需要上传数据，依然可以使用此 SDK 提供的 `Qiniu::RS.upload` 函数。该函数规格如下： Qiniu::RS.upload :url => remote_upload_url, :file => file_path, :key => record_id, :bucket => bucket_name, :mime_type => file_mime_type, :note => some_notes, :callback_params => {}, :enable_crc32_check => true **参数** :url : 必须，即通过 `Qiniu::RS.put_auth` 函数取得 `remote_upload_url` :file : 必须，字符串类型（String），本地文件可被读取的有效路径 :bucket : 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，指定将该数据属性信息存储到具体的资源表中 。 :key : 必须，字符串类型（String），类似传统数据库里边某个表的主键ID，给每一个文件一个UUID用于进行标示。 :mime_type : 可选，字符串类型（String），文件的 mime-type 值。如若不传入，SDK 会自行计算得出，若计算失败缺省使用 application/octet-stream 代替之。 :note : 可选，字符串类型（String），备注信息。 :callback_params : 可选，k/v 对的 Hash 结构，缺省为：`{:bucket => bucket, :key => key, :mime_type => mime_type}`，用于七牛云存储服务端通过 HTTP POST 以 application/x-www-form-urlencoded 编码的方式发送到 `Qiniu::RS.put_auth` 函数指定的 `callback_url` 。 :enable_crc32_check : 可选，Boolean 类型，是否启用文件上传 crc32 校验，默认为 false 。 **返回值** 上传成功，返回 `true`，否则返回 `false` 。 **针对 NotFound 处理** 您可以上传一个应对 HTTP 404 出错处理的文件，当您 [创建公开外链](#publish) 后，若公开的外链找不到该文件，即可使用您上传的“自定义404文件”代替之。要这么做，您只须使用 `Qiniu::RS.upload` 函数上传一个 `key` 为固定字符串类型的值 `errno-404` 即可。 ### 查看文件属性信息 Qiniu::RS.stat(bucket, key) 可以通过 SDK 提供的 `Qiniu::RS.stat` 函数，来查看某个已上传文件的属性信息。 **参数** bucket : 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，每份数据是属性信息都存储到具体的 bucket（资源表）中 。 key : 必须，字符串类型（String），类似传统数据库里边某个表的主键ID，每一个文件最终都用一个唯一 `key` 进行标示。 **返回值** 如果请求失败，返回 `false`；否则返回如下一个 `Hash` 类型的结构： { "fsize" => 3053, "hash" => "Fu9lBSwQKbWNlBLActdx8-toAajv", "mimeType" => "application/x-ruby", "putTime" => 13372775859344500 } fsize : 表示文件总大小，单位是 Byte hash : 文件的特征值，可以看做是基版本号 mimeType : 文件的 mime-type putTime : 上传时间，单位是 百纳秒 ### 获取文件下载链接（含文件属性信息） Qiniu::RS.get(bucket, key, save_as = nil, expires_in = nil, version = nil) `Qiniu::RS.get` 函数除了能像 `Qiniu::RS.stat` 一样返回文件的属性信息外，还能返回具体的下载链接及其有效时间。 **参数** bucket : 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，每份数据是属性信息都存储到具体的 bucket（资源表）中 。 key : 必须，字符串类型（String），类似传统数据库里边某个表的主键ID，每一个文件最终都用一个唯一 `key` 进行标示。 save_as : 可选，字符串类型（String），文件下载时保存的具体名称 expires_in : 可选，整型，用于设置下载 URL 的有效期，单位：秒，缺省为 3600 秒 version : 可选，字符串类型（String），值为 `Qiniu::RS.stat` 或 `Qiniu::RS.get` 函数返回的 `hash` 字段的值，可用于断点续下载。 **返回值** 如果请求失败，返回 `false`；否则返回如下一个 `Hash` 类型的结构： { "fsize" => 3053, "hash" => "Fu9lBSwQKbWNlBLActdx8-toAajv", "mimeType" => "application/x-ruby", "url" => "http://iovip.qbox.me/file/", "expires" => 3600 } fsize : 表示文件总大小，单位是 Byte hash : 文件的特征值，可以看做是基版本号 mimeType : 文件的 mime-type url : 文件的临时有效下载链接 expires : 文件下载链接的有效期，单位为 秒，过了 `expires` 秒之后，下载 `url` 将不再有效 ### 只获取文件下载链接 Qiniu::RS.download(bucket, key, save_as = nil, expires_in = nil, version = nil) `Qiniu::RS.download` 函数参数与 `Qiniu::RS.get` 一样，差别在于，`Qiniu::RS.download` 只返回文件的下载链接。 ### 删除指定文件 Qiniu::RS.delete(bucket, key) `Qiniu::RS.delete` 函数提供了从指定的 `bucket` 中删除指定的 `key`，即删除 `key` 索引关联的具体文件。 **参数** bucket : 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，每份数据是属性信息都存储到具体的 bucket（资源表）中 。 key : 必须，字符串类型（String），类似传统数据库里边某个表的主键ID，每一个文件最终都用一个唯一 `key` 进行标示。 **返回值** 如果删除成功，返回 `true`，否则返回 `false` 。 ### 删除所有文件（单个“表”） Qiniu::RS.drop(bucket) `Qiniu::RS.drop` 提供了删除整个 `bucket` 及其里边的所有 `key`，以及这些 `key` 关联的所有文件都将被删除。 **参数** bucket : 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，每份数据是属性信息都存储到具体的 bucket（资源表）中 。 **返回值** 如果删除成功，返回 `true`，否则返回 `false` 。 ### 批量操作 Qiniu::RS.batch(command, bucket, keys) SDK 还提供了 `Qiniu::RS.batch` 函数来提供批量处理 `Qiniu::RS.stat` 或是 `Qiniu::RS.get` 或 `Qiniu::RS.delete` 的相应功能。 **参数** command : 必须，字符串类型（String），其值可以是 `stat`, `get`, `delete` 中的一种 bucket : 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，每份数据是属性信息都存储到具体的 bucket（资源表）中 。 keys : 必须，数组类型（Array），所要操作 `key` 的集合。 **返回值** 如果请求失败，返回 `false`，否则返回一个 `Array` 类型的结构，其中每个元素是一个 `Hash` 类型的结构。例如批量`get`： [ { "code" => 200, "data" => { "expires" => 3600, "fsize" => 3053, "hash" => "Fu9lBSwQKbWNlBLActdx8-toAajv", "mimeType" => "application/x-ruby", "url" => "http://iovip.qbox.me/file/" } }, ... ] #### 批量获取文件属性信息（含下载链接） Qiniu::RS.batch_get(bucket, keys) `Qiniu::RS.batch_get` 函数是在 `Qiniu::RS.batch` 之上的封装，提供批量获取文件属性信息（含下载链接）的功能。 **参数** bucket : 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，每份数据是属性信息都存储到具体的 bucket（资源表）中 。 keys : 必须，数组类型（Array），所要操作 `key` 的集合。 **返回值** 如果请求失败，返回 `false`，否则返回一个 `Array` 类型的结构，其中每个元素是一个 `Hash` 类型的结构。`Hash` 类型的值同 `Qiniu::RS.get` 函数的返回值类似，只多出一个 `code` 字段，`code` 为 200 表示所有 keys 全部获取成功，`code` 若为 298 表示部分获取成功。 [ { "code" => 200, "data" => { "expires" => 3600, "fsize" => 3053, "hash" => "Fu9lBSwQKbWNlBLActdx8-toAajv", "mimeType" => "application/x-ruby", "url" => "http://iovip.qbox.me/file/" } }, ... ] #### 批量获取文件下载链接 Qiniu::RS.batch_download(bucket, keys) `Qiniu::RS.batch_download` 函数也是在 `Qiniu::RS.batch` 之上的封装，提供批量获取文件下载链接的功能。 参数同 `Qiniu::RS.batch_get` 的参数一样。 **返回值** 如果请求失败，返回 `false`，否则返回一个 `Array` 类型的结构，其中每个元素是一个字符串类型的下载链接： ["", "", …, ""] #### 批量删除文件 Qiniu::RS.batch_delete(bucket, keys) `Qiniu::RS.batch_download` 函数也是在 `Qiniu::RS.batch` 之上的封装，提供批量删除文件的功能。 参数同 `Qiniu::RS.batch_get` 的参数一样。 **返回值** 如果批量删除成功，返回 `true` ，否则为 `false` 。 ### 创建公开外链 Qiniu::RS.publish(domain, bucket) 调用 `Qiniu::RS.publish` 函数可以将您在七牛云存储中的资源表 `bucket` 发布到某个 `domain` 下，`domain` 需要在 DNS 管理里边 CNAME 到 `iovip.qbox.me` 。 这样，用户就可以通过 `http:///` 来访问资源表 `bucket` 中的文件。键值为 `foo/bar/file` 的文件对应访问 URL 为 `http:///foo/bar/file`。 另外，`domain` 可以是一个真实的域名，比如 `www.example.com`，也可以是七牛云存储的二级路径，比如 `io.qbox.me/example` 。 例如：执行 `Qiniu::RS.publish("cdn.example.com", "EXAMPLE_BUCKET")` 后，那么键名为 `foo/bar/file` 的文件可以通过 `http://cdn.example.com/foo/bar/file` 访问。 **参数** domain : 必须，字符串类型（String），资源表发布的目标域名，例如：`cdn.example.com` bucket : 必须，字符串类型（String），要公开发布的资源表名称。 **返回值** 如果发布成功，返回 `true`，否则返回 `false` 。 ### 取消公开外链 Qiniu::RS.unpublish(domain) 可以通过 SDK 提供的 `Qiniu::RS.unpublish` 函数来取消指定 `bucket` 的在某个 `domain` 域下的所有公开外链访问。 **参数** domain : 必须，字符串类型（String），资源表已发布的目标域名名称，例如：`cdn.example.com` **返回值** 如果撤销成功，返回 `true`，否则返回 `false` 。 ### 图像处理 #### 查看图片属性信息 Qiniu::RS.image_info(url) 使用 SDK 提供的 `Qiniu::RS.image_info` 方法，可以基于一张存储于七牛云存储服务器上的图片，针对其下载链接来获取该张图片的属性信息。 **参数** url : 必须，字符串类型（String），图片的下载链接，需是 `Qiniu::RS.get`（或`Qiniu::RS.batch_get`）函数返回值中 `url` 字段的值，或者是 `Qiniu::RS.download`（或`Qiniu::RS.batch_download`）函数返回的下载链接。且文件本身必须是图片。 **返回值** 如果请求失败，返回 `false`；否则，返回如下一个 `Hash` 类型的结构： { "format" => "jpeg", "width" => 640, "height" => 425, "colorModel" => "ycbcr" } format : 原始图片类型 width : 原始图片宽度，单位像素 height : 原始图片高度，单位像素 colorModel : 原始图片着色模式 #### 获取指定规格的缩略图预览地址 Qiniu::RS.image_preview_url(url, spec) 使用 SDK 提供的 `Qiniu::RS.image_preview_url` 方法，可以基于一张存储于七牛云存储服务器上的图片，针对其下载链接，以及指定的缩略图规格类型，来获取该张图片的缩略图地址。 **参数** url : 必须，字符串类型（String），图片的下载链接，需是 `Qiniu::RS.get`（或`Qiniu::RS.batch_get`）函数返回值中 `url` 字段的值，或者是 `Qiniu::RS.download`（或`Qiniu::RS.batch_download`）函数返回的下载链接。且文件本身必须是图片。 spec : 可选，字符串或整型的枚举值，指定缩略图的具体规格，参考 [七牛云存储API之缩略图预览](/v2/api/foimg/#fo-imagePreview) 和 [自定义缩略图规格](/v2/api/foimg/#fo-imagePreviewEx) 。该值缺省为 0 （即输出宽800px高600px图片质量为85的缩略图） **返回值** 返回一个字符串类型的缩略图 URL #### 高级图像处理（缩略、裁剪、旋转、转化） `Qiniu::RS.image_mogrify_preview_url()` 方法支持将一个存储在七牛云存储的图片进行缩略、裁剪、旋转和格式转化处理，该方法返回一个可以直接预览缩略图的URL。 image_mogrify_preview_url = Qiniu::RS.image_mogrify_preview_url(source_image_url, mogrify_options) **参数** source_image_url : 必须，字符串类型（string），指定原始图片的下载链接，可以根据 rs.get() 获取到。 mogrify_options : 必须，Hash Map 格式的图像处理参数。 `mogrify_options` 对象具体的规格如下： mogrify_options = { :thumbnail => , :gravity => , =NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast :crop => , :quality => , :rotate => , :format => , =jpg, gif, png, tif, etc. :auto_orient => } `Qiniu::RS.image_mogrify_preview_url()` 方法是对七牛云存储图像处理高级接口的完整包装，关于 `mogrify_options` 参数里边的具体含义和使用方式，可以参考文档：[图像处理高级接口](#/v2/api/foimg/#fo-imageMogr)。 **返回值** 返回一个可以预览最终缩略图的URL，String 类型。 #### 高级图像处理（缩略、裁剪、旋转、转化）并持久化存储处理结果 `Qiniu::RS.image_mogrify_save_as()` 方法支持将一个存储在七牛云存储的图片进行缩略、裁剪、旋转和格式转化处理，并且将处理后的缩略图作为一个新文件持久化存储到七牛云存储服务器上，这样就可以供后续直接使用而不用每次都传入参数进行图像处理。 result = Qiniu::RS.image_mogrify_save_as(target_bucket, target_key, src_img_url, mogrify_options) **参数** target_bucket : 必须，字符串类型（string），指定最终缩略图要存放的 bucket 。 target_key : 必须，字符串类型（string），指定最终缩略图存放在云存储服务端的唯一文件ID。 src_img_url : 必须，字符串类型（string），指定原始图片的下载链接，可以根据 rs.get() 获取到。 mogrify_options : 必须，Hash Map 格式的图像处理参数。 `mogrify_options` 对象具体的规格如下： mogrify_options = { :thumbnail => , :gravity => , =NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast :crop => , :quality => , :rotate => , :format => , =jpg, gif, png, tif, etc. :auto_orient => } `Qiniu::RS::Image.mogrify_preview_url()` 方法是对七牛云存储图像处理高级接口的完整包装，关于 `mogrify_options` 参数里边的具体含义和使用方式，可以参考文档：[图像处理高级接口](#/v2/api/foimg/#fo-imageMogr)。 **返回值** 如果请求失败，返回 `false`；否则，返回如下一个 `Hash` 类型的结构： {"hash" => "FrOXNat8VhBVmcMF3uGrILpTu8Cs"} 示例代码： data = Qiniu::RS.get("", "") src_img_url = data["url"] target_bucket = "test_thumbnails_bucket" target_key = "cropped-" + @test_image_key mogrify_options = { :thumbnail => "!120x120r", :gravity => "center", :crop => "!120x120a0a0", :quality => 85, :rotate => 45, :format => "jpg", :auto_orient => true } result = Qiniu::RS.image_mogrify_save_as(target_bucket, target_key, src_img_url, mogrify_options) if result thumbnail = Qiniu::RS.get(target_bucket, target_key) puts thumbnail["url"] # 您可以选择将存放缩略图的 bucket 公开，这样就可以直接以外链的形式访问到缩略图，而不用走API获取下载URL。 result = Qiniu::RS.publish("pic.example.com", target_bucket) # 然后将 pic.example.com CNAME 到 iovip.qbox.me ，就可以直接以如下方式访问缩略图 # [GET] http://pic.example.com/ end ## 贡献代码 七牛云存储 Ruby SDK 源码地址：[https://github.com/qiniu/ruby-sdk](https://github.com/qiniu/ruby-sdk) 1. 登录 [github.com](https://github.com) 2. Fork [https://github.com/qiniu/ruby-sdk](https://github.com/qiniu/ruby-sdk) 3. 创建您的特性分支 (`git checkout -b my-new-feature`) 4. 提交您的改动 (`git commit -am 'Added some feature'`) 5. 将您的改动记录提交到远程 `git` 仓库 (`git push origin my-new-feature`) 6. 然后到 github 网站的该 `git` 远程仓库的 `my-new-feature` 分支下发起 Pull Request ## 许可证 Copyright (c) 2012 qiniutek.com 基于 MIT 协议发布: * [www.opensource.org/licenses/MIT](http://www.opensource.org/licenses/MIT)