aliyun-oss-ruby-sdk 0.4.1

data/examples/aliyun/oss/streaming.rb

@@ -0,0 +1,124 @@
+# -*- encoding: utf-8 -*-
+
+$LOAD_PATH.unshift(File.expand_path("../../../../lib", __FILE__))
+require 'yaml'
+require 'aliyun/oss'
+
+##
+# 一般来说用户在上传object和下载object时只需要指定文件名就可以满足需要：
+# - 在上传的时候client会从指定的文件中读取数据上传到OSS
+# - 在下载的时候client会把从OSS下载的数据写入到指定的文件中
+#
+# 在某些情况下用户可能会需要流式地上传和下载：
+# - 用户要写入到object中的数据不能立即得到全部，而是从网络中流式获取，
+#   然后再一段一段地写入到OSS中
+# - 用户要写入到object的数据是经过运算得出，每次得到一部分，用户不希望
+#   保留所有的数据然后一次性写入到OSS
+# - 用户下载的object很大，用户不希望一次性把它们下载到内存中，而是希望
+#   获取一部分就处理一部分；用户也不希望把它先下载到文件中，然后再从文
+#   件中读出来处理，这样会让数据经历不必要的拷贝
+#
+# 当然，对于流式上传的需求，我们可以使用OSS的appendable object来满足。
+# 但是即使是normal object，利用sdk的streaming功能，也可以实现流式上传
+# 和下载。
+
+# 初始化OSS client
+AliyunSDK::Common::Logging.set_log_level(Logger::DEBUG)
+conf_file = '~/.oss.yml'
+conf = YAML.load(File.read(File.expand_path(conf_file)))
+bucket = AliyunSDK::OSS::Client.new(
+  :endpoint => conf['endpoint'],
+  :cname => conf['cname'],
+  :access_key_id => conf['access_key_id'],
+  :access_key_secret => conf['access_key_secret']).get_bucket(conf['bucket'])
+
+# 辅助打印函数
+def demo(msg)
+  puts "######### #{msg} ########"
+  puts
+  yield
+  puts "-------------------------"
+  puts
+end
+
+# 例子1: 归并排序
+# 有两个文件sort.1, sort.2，它们分别存了一些从小到大排列的整数，每个整
+# 数1行，现在要将它们做归并排序的结果上传到OSS中，命名为sort.all
+
+local_1, local_2 = 'sort.1', 'sort.2'
+result_object = 'sort.all'
+
+File.open(File.expand_path(local_1), 'w') do |f|
+  [1001, 2005, 2007, 2011, 2013, 2015].each do |i|
+    f.puts(i.to_s)
+  end
+end
+
+File.open(File.expand_path(local_2), 'w') do |f|
+  [2009, 2010, 2012, 2017, 2020, 9999].each do |i|
+    f.puts(i.to_s)
+  end
+end
+
+demo "Streaming upload" do
+  bucket.put_object(result_object) do |content|
+    f1 = File.open(File.expand_path(local_1))
+    f2 = File.open(File.expand_path(local_2))
+    v1, v2 = f1.readline, f2.readline
+
+    until f1.eof? or f2.eof?
+      if v1.to_i < v2.to_i
+        content << v1
+        v1 = f1.readline
+      else
+        content << v2
+        v2 = f2.readline
+      end
+    end
+
+    [v1, v2].sort.each{|i| content << i}
+    content << f1.readline until f1.eof?
+    content << f2.readline until f2.eof?
+  end
+
+  puts "Put object: #{result_object}"
+
+  # 将文件下载下来查看
+  bucket.get_object(result_object, :file => result_object)
+  puts "Get object: #{result_object}"
+  puts "Content: #{File.read(result_object)}"
+end
+
+# 例子2: 下载进度条
+# 下载一个大文件（10M），在下载的过程中打印下载进度
+
+large_file = 'large_file'
+
+demo "Streaming download" do
+  puts "Begin put object: #{large_file}"
+  # 利用streaming上传
+  bucket.put_object(large_file) do |stream|
+    10.times { stream << "x" * (1024 * 1024) }
+  end
+
+  # 查看object大小
+  object_size = bucket.get_object(large_file).size
+  puts "Put object: #{large_file}, size: #{object_size}"
+
+  # 流式下载文件，仅打印进度，不保存文件
+  def to_percentile(v)
+    "#{(v * 100.0).round(2)} %"
+  end
+
+  puts "Begin download: #{large_file}"
+  last_got, got = 0, 0
+  bucket.get_object(large_file) do |chunk|
+    got += chunk.size
+    # 仅在下载进度大于10%的时候打印
+    if (got - last_got).to_f / object_size > 0.1
+      puts "Progress: #{to_percentile(got.to_f / object_size)}"
+      last_got = got
+    end
+  end
+  puts "Get object: #{large_file}, size: #{object_size}"
+end

