aliyun-sdk 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8d7df8217a8d711e910788b4478a63a9de6d3d19
+  data.tar.gz: 4a675680ae738c788a650425002973a1a90e27ac
+SHA512:
+  metadata.gz: f82087353b70116909deaf0453bc4b65c213dfb37e8566d8a99f3ab1bc8e93dc6704c5c918400cfbe9c4799aa06e69d10eb45ab2d7e530e4f25864a6f189a92f
+  data.tar.gz: e61556df4633d1f99354d05078fbffd70c7ecbc13b44e3606553230d9faa4a969195a4f1aa2f4cd4a3602491ef8a89d6a17635c83e5a88e04f0ae9a8c63a0fb6

data/README.md

@@ -0,0 +1,364 @@
+# Aliyun OSS SDK for Ruby
+
+![Build Status](http://cise.alibaba-inc.com/task/119062/build/10/status.svg)
+
+-----
+
+Aliyun::OSS是用于方便访问阿里云OSS（Object Storage Service）RESTful
+API的Ruby客户端程序。了解OSS的的更多信息请访问OSS官网：
+http://www.aliyun.com/product/oss
+
+## 运行环境
+
+- Ruby版本 >= 1.9.2
+- 支持Ruby运行环境的Windows/Linux/OS X
+
+安装Ruby请参考：https://www.ruby-lang.org/zh_cn/downloads/
+
+## 快速开始
+
+### 开通OSS账号
+
+登录官网：http://www.aliyun.com/product/oss ，点击“立即开通”。按照提示
+开通OSS服务。开通服务之后请在“管理控制台”中查看您的AccessKeyId和
+AccessKeySecret，在使用Aliyun OSS SDK时需要提供您的这两个信息。
+
+### 安装Aliyun OSS SDK for Ruby
+
+    gem install aliyun-sdk
+
+并在你的程序中或者`irb`命令下包含：
+
+    require 'aliyun/oss'
+
+**注意：**
+
+1. SDK依赖的一些gem是本地扩展的形式，因此安装完Ruby之后还需要安装
+   ruby-dev以支持编译本地扩展的gem
+2. SDK依赖的处理XML的gem(nokogiri)要求环境中包含zlib库
+
+以Ubuntu为例，安装上述依赖的方法：
+
+    sudo apt-get install ruby-dev
+    sudo apt-get install zlib1g-dev
+
+其他系统类似。
+
+### 创建Client
+
+    client = Aliyun::OSS::Client.new(
+      :endpoint => endpoint,
+      :access_key_id => 'access_key_id',
+      :access_key_secret => 'access_key_secret')
+
+其中`endpoint`是OSS服务的地址，根据节点区域不同，这个地址可能不一样，例如
+杭州节点的地址是：`http://oss-cn-hangzhou.oss.aliyuncs.com`，其他节点的地址见：
+[节点列表][1]
+
+`access_key_id`和`access_key_secret`是您的服务凭证，在官网的“管理控制
+台”上面可以查看。**请妥善保管您的AccessKeySecret，泄露之后可能影响您的
+数据安全**
+
+#### 使用用户绑定的域名作为endpoint
+
+OSS支持自定义域名绑定，允许用户将自己的域名指向阿里云OSS的服务地址
+（CNAME），这样用户迁移到OSS上时应用内资源的路径可以不用修改。绑定的域
+名指向OSS的一个bucket。绑定域名的操作只能在OSS控制台进行。更多关于自定
+义域名绑定的内容请到官网了解：[OSS自定义域名绑定][2]
+
+用户绑定了域名后，使用SDK时指定的endpoint可以使用标准的OSS服务地址，也
+可以使用用户绑定的域名：
+
+    client = Aliyun::OSS::Client.new(
+      :endpoint => 'http://img.my-domain.com',
+      :access_key_id => 'access_key_id',
+      :access_key_secret => 'access_key_secret',
+      :cname => true)
+
+有以下几点需要注意：
+
+1. 在Client初始化时必须指定:cname为true
+2. 自定义域名绑定了OSS的一个bucket，所以用这种方式创建的client不能进行
+   list_buckets操作
+3. 在{Aliyun::OSS::Client#get_bucket}时仍需要指定bucket名字，并且要与
+   域名所绑定的bucket名字相同
+
+### 列出当前所有的Bucket
+
+    buckets = client.list_buckets
+    buckets.each{ |b| puts b.name }
+
+`list_buckets`返回的是一个迭代器，用户依次获取每个Bucket的信息。Bucket
+对象的结构请查看API文档中的{Aliyun::OSS::Bucket}
+
+### 创建一个Bucket
+
+    bucket = client.create_bucket('my-bucket')
+
+### 列出Bucket中所有的Object
+
+    bucket = client.get_bucket('my-bucket')
+    objects = bucket.list_objects
+    objects.each{ |o| puts o.key }
+
+`list_objects`返回的是一个迭代器，用户依次获取每个Object的信息。Object
+对象的结构请查看API文档中的{Aliyun::OSS::Object}
+
+### 在Bucket中创建一个Object
+
+    bucket.put_object(object_key){ |stream| stream << 'hello world' }
+
+用户也可以通过上传本地文件创建一个Object：
+
+    bucket.put_object(object_key, :file => local_file)
+
+### 从Bucket中下载一个Object
+
+    bucket.get_object(object_key){ |content| puts content }
+
+用户也可以将Object下载到本地文件中：
+
+    bucket.get_object(object_key, :file => local_file)
+
+### 拷贝Object
+
+    bucket.copy_object(from_key, to_key)
+
+### 判断一个Object是否存在
+
+    bucket.object_exists?(object_key)
+
+更多Bucket的操作请参考API文档中的{Aliyun::OSS::Bucket}
+
+## 模拟目录结构
+
+OSS是Object存储服务，本身不支持目录结构，所有的object都是“平”的。但是
+用户可以通过设置object的key为"/foo/bar/file"这样的形式来模拟目录结构。
+假设现在有以下Objects：
+
+    /foo/x
+    /foo/bar/f1
+    /foo/bar/dir/file
+    /foo/hello/file
+
+列出"/foo/"目录下的所有文件就是以"/foo/"为prefix进行`list_objects`，但
+是这样也会把"/foo/bar/"下的所有object也列出来。为此需要用到delimiter参
+数，其含义是从prefix往后遇到第一个delimiter时停止，这中间的key作为
+Object的common prefix，包含在`list_objects`的结果中。
+
+    objs = bucket.list_objects(:prefix => '/foo/', :delimiter => '/')
+    objs.each do |i|
+      if i.is_a?(Object) # a object
+        puts "object: #{i.key}"
+      else
+        puts "common prefix: #{i}"
+      end
+    end
+    # output
+    object: /foo/x
+    common prefix: /foo/bar/
+    common prefix: /foo/hello/
+
+Common prefix让用户不需要遍历所有的object（可能数量巨大）而找出前缀，
+在模拟目录结构时非常有用。
+
+## 断点上传/下载
+
+OSS支持大文件的存储，用户如果上传/下载大文件(Object)的时候中断了（网络
+闪断、程序崩溃、机器断电等），重新上传/下载是件很费资源的事情。OSS支持
+Multipart的功能，可以在上传/下载时将大文件进行分片传输。Aliyun OSS SDK
+基于此提供了断点上传/下载的功能。如果发生中断，可以从上次中断的地方继
+续进行上传/下载。对于文件大小超过100MB的文件，都建议采用断点上传/下载
+的方式进行。
+
+### 断点上传
+
+    bucket.resumable_upload(object_key, local_file, :cpt_file => cpt_file)
+
+其中`:cpt_file`指定保存上传中间状态的checkpoint文件所在的位置，如果用户
+没有指定，SDK将为用户在`local_file`所在的目录生成一个
+`local_file.cpt`。上传中断后，只需要提供相同的cpt文件，上传将会从
+中断的点继续上传。所以典型的上传代码是：
+
+    retry_times = 5
+    retry_times.times do
+      begin
+        bucket.resumable_upload(object_key, local_file)
+      rescue => e
+        logger.error(e.message)
+      end
+    end
+
+注意：
+
+1. SDK会将上传的中间状态信息记录在cpt文件中，所以要确保用户对cpt文
+   件有写权限
+2. cpt文件记录了上传的中间状态信息并自带了校验，用户不能去编辑它，如
+   果cpt文件损坏则上传无法继续。整个上传完成后cpt文件会被删除。
+
+### 断点下载
+
+    bucket.resumable_download(object_key, local_file, :cpt_file => cpt_file)
+
+其中`:cpt_file`指定保存下载中间状态的checkpoint文件所在的位置，如果用户
+没有指定，SDK将为用户在`local_file`所在的目录生成一个
+`local_file.cpt`。下载中断后，只需要提供相同的cpt文件，下载将会从
+中断的点继续下载。所以典型的下载代码是：
+
+    retry_times = 5
+    retry_times.times do
+      begin
+        bucket.resumable_download(object_key, local_file)
+      rescue => e
+        logger.error(e.message)
+      end
+    end
+
+注意：
+
+1. 在下载过程中，对于下载完成的每个分片，会在`local_file`所在的目录生
+   成一个`local_file.part.N`的临时文件。整个下载完成后这些文件会被删除。
+   用户不能去编辑或删除part文件，否则下载不能继续。
+2. SDK会将下载的中间状态信息记录在cpt文件中，所以要确保用户对cpt文
+   件有写权限
+3. cpt文件记录了下载的中间状态信息并自带了校验，用户不能去编辑它，如
+   果cpt文件损坏则下载无法继续。整个下载完成后cpt文件会被删除。
+
+
+## 可追加的文件
+
+阿里云OSS中的Object分为两种类型：Normal和Appendable。
+
+- 对于Normal Object，每次上传都是作为一个整体，如果一个Object已存在，
+  两次上传相同key的Object将会覆盖原有的Object
+- 对于Appendable Object，第一次通过`append_object`创建它，后续的
+  `append_object`不会覆盖原有的内容，而是在Object末尾追加内容
+- 不能向Normal Object追加内容
+- 不能拷贝一个Appendable Object
+
+### 创建一个Appendable Object
+
+    bucket.append_object(object_key, 0){ |stream| stream << "hello world" }
+
+第二个参数是追加的位置，对一个Object第一次追加时，这个参数为0。后续的
+追加这个参数要求是追加前Object的长度。
+
+当然，也可以从文件中读取追加的内容：
+
+    bucket.append_object(object_key, 0, :file => local_file)
+
+### 向Object追加内容
+
+    pos = bucket.get_object_meta(object_key).size
+    next_pos = bucket.append_object(object_key, pos, :file => local_file)
+
+程序第一次追加时，可以通过{Aliyun::OSS::Bucket#get_object_meta}获取文件的长度，
+后续追加时，可以根据{Aliyun::OSS::Bucket#append_object}返回的下次追加长度。
+
+注意：如果并发地`append_object`，`next_pos`并不总是对的。
+
+## Object meta信息
+
+在上传Object时，除了Object内容，OSS还允许用户为Object设置一些"meta信息
+"，这些meta信息是一个个的Key-Value对，用于标识Object特有的属性信息。这
+些meta信息会跟Object一起存储，并在`get_object`和`get_object_meta`时返
+回给用户。
+
+    bucket.put_object(object_key, :file => local_file,
+                      :metas => {
+                        'key1' => 'value1',
+                        'key2' => 'value2'})
+
+    obj = bucket.get_object(object_key, :file => localfile)
+    puts obj.metas
+
+关于meta信息有以下几点需要注意：
+1. meta信息的key和value都只能是简单的ASCII非换行字符，并且总的大小不能超过8KB。
+2. Copy object时默认将拷贝源object的meta信息，如果用户不希望这么做，需要
+   显式地将`:meta_directive`设置成{Aliyun::OSS::MetaDirective::REPLACE}
+
+## 权限控制
+
+OSS允许用户对Bucket和Object分别设置访问权限，方便用户控制自己的资源可
+以被如何访问。对于Bucket，有三种访问权限：
+
+- public-read-write 允许匿名用户向该Bucket中创建/获取/删除Object
+- public-read 允许匿名用户获取该Bucket中的Object
+- private 不允许匿名访问，所有的访问都要经过签名
+
+创建Bucket时，默认是private权限。之后用户可以通过`bucket.acl=`来设置
+Bucket的权限。
+
+    bucket.acl = Aliyun::OSS::ACL::PUBLIC_READ
+    puts bucket.acl # public-read
+
+对于Object，有四种访问权限：
+
+- default 继承所属的Bucket的访问权限，即与所属Bucket的权限值一样
+- public-read-write 允许匿名用户读写该Object
+- public-read 允许匿名用户读该Object
+- private 不允许匿名访问，所有的访问都要经过签名
+
+创建Object时，默认为default权限。之后用户可以通过
+`bucket.set_object_acl`来设置Object的权限。
+
+    acl = bucket.get_object_acl(object_key)
+    puts acl # default
+    bucket.set_object_acl(object_key, Aliyun::OSS::ACL::PUBLIC_READ)
+    acl = bucket.get_object_acl(object_key)
+    puts acl # public-read
+
+需要注意的是：
+
+1. 如果设置了Object的权限，则访问该Object时进行权限认证时会优先判断
+   Object的权限，而Bucket的权限设置会被忽略。
+2. 允许匿名访问时（设置了public-read或者public-read-write权限），用户
+   可以直接通过浏览器访问，例如：
+
+        http://bucket-name.oss-cn-hangzhou.aliyuncs.com/object.jpg
+
+3. 访问具有public权限的Bucket/Object时，也可以通过创建匿名的Client来进行：
+
+        # 不填access_key_id和access_key_secret，将创建匿名Client，只能访问
+        # 具有public权限的Bucket/Object
+        client = Client.new(:endpoint => 'oss-cn-hangzhou.aliyuncs.com')
+        bucket = client.get_bucket('public-bucket')
+        obj = bucket.get_object('public-object', :file => local_file)
+
+## 运行examples
+
+SDK的examples/目录下有一些展示SDK功能的示例程序，用户稍加配置就可以直
+接运行。examples需要的权限信息和bucket信息从用户`HOME`目录下的配置文件
+`~/.oss.yml`中读取，其中应该包含以下字段：
+
+    endpoint: oss-cn-hangzhou.aliyuncs.com
+    cname: false
+    id: ACCESS KEY ID
+    key: ACCESS KEY SECRET
+    bucket: BUCKET NAME
+
+用户需要创建（如果不存在）或者修改其中的内容，然后运行：
+
+    ruby examples/aliyun/oss/bucket.rb
+
+## 运行测试
+
+SDK采用rspec进行测试，如果要对SDK进行修改，请确保没有break现有测试。测
+试运行的方法是，在ruby-sdk/目录下运行：
+
+    rspec
+
+或者用bundle和rake：
+
+    bundle exec rake spec
+
+## 更多
+
+更多文档请查看：
+
+- 阿里云官网文档：http://help.aliyun.com/product/8314910_oss.html
+
+
+[1]: http://help.aliyun.com/document_detail/oss/product-documentation/domain-region.html
+
+[2]: http://help.aliyun.com/document_detail/oss/product-documentation/function/cname.html

data/lib/aliyun/oss.rb

@@ -0,0 +1,17 @@
+# -*- encoding: utf-8 -*-
+
+require_relative 'oss/version'
+require_relative 'oss/logging'
+require_relative 'oss/util'
+require_relative 'oss/exception'
+require_relative 'oss/struct'
+require_relative 'oss/config'
+require_relative 'oss/http'
+require_relative 'oss/protocol'
+require_relative 'oss/multipart'
+require_relative 'oss/upload'
+require_relative 'oss/download'
+require_relative 'oss/iterator'
+require_relative 'oss/object'
+require_relative 'oss/bucket'
+require_relative 'oss/client'

data/lib/aliyun/oss/bucket.rb

@@ -0,0 +1,555 @@
+# -*- encoding: utf-8 -*-
+
+module Aliyun
+  module OSS
+    ##
+    # Bucket是用户的Object相关的操作的client，主要包括三部分功能：
+    # 1. bucket相关：获取/设置bucket的属性（acl, logging, referer,
+    #    website, lifecycle, cors）
+    # 2. object相关：上传、下载、追加、拷贝object等
+    # 3. multipart相关：断点续传、断点续载
+    class Bucket < Struct::Base
+
+      attrs :name, :location, :creation_time
+
+      def initialize(opts = {}, protocol = nil)
+        super(opts)
+        @protocol = protocol
+      end
+
+      ### Bucket相关的API ###
+
+      # 获取Bucket的ACL
+      # @return [String] Bucket的{OSS::ACL ACL}
+      def acl
+        @protocol.get_bucket_acl(name)
+      end
+
+      # 设置Bucket的ACL
+      # @param acl [String] Bucket的{OSS::ACL ACL}
+      def acl=(acl)
+        @protocol.put_bucket_acl(name, acl)
+      end
+
+      # 获取Bucket的logging配置
+      # @return [BucketLogging] Bucket的logging配置
+      def logging
+        @protocol.get_bucket_logging(name)
+      end
+
+      # 设置Bucket的logging配置
+      # @param logging [BucketLogging] logging配置
+      def logging=(logging)
+        if logging.enabled?
+          @protocol.put_bucket_logging(name, logging)
+        else
+          @protocol.delete_bucket_logging(name)
+        end
+      end
+
+      # 获取Bucket的website配置
+      # @return [BucketWebsite] Bucket的website配置
+      def website
+        begin
+          w = @protocol.get_bucket_website(name)
+        rescue ServerError => e
+          raise unless e.http_code == 404
+        end
+
+        w || BucketWebsite.new
+      end
+
+      # 设置Bucket的website配置
+      # @param website [BucketWebsite] website配置
+      def website=(website)
+        if website.enabled?
+          @protocol.put_bucket_website(name, website)
+        else
+          @protocol.delete_bucket_website(name)
+        end
+      end
+
+      # 获取Bucket的Referer配置
+      # @return [BucketReferer] Bucket的Referer配置
+      def referer
+        @protocol.get_bucket_referer(name)
+      end
+
+      # 设置Bucket的Referer配置
+      # @param referer [BucketReferer] Referer配置
+      def referer=(referer)
+        @protocol.put_bucket_referer(name, referer)
+      end
+
+      # 获取Bucket的生命周期配置
+      # @return [Array<OSS::LifeCycleRule>] Bucket的生命周期规则，如果
+      #  当前Bucket未设置lifecycle，则返回[]
+      def lifecycle
+        begin
+          r = @protocol.get_bucket_lifecycle(name)
+        rescue ServerError => e
+          raise unless e.http_code == 404
+        end
+
+        r || []
+      end
+
+      # 设置Bucket的生命周期配置
+      # @param rules [Array<OSS::LifeCycleRule>] 生命
+      #  周期配置规则
+      # @see OSS::LifeCycleRule 查看如何设置生命周期规则
+      # @note 如果rules为空，则会删除这个bucket上的lifecycle配置
+      def lifecycle=(rules)
+        if rules.empty?
+          @protocol.delete_bucket_lifecycle(name)
+        else
+          @protocol.put_bucket_lifecycle(name, rules)
+        end
+      end
+
+      # 获取Bucket的跨域资源共享(CORS)的规则
+      # @return [Array<OSS::CORSRule>] Bucket的CORS规则，如果当前
+      #  Bucket未设置CORS规则，则返回[]
+      def cors
+        begin
+          r = @protocol.get_bucket_cors(name)
+        rescue ServerError => e
+          raise unless e.http_code == 404
+        end
+
+        r || []
+      end
+
+      # 设置Bucket的跨域资源共享(CORS)的规则
+      # @param rules [Array<OSS::CORSRule>] CORS规则
+      # @note 如果rules为空，则会删除这个bucket上的CORS配置
+      def cors=(rules)
+        if rules.empty?
+          @protocol.delete_bucket_cors(name)
+        else
+          @protocol.set_bucket_cors(name, rules)
+        end
+      end
+
+      ### Object相关的API ###
+
+
+      # 列出bucket中的object
+      # @param opts [Hash] 查询选项
+      # @option opts [String] :prefix 返回的object的前缀，如果设置则只
+      #  返回那些名字以它为前缀的object
+      # @option opts [String] :delimiter 用于获取公共前缀的分隔符，从
+      #  前缀后面开始到第一个分隔符出现的位置之前的字符，作为公共前缀。
+      # @example
+      #  假设我们有如下objects:
+      #     /foo/bar/obj1
+      #     /foo/bar/obj2
+      #     ...
+      #     /foo/bar/obj9999999
+      #     /foo/xxx/
+      #  用'foo/'作为前缀, '/'作为分隔符, 则得到的公共前缀是：
+      #  '/foo/bar/', '/foo/xxx/'。它们恰好就是目录'/foo/'下的所有子目
+      #  录。用delimiter获取公共前缀的方法避免了查询当前bucket下的所有
+      #   object（可能数量巨大），是用于模拟目录结构的常用做法。
+      # @option opts [String] :encoding 指定返回的响应中object名字的编
+      #  码方法，目前只支持{OSS::KeyEncoding::URL}编码方式。
+      # @return [Enumerator<Object>] 其中Object可能是{OSS::Object}，也
+      #  可能是{String}，此时它是一个公共前缀
+      # @example
+      #  all = bucket.list_objects
+      #  all.each do |i|
+      #    if i.is_a?(Object)
+      #      puts "Object: #{i.key}"
+      #    else
+      #      puts "Common prefix: #{i}"
+      #    end
+      #  end
+      def list_objects(opts = {})
+        Iterator::Objects.new(@protocol, name, opts).to_enum
+      end
+
+      # 向Bucket中上传一个object
+      # @param key [String] Object的名字
+      # @param opts [Hash] 上传object时的选项（可选）
+      # @option opts [String] :file 设置所上传的文件
+      # @option opts [String] :content_type 设置所上传的内容的
+      #  Content-Type，默认是application/octet-stream
+      # @option opts [Hash] :metas 设置object的meta，这是一些用户自定
+      #  义的属性，它们会和object一起存储，在{#get_object_meta}的时候会
+      #  返回这些meta。属性的key不区分大小写。例如：{ 'year' => '2015' }
+      # @yield [HTTP::StreamWriter] 如果调
+      #  用的时候传递了block，则写入到object的数据由block指定
+      # @example 流式上传数据
+      #   put_object('x'){ |stream| 100.times { |i| stream << i.to_s } }
+      #   put_object('x'){ |stream| stream << get_data }
+      # @example 上传文件
+      #   put_object('x', :file => '/tmp/x')
+      # @example 指定Content-Type和metas
+      #   put_object('x', :file => '/tmp/x', :content_type => 'text/html',
+      #              :metas => {'year' => '2015', 'people' => 'mary'})
+      # @note 采用streaming的方式时，提供的数据必须是有结束标记的数据。
+      #  因为put_object会不断地从StreamWriter中读取数据上传到OSS，直到
+      #  它读到的数据为nil停止。
+      # @note 如果opts中指定了:file，则block会被忽略
+      def put_object(key, opts = {}, &block)
+        file = opts[:file]
+        if file
+          opts[:content_type] = get_content_type(file)
+
+          @protocol.put_object(name, key, opts) do |sw|
+            File.open(File.expand_path(file), 'rb') do |f|
+              sw << f.read(Protocol::STREAM_CHUNK_SIZE) until f.eof?
+            end
+          end
+        else
+          @protocol.put_object(name, key, opts, &block)
+        end
+      end
+
+      # 从Bucket中下载一个object
+      # @param key [String] Object的名字
+      # @param opts [Hash] 下载Object的选项（可选）
+      # @option opts [Array<Integer>] :range 指定下载object的部分数据，
+      #  range应只包含两个数字，表示一个*左开右闭*的bytes range
+      # @option opts [String] :file 指定将下载的object写入到文件中
+      # @option opts [Hash] :condition 指定下载object需要满足的条件
+      #   * :if_modified_since (Time) 指定如果object的修改时间晚于这个值，则下载
+      #   * :if_unmodified_since (Time) 指定如果object从这个时间后再无修改，则下载
+      #   * :if_match_etag (String) 指定如果object的etag等于这个值，则下载
+      #   * :if_unmatch_etag (String) 指定如果object的etag不等于这个值，则下载
+      # @option opts [Hash] :rewrite 指定下载object时Server端返回的响应头部字段的值
+      #   * :content_type (String) 指定返回的响应中Content-Type的值
+      #   * :content_language (String) 指定返回的响应中Content-Language的值
+      #   * :expires (Time) 指定返回的响应中Expires的值
+      #   * :cache_control (String) 指定返回的响应中Cache-Control的值
+      #   * :content_disposition (String) 指定返回的响应中Content-Disposition的值
+      #   * :content_encoding (String) 指定返回的响应中Content-Encoding的值
+      # @return [OSS::Object] 返回Object对象
+      # @yield [String] 如果调用的时候传递了block，则获取到的object的数据交由block处理
+      # @example 流式下载文件
+      #   get_object('x'){ |chunk| handle_chunk_data(chunk) }
+      # @example 下载到本地文件
+      #   get_object('x', :file => '/tmp/x')
+      # @example 指定检查条件
+      #   get_object('x', :file => '/tmp/x', :condition => {:if_match_etag => 'etag'})
+      # @example 指定重写响应的header信息
+      #   get_object('x', :file => '/tmp/x', :rewrite => {:content_type => 'text/html'})
+      # @note 如果opts中指定了`:file`，则block会被忽略
+      # @note 如果既没有指定`:file`也没有指定block，则只获取Object
+      #  meta而不下载Object内容
+      def get_object(key, opts = {}, &block)
+        obj = nil
+        file = opts[:file]
+        if file
+          File.open(File.expand_path(file), 'wb') do |f|
+            obj = @protocol.get_object(name, key, opts) do |chunk|
+              f.write(chunk)
+            end
+          end
+        elsif block
+          obj = @protocol.get_object(name, key, opts, &block)
+        else
+          obj = @protocol.get_object_meta(name, key, opts)
+        end
+
+        obj
+      end
+
+      # 更新Object的metas
+      # @param key [String] Object的名字
+      # @param metas [Hash] Object的meta
+      # @param conditions [Hash] 指定更新Object meta需要满足的条件，
+      #  同{#get_object}
+      # @return [Hash] 更新后文件的信息
+      #  * :etag [String] 更新后文件的ETag
+      #  * :last_modified [Time] 更新后文件的最后修改时间
+      def update_object_metas(key, metas, conditions = {})
+        @protocol.copy_object(
+          name, key, key,
+          :meta_directive => MetaDirective::REPLACE,
+          :metas => metas,
+          :condition => conditions)
+      end
+
+      # 判断一个object是否存在
+      # @param key [String] Object的名字
+      # @return [Boolean] 如果Object存在返回true，否则返回false
+      def object_exists?(key)
+        begin
+          get_object(key)
+          return true
+        rescue ServerError => e
+          return false if e.http_code == 404
+          raise e
+        end
+
+        false
+      end
+
+      alias :object_exist? :object_exists?
+
+      # 向Bucket中的object追加内容。如果object不存在，则创建一个
+      # Appendable Object。
+      # @param key [String] Object的名字
+      # @param opts [Hash] 上传object时的选项（可选）
+      # @option opts [String] :file 指定追加的内容从文件中读取
+      # @option opts [String] :content_type 设置所上传的内容的
+      #  Content-Type，默认是application/octet-stream
+      # @option opts [Hash] :metas 设置object的meta，这是一些用户自定
+      #  义的属性，它们会和object一起存储，在{#get_object_meta}的时候会
+      #  返回这些meta。属性的key不区分大小写。例如：{ 'year' => '2015' }
+      # @example 流式上传数据
+      #   pos = append_object('x', 0){ |stream| 100.times { |i| stream << i.to_s } }
+      #   append_object('x', pos){ |stream| stream << get_data }
+      # @example 上传文件
+      #   append_object('x', 0, :file => '/tmp/x')
+      # @example 指定Content-Type和metas
+      #   append_object('x', 0, :file => '/tmp/x', :content_type => 'text/html',
+      #                 :metas => {'year' => '2015', 'people' => 'mary'})
+      # @return [Integer] 返回下次append的位置
+      # @yield [HTTP::StreamWriter] 同 {#put_object}
+      def append_object(key, pos, opts = {}, &block)
+        next_pos = -1
+        file = opts[:file]
+        if file
+          opts[:content_type] = get_content_type(file)
+
+          next_pos = @protocol.append_object(name, key, pos, opts) do |sw|
+            File.open(File.expand_path(file), 'rb') do |f|
+              sw << f.read(Protocol::STREAM_CHUNK_SIZE) until f.eof?
+            end
+          end
+        else
+          next_pos = @protocol.append_object(name, key, pos, opts, &block)
+        end
+
+        next_pos
+      end
+
+      # 将Bucket中的一个object拷贝成另外一个object
+      # @param source [String] 源object名字
+      # @param dest [String] 目标object名字
+      # @param opts [Hash] 拷贝object时的选项（可选）
+      # @option opts [String] :acl 目标文件的acl属性，默认为private
+      # @option opts [String] :meta_directive 指定是否拷贝源object的
+      #  meta信息，默认为{OSS::MetaDirective::COPY}：即拷贝object的时
+      #  候也拷贝meta信息。
+      # @option opts [Hash] :metas 设置object的meta，这是一些用户自定
+      #  义的属性，它们会和object一起存储，在{#get_object_meta}的时候会
+      #  返回这些meta。属性的key不区分大小写。例如：{ 'year' => '2015'
+      #  }。如果:meta_directive为{OSS::MetaDirective::COPY}，则:metas
+      #  会被忽略。
+      # @option opts [Hash] :condition 指定拷贝object需要满足的条件，
+      #  同 {#get_object}
+      # @return [Hash] 目标文件的信息
+      #  * :etag [String] 目标文件的ETag
+      #  * :last_modified [Time] 目标文件的最后修改时间
+      def copy_object(source, dest, opts = {})
+        @protocol.copy_object(name, source, dest, opts)
+      end
+
+      # 删除一个object
+      # @param key [String] Object的名字
+      def delete_object(key)
+        @protocol.delete_object(name, key)
+      end
+
+      # 批量删除object
+      # @param keys [Array<String>] Object的名字集合
+      # @param opts [Hash] 删除object的选项（可选）
+      # @option opts [Boolean] :quiet 指定是否允许Server返回成功删除的
+      #  object
+      # @option opts [String] :encoding 指定Server返回的成功删除的
+      #  object的名字的编码方式，目前只支持{OSS::KeyEncoding::URL}
+      # @return [Array<String>] 成功删除的object的名字，如果指定
+      #  了:quiet参数，则返回[]
+      def batch_delete_objects(keys, opts = {})
+        @protocol.batch_delete_objects(name, keys, opts)
+      end
+
+      # 设置object的ACL
+      # @param key [String] Object的名字
+      # @param acl [String] Object的{OSS::ACL ACL}
+      def set_object_acl(key, acl)
+        @protocol.put_object_acl(name, key, acl)
+      end
+
+      # 获取object的ACL
+      # @param key [String] Object的名字
+      # @return [String] object的{OSS::ACL ACL}
+      def get_object_acl(key)
+        @protocol.get_object_acl(name, key)
+      end
+
+      # 获取object的CORS规则
+      # @param key [String] Object的名字
+      # @return [OSS::CORSRule]
+      def get_object_cors(key)
+        @protocol.get_object_cors(name, key)
+      end
+
+      ##
+      # 断点续传相关的API
+      #
+
+      # 上传一个本地文件到bucket中的一个object，支持断点续传。指定的文
+      # 件会被分成多个分片进行上传，只有所有分片都上传成功整个文件才
+      # 上传成功。
+      # @param key [String] Object的名字
+      # @param file [String] 本地文件的路径
+      # @param opts [Hash] 上传文件的可选项
+      # @option opts [String] :content_type 设置所上传的内容的
+      #  Content-Type，默认是application/octet-stream
+      # @option opts [Hash] :metas 设置object的meta，这是一些用户自定
+      #  义的属性，它们会和object一起存储，在{#get_object_meta}的时候会
+      #  返回这些meta。属性的key不区分大小写。例如：{ 'year' => '2015' }
+      # @option opts [Integer] :part_size 设置分片上传时每个分片的大小，
+      #  默认为1 MB。断点上传最多允许10000个分片，如果文件大于10000个
+      #  分片的大小，则每个分片的大小会大于1MB。
+      # @option opts [String] :cpt_file 断点续传的checkpoint文件，如果
+      #  指定的cpt文件不存在，则会在file所在目录创建一个默认的cpt文件，
+      #  命名方式为：file.cpt，其中file是用户要上传的文件。在上传的过
+      #  程中会不断更新此文件，成功完成上传后会删除此文件；如果指定的
+      #  cpt文件已存在，则从cpt文件中记录的点继续上传。
+      # @option opts [Boolean] :disable_cpt 是否禁用checkpoint功能，如
+      #  果设置为true，则在上传的过程中不会写checkpoint文件，这意味着
+      #  上传失败后不能断点续传，而只能重新上传整个文件。如果这个值为
+      #  true，则:cpt_file会被忽略。
+      # @yield [Float] 如果调用的时候传递了block，则会将上传进度交由
+      #  block处理，进度值是一个0-1之间的小数
+      # @raise [CheckpointBrokenError] 如果cpt文件被损坏，则抛出此错误
+      # @raise [FileInconsistentError] 如果指定的文件与cpt中记录的不一
+      #  致，则抛出此错误
+      # @example
+      #   bucket.resumable_upload('my-object', '/tmp/x') do |p|
+      #     puts "Progress: #{(p * 100).round(2)} %"
+      #   end
+      def resumable_upload(key, file, opts = {}, &block)
+        unless cpt_file = opts[:cpt_file]
+          cpt_file = get_cpt_file(file)
+        end
+
+        Multipart::Upload.new(
+          @protocol, options: opts,
+          progress: block,
+          object: key, bucket: name, creation_time: Time.now,
+          file: File.expand_path(file), cpt_file: cpt_file
+        ).run
+      end
+
+      # 下载bucket中的一个object到本地文件，支持断点续传。指定的object
+      # 会被分成多个分片进行下载，只有所有的分片都下载成功整个object才
+      # 下载成功。对于每个下载的分片，会在file所在目录建立一个临时文件
+      # file.part.N，下载成功后这些part文件会被合并成最后的file然后删
+      # 除。
+      # @param key [String] Object的名字
+      # @param file [String] 本地文件的路径
+      # @param opts [Hash] 下载文件的可选项
+      # @option opts [Integer] :part_size 设置分片上传时每个分片的大小，
+      #  默认为1 MB。断点下载最多允许100个分片，如果文件大于100个分片，
+      #  则每个分片的大小会大于1MB
+      # @option opts [String] :cpt_file 断点续传的checkpoint文件，如果
+      #  指定的cpt文件不存在，则会在file所在目录创建一个默认的cpt文件，
+      #  命名方式为：file.cpt，其中file是用户要下载的文件名。在下载的过
+      #  程中会不断更新此文件，成功完成下载后会删除此文件；如果指定的
+      #  cpt文件已存在，则从cpt文件中记录的点继续下载。
+      # @option opts [Boolean] :disable_cpt 是否禁用checkpoint功能，如
+      #  果设置为true，则在下载的过程中不会写checkpoint文件，这意味着
+      #  下载失败后不能断点续传，而只能重新下载整个文件。如果这个值为true，
+      #  则:cpt_file会被忽略。
+      # @option opts [Hash] :condition 指定下载object需要满足的条件，
+      #  同 {#get_object}
+      # @option opts [Hash] :rewrite 指定下载object时Server端返回的响
+      #  应头部字段的值，同 {#get_object}
+      # @yield [Float] 如果调用的时候传递了block，则会将下载进度交由
+      #  block处理，进度值是一个0-1之间的小数
+      # @raise [CheckpointBrokenError] 如果cpt文件被损坏，则抛出此错误
+      # @raise [ObjectInconsistentError] 如果指定的object的etag与cpt文
+      #  件中记录的不一致，则抛出错误
+      # @raise [PartMissingError] 如果已下载的部分(.part文件)找不到，
+      #  则抛出此错误
+      # @raise [PartInconsistentError] 如果已下载的部分(.part文件)的
+      #  MD5值与cpt文件记录的不一致，则抛出此错误
+      # @note 已经下载的部分会在file所在的目录创建.part文件，命名方式
+      #  为file.part.N
+      # @example
+      #   bucket.resumable_download('my-object', '/tmp/x') do |p|
+      #     puts "Progress: #{(p * 100).round(2)} %"
+      #   end
+      def resumable_download(key, file, opts = {}, &block)
+        unless cpt_file = opts[:cpt_file]
+          cpt_file = get_cpt_file(file)
+        end
+
+        Multipart::Download.new(
+          @protocol, options: opts,
+          progress: block,
+          object: key, bucket: name, creation_time: Time.now,
+          file: File.expand_path(file), cpt_file: cpt_file
+        ).run
+      end
+
+      # 获取Bucket的URL
+      # @return [String] Bucket的URL
+      def bucket_url
+        @protocol.get_request_url(name)
+      end
+
+      # 获取Object的URL
+      # @param [String] key Object的key
+      # @param [Boolean] sign 是否对URL进行签名，默认为是
+      # @param [Fixnum] expiry URL的有效时间，单位为秒，默认为60s
+      # @return [String] 用于直接访问Object的URL
+      def object_url(key, sign = true, expiry = 60)
+        url = @protocol.get_request_url(name, key)
+        return url unless sign
+
+        expires = Time.now.to_i + expiry
+        string_to_sign = "GET\n" +
+                         "\n\n" +
+                         "#{expires}\n" +
+                         "/#{name}/#{key}"
+        signature = sign(string_to_sign)
+
+        query_string = {
+          'Expires' => expires.to_s,
+          'OSSAccessKeyId' => CGI.escape(access_key_id),
+          'Signature' => CGI.escape(signature)
+        }.map { |k, v| "#{k}=#{v}" }.join('&')
+
+        [url, query_string].join('?')
+      end
+
+      # 获取用户所设置的ACCESS_KEY_ID
+      # @return [String] 用户的ACCESS_KEY_ID
+      def access_key_id
+        @protocol.get_access_key_id
+      end
+
+      # 用ACCESS_KEY_SECRET对内容进行签名
+      # @param [String] string_to_sign 要进行签名的内容
+      # @return [String] 生成的签名
+      def sign(string_to_sign)
+        @protocol.sign(string_to_sign)
+      end
+
+      private
+      # Infer the file's content type using MIME::Types
+      # @param file [String] the file path
+      # @return [String] the infered content type or nil if it fails
+      #  to infer the content type
+      def get_content_type(file)
+        t = MIME::Types.of(file)
+        t.first.content_type unless t.empty?
+      end
+
+      # Get the checkpoint file path for file
+      # @param file [String] the file path
+      # @return [String] the checkpoint file path
+      def get_cpt_file(file)
+        "#{File.expand_path(file)}.cpt"
+      end
+
+    end # Bucket
+  end # OSS
+end # Aliyun