data/examples/aliyun/oss/using_sts.rb

@@ -0,0 +1,48 @@
+# -*- encoding: utf-8 -*-
+
+$LOAD_PATH.unshift(File.expand_path("../../../../lib", __FILE__))
+require 'yaml'
+require 'aliyun/sts'
+require 'aliyun/oss'
+
+# 初始化OSS client
+AliyunSDK::Common::Logging.set_log_level(Logger::DEBUG)
+conf_file = '~/.sts.yml'
+conf = YAML.load(File.read(File.expand_path(conf_file)))
+
+# 辅助打印函数
+def demo(msg)
+  puts "######### #{msg} ########"
+  puts
+  yield
+  puts "-------------------------"
+  puts
+end
+
+demo "Using STS" do
+  sts = AliyunSDK::STS::Client.new(
+    :access_key_id => conf['access_key_id'],
+    :access_key_secret => conf['access_key_secret'])
+
+  token = sts.assume_role(
+    'acs:ram::52352:role/aliyunosstokengeneratorrole', 'app-1')
+
+  client = AliyunSDK::OSS::Client.new(
+    :endpoint => 'http://oss-cn-hangzhou.aliyuncs.com',
+    :sts_token => token.security_token,
+    :access_key_id => token.access_key_id,
+    :access_key_secret => token.access_key_secret)
+
+  unless client.bucket_exists?('bucket-for-sts-test')
+    client.create_bucket('bucket-for-sts-test')
+  end
+
+  bucket = client.get_bucket('bucket-for-sts-test')
+
+  bucket.put_object('hello') { |s| s << 'hello' }
+  bucket.put_object('world') { |s| s << 'world' }
+
+  bucket.list_objects.take(10).each do |obj|
+    puts "Object: #{obj.key}, size: #{obj.size}"
+  end
+end

data/examples/aliyun/sts/assume_role.rb

@@ -0,0 +1,59 @@
+# -*- encoding: utf-8 -*-
+
+$LOAD_PATH.unshift(File.expand_path("../../../../lib", __FILE__))
+require 'yaml'
+require 'aliyun/sts'
+
+AliyunSDK::Common::Logging.set_log_level(Logger::DEBUG)
+conf_file = '~/.sts.yml'
+conf = YAML.load(File.read(File.expand_path(conf_file)))
+client = AliyunSDK::STS::Client.new(
+  :access_key_id => conf['access_key_id'],
+  :access_key_secret => conf['access_key_secret'])
+
+# 辅助打印函数
+def demo(msg)
+  puts "######### #{msg} ########"
+  puts
+  yield
+  puts "-------------------------"
+  puts
+end
+
+token = client.assume_role(
+  'acs:ram::52352:role/aliyunosstokengeneratorrole', 'app-1')
+
+demo "Assume role" do
+  begin
+    token = client.assume_role(
+      'acs:ram::52352:role/aliyunosstokengeneratorrole', 'app-1')
+
+    puts "Credentials for session: #{token.session_name}"
+    puts "access key id: #{token.access_key_id}"
+    puts "access key secret: #{token.access_key_secret}"
+    puts "security token: #{token.security_token}"
+    puts "expiration at: #{token.expiration}"
+  rescue => e
+    puts "AssumeRole failed: #{e.message}"
+  end
+end
+
+demo "Assume role with policy" do
+  begin
+    policy = AliyunSDK::STS::Policy.new
+    policy.allow(
+      ['oss:Get*', 'oss:PutObject'],
+      ['acs:oss:*:*:my-bucket', 'acs:oss:*:*:my-bucket/*'])
+
+    token = client.assume_role(
+      'acs:ram::52352:role/aliyunosstokengeneratorrole', 'app-2', policy, 900)
+
+    puts "Credentials for session: #{token.session_name}"
+    puts "access key id: #{token.access_key_id}"
+    puts "access key secret: #{token.access_key_secret}"
+    puts "security token: #{token.security_token}"
+    puts "expiration at: #{token.expiration}"
+  rescue => e
+    puts "AssumeRole failed: #{e.message}"
+  end
+end

data/lib/aliyun_sdk/common.rb

@@ -0,0 +1,6 @@
+# -*- encoding: utf-8 -*-
+
+require_relative 'version'
+require_relative 'common/struct'
+require_relative 'common/logging'
+require_relative 'common/exception'

data/lib/aliyun_sdk/common/exception.rb

@@ -0,0 +1,18 @@
+# -*- encoding: utf-8 -*-
+
+module AliyunSDK
+  module Common
+
+    ##
+    # Base exception class
+    #
+    class Exception < RuntimeError
+      attr_reader :message
+
+      def initialize(message)
+        @message = message
+      end
+    end
+
+  end # Common
+end # Aliyun

data/lib/aliyun_sdk/common/logging.rb

@@ -0,0 +1,46 @@
+# -*- encoding: utf-8 -*-
+
+require 'logger'
+
+module AliyunSDK
+  module Common
+    ##
+    # Logging support
+    # @example
+    #   include Logging
+    #   logger.info(xxx)
+    module Logging
+
+      DEFAULT_LOG_FILE = "./aliyun_sdk.log"
+      MAX_NUM_LOG = 100
+      ROTATE_SIZE = 10 * 1024 * 1024
+
+      # level = Logger::DEBUG | Logger::INFO | Logger::ERROR | Logger::FATAL
+      def self.set_log_level(level)
+        Logging.logger.level = level
+      end
+
+      # 设置日志输出的文件
+      def self.set_log_file(file)
+        @log_file = file
+      end
+
+      # 获取logger
+      def logger
+        Logging.logger
+      end
+
+      private
+
+      def self.logger
+        unless @logger
+          @logger = Logger.new(
+            @log_file ||= DEFAULT_LOG_FILE, MAX_NUM_LOG, ROTATE_SIZE)
+          @logger.level = Logger::INFO
+        end
+        @logger
+      end
+
+    end # logging
+  end # Common
+end # Aliyun

data/lib/aliyun_sdk/common/struct.rb

@@ -0,0 +1,56 @@
+# -*- encoding: utf-8 -*-
+
+module AliyunSDK
+  module Common
+
+    # Common structs used. It provides a 'attrs' helper method for
+    # subclass to define its attributes. 'attrs' is based on
+    # attr_reader and provide additional functionalities for classes
+    # that inherits Struct::Base :
+    # * the constuctor is provided to accept options and set the
+    #   corresponding attibute automatically
+    # * the #to_s method is rewrite to concatenate the defined
+    #   attributes keys and values
+    # @example
+    #   class X < Struct::Base
+    #     attrs :foo, :bar
+    #   end
+    #
+    #   x.new(:foo => 'hello', :bar => 'world')
+    #   x.foo # == "hello"
+    #   x.bar # == "world"
+    #   x.to_s # == "foo: hello, bar: world"
+    module Struct
+      class Base
+        module AttrHelper
+          def attrs(*s)
+            define_method(:attrs) {s}
+            attr_reader(*s)
+          end
+        end
+
+        extend AttrHelper
+
+        def initialize(opts = {})
+          extra_keys = opts.keys - attrs
+          unless extra_keys.empty?
+            fail Common::Exception,
+                 "Unexpected extra keys: #{extra_keys.join(', ')}"
+          end
+
+          attrs.each do |attr|
+            instance_variable_set("@#{attr}", opts[attr])
+          end
+        end
+
+        def to_s
+          attrs.map do |attr|
+            v = instance_variable_get("@#{attr}")
+            "#{attr.to_s}: #{v}"
+          end.join(", ")
+        end
+      end # Base
+    end # Struct
+
+  end # Common
+end # Aliyun

data/lib/aliyun_sdk/oss.rb

@@ -0,0 +1,16 @@
+# -*- encoding: utf-8 -*-
+
+require_relative 'common'
+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_sdk/oss/bucket.rb

@@ -0,0 +1,661 @@
+# -*- encoding: utf-8 -*-
+
+module AliyunSDK
+  module OSS
+    ##
+    # Bucket是用户的Object相关的操作的client，主要包括三部分功能：
+    # 1. bucket相关：获取/设置bucket的属性（acl, logging, referer,
+    #    website, lifecycle, cors）
+    # 2. object相关：上传、下载、追加、拷贝object等
+    # 3. multipart相关：断点续传、断点续载
+    class Bucket < Common::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] :marker 如果设置，则只返回名字在它之后
+      #  （字典序，不包含marker）的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（可能数量巨大），是用于模拟目录结构的常用做法。
+      # @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.merge(encoding: KeyEncoding::URL)).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。属性的key不区分大小写。例如：{ 'year' => '2015' }
+      # @option opts [Callback] :callback 指定操作成功后OSS的
+      #  上传回调，上传成功后OSS会向用户的应用服务器发一个HTTP POST请
+      #  求，`:callback`参数指定这个请求的相关参数
+      # @option opts [Hash] :headers 指定请求的HTTP Header，不区分大小
+      #  写。这里指定的值会覆盖通过`:content_type`和`:metas`设置的值。
+      # @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'})
+      # @example 指定Callback
+      #   callback = AliyunSDK::OSS::Callback.new(
+      #     url: 'http://10.101.168.94:1234/callback',
+      #     query: {user: 'put_object'},
+      #     body: 'bucket=${bucket}&object=${object}'
+      #   )
+      #
+      #   bucket.put_object('files/hello', callback: callback)
+      # @raise [CallbackError] 如果文件上传成功而Callback调用失败，抛
+      #  出此错误
+      # @note 如果opts中指定了`:file`，则block会被忽略
+      # @note 如果指定了`:callback`，则可能文件上传成功，但是callback
+      #  执行失败，此时会抛出{OSS::CallbackError}，用户可以选择接住这
+      #  个异常，以忽略Callback调用错误
+      def put_object(key, opts = {}, &block)
+        args = opts.dup
+
+        file = args[:file]
+        args[:content_type] ||= get_content_type(file) if file
+        args[:content_type] ||= get_content_type(key)
+
+        if file
+          @protocol.put_object(name, key, args) 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, args, &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] :headers 指定请求的HTTP Header，不区分大小
+      #  写。这里指定的值会覆盖通过`:range`和`:condition`设置的值。
+      # @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。属性的key不区分大小写。例如：{ 'year' => '2015' }
+      # @option opts [Hash] :headers 指定请求的HTTP Header，不区分大小
+      #  写。这里指定的值会覆盖通过`:content_type`和`:metas`设置的值。
+      # @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)
+        args = opts.dup
+
+        file = args[:file]
+        args[:content_type] ||= get_content_type(file) if file
+        args[:content_type] ||= get_content_type(key)
+
+        if file
+          next_pos = @protocol.append_object(name, key, pos, args) 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, args, &block)
+        end
+
+        next_pos
+      end
+
+      # 将Bucket中的一个object拷贝成另外一个object
+      # @param source [String] 源object名字
+      # @param dest [String] 目标object名字
+      # @param opts [Hash] 拷贝object时的选项（可选）
+      # @option opts [String] :src_bucket 源object所属的Bucket，默认与
+      #  目标文件为同一个Bucket。源Bucket与目标Bucket必须属于同一个Region。
+      # @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。属性的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 = {})
+        args = opts.dup
+
+        args[:content_type] ||= get_content_type(dest)
+        @protocol.copy_object(name, source, dest, args)
+      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，默认为false，即返回删除结果
+      # @return [Array<String>] 成功删除的object的名字，如果指定
+      #  了:quiet参数，则返回[]
+      def batch_delete_objects(keys, opts = {})
+        @protocol.batch_delete_objects(
+          name, keys, opts.merge(encoding: KeyEncoding::URL))
+      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。属性的key不区分大小写。例如：{ 'year' => '2015' }
+      # @option opts [Integer] :part_size 设置分片上传时每个分片的大小，
+      #  默认为10 MB。断点上传最多允许10000个分片，如果文件大于10000个
+      #  分片的大小，则每个分片的大小会大于10MB。
+      # @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 [Callback] :callback 指定文件上传成功后OSS的
+      #  上传回调，上传成功后OSS会向用户的应用服务器发一个HTTP POST请
+      #  求，`:callback`参数指定这个请求的相关参数
+      # @option opts [Hash] :headers 指定请求的HTTP Header，不区分大小
+      #  写。这里指定的值会覆盖通过`:content_type`和`:metas`设置的值。
+      # @yield [Float] 如果调用的时候传递了block，则会将上传进度交由
+      #  block处理，进度值是一个0-1之间的小数
+      # @raise [CheckpointBrokenError] 如果cpt文件被损坏，则抛出此错误
+      # @raise [FileInconsistentError] 如果指定的文件与cpt中记录的不一
+      #  致，则抛出此错误
+      # @raise [CallbackError] 如果文件上传成功而Callback调用失败，抛
+      #  出此错误
+      # @example
+      #   bucket.resumable_upload('my-object', '/tmp/x') do |p|
+      #     puts "Progress: #{(p * 100).round(2)} %"
+      #   end
+      # @example 指定Callback
+      #   callback = AliyunSDK::OSS::Callback.new(
+      #     url: 'http://10.101.168.94:1234/callback',
+      #     query: {user: 'put_object'},
+      #     body: 'bucket=${bucket}&object=${object}'
+      #   )
+      #
+      #   bucket.resumable_upload('files/hello', '/tmp/x', callback: callback)
+      # @note 如果指定了`:callback`，则可能文件上传成功，但是callback
+      #  执行失败，此时会抛出{OSS::CallbackError}，用户可以选择接住这
+      #  个异常，以忽略Callback调用错误
+      def resumable_upload(key, file, opts = {}, &block)
+        args = opts.dup
+
+        args[:content_type] ||= get_content_type(file)
+        args[:content_type] ||= get_content_type(key)
+        cpt_file = args[:cpt_file] || get_cpt_file(file)
+
+        Multipart::Upload.new(
+          @protocol, options: args,
+          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 设置分片上传时每个分片的大小，
+      #  默认为10 MB。断点下载最多允许100个分片，如果文件大于100个分片，
+      #  则每个分片的大小会大于10 MB
+      # @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] :headers 指定请求的HTTP Header，不区分大小
+      #  写。这里指定的值会覆盖通过`:condition`设置的值。
+      # @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)
+        args = opts.dup
+
+        args[:content_type] ||= get_content_type(file)
+        args[:content_type] ||= get_content_type(key)
+        cpt_file = args[:cpt_file] || get_cpt_file(file)
+
+        Multipart::Download.new(
+          @protocol, options: args,
+          progress: block,
+          object: key, bucket: name, creation_time: Time.now,
+          file: File.expand_path(file), cpt_file: cpt_file
+        ).run
+      end
+
+      # 列出此Bucket中正在进行的multipart上传请求，不包括已经完成或者
+      # 被取消的。
+      # @param [Hash] opts 可选项
+      # @option opts [String] :key_marker object key的标记，根据有没有
+      #  设置:id_marker，:key_marker的含义不同：
+      #  1. 如果未设置:id_marker，则只返回object key在:key_marker之后
+      #     （字典序，不包含marker）的upload请求
+      #  2. 如果设置了:id_marker，则返回object key在:key_marker之后
+      #     （字典序，不包含marker）的uplaod请求*和*Object
+      #     key与:key_marker相等，*且*upload id在:id_marker之后（字母
+      #     表顺序排序，不包含marker）的upload请求
+      # @option opts [String] :id_marker upload id的标记，如
+      #  果:key_marker没有设置，则此参数会被忽略；否则与:key_marker一起
+      #  决定返回的结果（见上）
+      # @option opts [String] :prefix 如果指定，则只返回object key中符
+      #  合指定前缀的upload请求
+      # @return [Enumerator<Multipart::Transaction>] 其中每一个元素表
+      #  示一个upload请求
+      # @example
+      #   key_marker = 1, id_marker = null
+      #   # return <2, 0>, <2, 1>, <3, 0> ...
+      #   key_marker = 1, id_marker = 5
+      #   # return <1, 6>, <1, 7>, <2, 0>, <3, 0> ...
+      def list_uploads(opts = {})
+        Iterator::Uploads.new(
+          @protocol, name, opts.merge(encoding: KeyEncoding::URL)).to_enum
+      end
+
+      # 取消一个multipart上传请求，一般用于清除Bucket下因断点上传而产
+      # 生的文件碎片。成功取消后属于这个上传请求的分片都会被清除。
+      # @param [String] upload_id 上传请求的id，可通过{#list_uploads}
+      #  获得
+      # @param [String] key Object的名字
+      def abort_upload(upload_id, key)
+        @protocol.abort_multipart_upload(name, key, upload_id)
+      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
+        query = {
+          'Expires' => expires.to_s,
+          'OSSAccessKeyId' => CGI.escape(access_key_id)
+        }
+
+        sub_res = []
+        if @protocol.get_sts_token
+          sub_res << "security-token=#{@protocol.get_sts_token}"
+          query['security-token'] = CGI.escape(@protocol.get_sts_token)
+        end
+
+        resource = "/#{name}/#{key}"
+        unless sub_res.empty?
+          resource << "?#{sub_res.join('&')}"
+        end
+
+        string_to_sign = "" <<
+                         "GET\n" << # method
+                         "\n" <<    # Content-MD5
+                         "\n" <<    # Content-Type
+                         "#{expires}\n" <<
+                         "#{resource}"
+
+        signature = sign(string_to_sign)
+        query_string =
+          query.merge('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