You are viewing documentation for version 1 of the AWS SDK for Ruby. Version 2 documentation can be found here.

Class: AWS::S3::Client::V20060301

Inherits:
AWS::S3::Client show all
Defined in:
lib/aws/s3/client.rb

Constant Summary

Constant Summary

Constants inherited from AWS::S3::Client

API_VERSION, HTTP_200_ERROR_OPERATIONS, XMLNS

Instance Attribute Summary

Attributes inherited from Core::Client

#config

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from AWS::S3::Client

#initialize

Methods included from Validators

#dns_compatible_bucket_name?, #json_validation_message, #path_style_bucket_name?, #require_acl!, #require_allowed_methods!, #require_allowed_origins!, #require_bucket_name!, #require_part_number!, #require_policy!, #require_upload_id!, #set_body_stream_and_content_length, #valid_bucket_name?, #validate!, #validate_bucket_name!, #validate_key!, #validate_parts!

Methods included from Core::UriEscape

escape, escape_path

Methods inherited from Core::Client

#initialize, #log_warning, #operations, #with_http_handler, #with_options

Constructor Details

This class inherits a constructor from AWS::S3::Client

Class Method Details

.object_method(method_name, verb, *args, &block) ⇒ Object 



560
561
562
563
564
565
566
567
568
569
570
 
# File 'lib/aws/s3/client.rb', line 560

def self.object_method(method_name, verb, *args, &block)
  bucket_method(method_name, verb, *args) do
    configure_request do |req, options|
      validate_key!(options[:key])
      super(req, options)
      req.key = options[:key]
    end

    instance_eval(&block) if block
  end
end

Instance Method Details

#abort_multipart_upload(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :key (required, String)
  • :upload_id (required, String)

Returns:



1919
1920
1921
1922
1923
1924
1925
 
# File 'lib/aws/s3/client.rb', line 1919

object_method(:abort_multipart_upload, :delete) do
  configure_request do |req, options|
      require_upload_id!(options[:upload_id])
    super(req, options)
    req.add_param('uploadId', options[:upload_id])
  end
end

#complete_multipart_upload(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :key (required, String)
  • :upload_id (required, String)
  • :parts (required, Array<Hash>) —

    An array of hashes with the following keys: * :part_number [Integer] - required * :etag [String] - required

Returns:



1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
 
# File 'lib/aws/s3/client.rb', line 1882

object_method(:complete_multipart_upload, :post,
              XML::CompleteMultipartUpload) do
  configure_request do |req, options|
    require_upload_id!(options[:upload_id])
    validate_parts!(options[:parts])
    super(req, options)
    req.add_param('uploadId', options[:upload_id])

    req.body = Nokogiri::XML::Builder.new do |xml|
      xml.CompleteMultipartUpload do
        options[:parts].each do |part|
          xml.Part do
            xml.PartNumber(part[:part_number])
            xml.ETag(part[:etag])
          end
        end
      end
    end.doc.root.to_xml

  end

  process_response do |resp|
    extract_object_headers(resp)
  end

  simulate_response do |response|
    response.data = {}
  end

end

#copy_object(options = {}) ⇒ Core::Response

Copies an object from one key to another.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String) —

    Name of the bucket to copy a object into.

  • :key (required, String) —

    Where (object key) in the bucket the object should be copied to.

  • :website_redirect_location (String) —

    If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL.

  • :copy_source (required, String) —

    The source bucket name and key, joined by a forward slash ('/'). This string must be URL-encoded. Additionally, you must have read access to the source object.

  • :acl (String) —

    A canned ACL (e.g. 'private', 'public-read', etc). See the S3 API documentation for a complete list of valid values.

  • :server_side_encryption (Symbol, String) — default: nil —

    The algorithm used to encrypt the object on the server side (e.g. :aes256).

  • :storage_class+ (String) — default: 'STANDARD' —

    Controls whether Reduced Redundancy Storage is enabled for the object. Valid values are 'STANDARD' and 'REDUCED_REDUNDANCY'.

  • :metadata_directive (String) — default: 'COPY' —

    Specify 'COPY' or 'REPLACE'.

  • :content_type (String)
  • :content_encoding (String)
  • :content_disposition (String)
  • :cache_control (String)
  • :expires (String) —

    The date and time at which the object is no longer cacheable.

  • :grant_read (String)
  • :grant_write (String)
  • :grant_read_acp (String)
  • :grant_write_acp (String)
  • :grant_full_control (String)
  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the :sse_customer_algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :copy_source_sse_customer_algorithm (String) —

    Specifies the algorithm to use when decrypting the source object (e.g., AES256).

  • :copy_source_sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created.

  • :copy_source_sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

Returns:



2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
 
# File 'lib/aws/s3/client.rb', line 2008

object_method(:copy_object, :put, :header_options => {
  :website_redirect_location => 'x-amz-website-redirect-location',
  :acl => 'x-amz-acl',
  :grant_read => 'x-amz-grant-read',
  :grant_write => 'x-amz-grant-write',
  :grant_read_acp => 'x-amz-grant-read-acp',
  :grant_write_acp => 'x-amz-grant-write-acp',
  :grant_full_control => 'x-amz-grant-full-control',
  :copy_source => 'x-amz-copy-source',
  :cache_control => 'Cache-Control',
  :metadata_directive => 'x-amz-metadata-directive',
  :content_type => 'Content-Type',
  :content_encoding => 'Content-Encoding',
  :content_disposition => 'Content-Disposition',
  :expires => 'Expires',
  :sse_customer_algorithm => 'x-amz-server-side-encryption-customer-algorithm',
  :sse_customer_key => 'x-amz-server-side-encryption-customer-key',
  :sse_customer_key_md5 => 'x-amz-server-side-encryption-customer-key-MD5',
  :copy_source_sse_customer_algorithm => 'x-amz-copy-source-server-side-encryption-customer-algorithm',
  :copy_source_sse_customer_key => 'x-amz-copy-source-server-side-encryption-customer-key',
  :copy_source_sse_customer_key_md5 => 'x-amz-copy-source-server-side-encryption-customer-key-MD5',
}) do

  configure_request do |req, options|

    validate!(:copy_source, options[:copy_source]) do
      "may not be blank" if options[:copy_source].to_s.empty?
    end

    options = options.merge(:copy_source => escape_path(options[:copy_source]))
    super(req, options)
    set_metadata(req, options)
    set_storage_class(req, options)
    set_server_side_encryption(req, options)

    if options[:version_id]
      req.headers['x-amz-copy-source'] += "?versionId=#{options[:version_id]}"
    end
  end

  process_response do |resp|
    extract_object_headers(resp)
  end

end

#create_bucket(options = {}) ⇒ Core::Response Also known as: put_bucket

Creates a bucket.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :acl (String) —

    A canned ACL (e.g. 'private', 'public-read', etc). See the S3 API documentation for a complete list of valid values.

  • :grant_read (String)
  • :grant_write (String)
  • :grant_read_acp (String)
  • :grant_write_acp (String)
  • :grant_full_control (String)

Returns:



587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
 
# File 'lib/aws/s3/client.rb', line 587

bucket_method(:create_bucket, :put, :header_options => {
  :acl => 'x-amz-acl',
  :grant_read => 'x-amz-grant-read',
  :grant_write => 'x-amz-grant-write',
  :grant_read_acp => 'x-amz-grant-read-acp',
  :grant_write_acp => 'x-amz-grant-write-acp',
  :grant_full_control => 'x-amz-grant-full-control',
}) do

  configure_request do |req, options|
    validate_bucket_name!(options[:bucket_name])
    if location = options[:location_constraint]
      xmlns = "http://s3.amazonaws.com/doc/#{API_VERSION}/"
      req.body = <<-XML
        <CreateBucketConfiguration xmlns="#{xmlns}">
          <LocationConstraint>#{location}</LocationConstraint>
        </CreateBucketConfiguration>
      XML
    end
    super(req, options)
  end

end

#delete_bucket(options = {}) ⇒ Core::Response

Deletes an empty bucket.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



697
 
# File 'lib/aws/s3/client.rb', line 697

bucket_method(:delete_bucket, :delete)

#delete_bucket_cors(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



846
847
848
849
850
851
 
# File 'lib/aws/s3/client.rb', line 846

bucket_method(:delete_bucket_cors, :delete) do
  configure_request do |req, options|
    req.add_param('cors')
    super(req, options)
  end
end

#delete_bucket_lifecycle_configuration(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



738
739
740
741
742
743
744
745
 
# File 'lib/aws/s3/client.rb', line 738

bucket_method(:delete_bucket_lifecycle_configuration, :delete) do

  configure_request do |req, options|
    req.add_param('lifecycle')
    super(req, options)
  end

end

#delete_bucket_policy(options = {}) ⇒ Core::Response

Deletes the access policy for a bucket.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



968
 
# File 'lib/aws/s3/client.rb', line 968

bucket_method(:delete_bucket_policy, :delete, 'policy')

#delete_bucket_tagging(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



905
906
907
908
909
910
 
# File 'lib/aws/s3/client.rb', line 905

bucket_method(:delete_bucket_tagging, :delete) do
  configure_request do |req, options|
    req.add_param('tagging')
    super(req, options)
  end
end

#delete_bucket_website(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



690
 
# File 'lib/aws/s3/client.rb', line 690

bucket_method(:delete_bucket_website, :delete, 'website')

#delete_object(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :key (required, String)
  • :version_id (String)
  • :mfa (String)

Returns:



1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
 
# File 'lib/aws/s3/client.rb', line 1626

object_method(:delete_object, :delete, :header_options => { :mfa => "x-amz-mfa" }) do

  configure_request do |req, options|
    super(req, options)
    if options[:version_id]
      req.add_param('versionId', options[:version_id])
    end
  end

  process_response do |resp|
    resp.data[:version_id] = resp.http_response.header('x-amz-version-id')
  end

end

#delete_objects(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :objects (required, Array<Hash>) —

    Each entry should be a hash with the following keys: * :key - required * :version_id

  • :quiet (Boolean) — default: true
  • :mfa (String)

Returns:



1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
 
# File 'lib/aws/s3/client.rb', line 1805

bucket_method(:delete_objects, :post, 'delete', XML::DeleteObjects,
  :header_options => { :mfa => "x-amz-mfa" }
) do

  configure_request do |req, options|

    super(req, options)

    req.body = Nokogiri::XML::Builder.new do |xml|
      xml.Delete do
        xml.Quiet(options.key?(:quiet) ? options[:quiet] : true)
        (options[:objects] || options[:keys]).each do |obj|
          xml.Object do
            xml.Key(obj[:key])
            xml.VersionId(obj[:version_id]) if obj[:version_id]
          end
        end
      end
    end.doc.root.to_xml

    req.headers['content-md5'] = md5(req.body)

  end
end

#get_bucket_acl(options = {}) ⇒ Core::Response

Gets the access control list for a bucket.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



1218
 
# File 'lib/aws/s3/client.rb', line 1218

bucket_method(:get_bucket_acl, :get, 'acl', XML::GetBucketAcl)

#get_bucket_cors(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



829
830
831
832
833
834
835
836
837
838
839
840
 
# File 'lib/aws/s3/client.rb', line 829

bucket_method(:get_bucket_cors, :get) do

  configure_request do |req, options|
    req.add_param('cors')
    super(req, options)
  end

  process_response do |resp|
    resp.data = XML::GetBucketCors.parse(resp.http_response.body)
  end

end

#get_bucket_lifecycle_configuration(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



720
721
722
723
724
725
726
727
728
729
730
731
732
 
# File 'lib/aws/s3/client.rb', line 720

bucket_method(:get_bucket_lifecycle_configuration, :get) do

  configure_request do |req, options|
    req.add_param('lifecycle')
    super(req, options)
  end

  process_response do |resp|
    xml = resp.http_response.body
    resp.data = XML::GetBucketLifecycleConfiguration.parse(xml)
  end

end

#get_bucket_location(options = {}) ⇒ Core::Response

Gets the bucket's location constraint.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



1006
1007
1008
1009
1010
1011
1012
1013
1014
 
# File 'lib/aws/s3/client.rb', line 1006

bucket_method(:get_bucket_location, :get, 'location') do

  process_response do |response|
    regex = />(.*)<\/LocationConstraint>/
    matches = response.http_response.body.to_s.match(regex)
    response.data[:location_constraint] = matches ? matches[1] : nil
  end

end

#get_bucket_logging(options = {}) ⇒ Core::Response

Gets the bucket's logging status.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



1097
1098
 
# File 'lib/aws/s3/client.rb', line 1097

bucket_method(:get_bucket_logging, :get, 'logging',
XML::GetBucketLogging)

#get_bucket_policy(options = {}) ⇒ Core::Response

Gets the access policy for a bucket.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



955
956
957
958
959
960
961
 
# File 'lib/aws/s3/client.rb', line 955

bucket_method(:get_bucket_policy, :get, 'policy') do

  process_response do |resp|
    resp.data[:policy] = resp.http_response.body
  end

end

#get_bucket_tagging(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



888
889
890
891
892
893
894
895
896
897
898
899
 
# File 'lib/aws/s3/client.rb', line 888

bucket_method(:get_bucket_tagging, :get) do

  configure_request do |req, options|
    req.add_param('tagging')
    super(req, options)
  end

  process_response do |resp|
    resp.data = XML::GetBucketTagging.parse(resp.http_response.body)
  end

end

#get_bucket_versioning(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



1104
1105
 
# File 'lib/aws/s3/client.rb', line 1104

bucket_method(:get_bucket_versioning, :get, 'versioning',
XML::GetBucketVersioning)

#get_bucket_website(options = {}) ⇒ Core::Response

Returns * :index_document - (Hash) * :suffix - (String) * :error_document - (Hash) * :key - (String)

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:

  • (Core::Response) —
    • :index_document - (Hash)
      • :suffix - (String)
    • :error_document - (Hash)
      • :key - (String)


684
 
# File 'lib/aws/s3/client.rb', line 684

bucket_method(:get_bucket_website, :get, 'website', XML::GetBucketWebsite)

#get_object(options = {}) ⇒ Core::Response

Gets the data for a key.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :key (required, String)
  • :request_payer (String) —

    If specified, the request will contain the specified String value in the x-amz-request-payer header. This is required for Requester Pays enabled buckets.

  • :if_modified_since (Time) —

    If specified, the response will contain an additional :modified value that returns true if the object was modified after the given time. If :modified is false, then the response :data value will be nil.

  • :if_unmodified_since (Time) —

    If specified, the response will contain an additional :unmodified value that is true if the object was not modified after the given time. If :unmodified returns false, the :data value will be nil.

  • :if_match (String) —

    If specified, the response will contain an additional :matches value that is true if the object ETag matches the value for this option. If :matches is false, the :data value of the response will be nil.

  • :if_none_match (String) —

    If specified, the response will contain an additional :matches value that is true if and only if the object ETag matches the value for this option. If :matches is true, the :data value of the response will be nil.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the :sse_customer_algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :range (Range<Integer>) —

    A byte range of data to request.

Returns:



1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
 
# File 'lib/aws/s3/client.rb', line 1476

object_method(:get_object, :get,
              :header_options => {
                :request_payer => "x-amz-request-payer",
                :if_modified_since => "If-Modified-Since",
                :if_unmodified_since => "If-Unmodified-Since",
                :if_match => "If-Match",
                :if_none_match => "If-None-Match",
                :sse_customer_algorithm => 'x-amz-server-side-encryption-customer-algorithm',
                :sse_customer_key => 'x-amz-server-side-encryption-customer-key',
                :sse_customer_key_md5 => 'x-amz-server-side-encryption-customer-key-MD5',
              }) do
  configure_request do |req, options|

    super(req, options)

    if options[:version_id]
      req.add_param('versionId', options[:version_id])
    end

    ["If-Modified-Since",
     "If-Unmodified-Since"].each do |date_header|
      case value = req.headers[date_header]
      when DateTime
        req.headers[date_header] = Time.parse(value.to_s).rfc2822
      when Time
        req.headers[date_header] = value.rfc2822
      end
    end

    if options[:range]
      range = options[:range]
      if range.is_a?(Range)
        offset = range.exclude_end? ? -1 : 0
        range = "bytes=#{range.first}-#{range.last + offset}"
      end
      req.headers['Range'] = range
    end

  end

  process_response do |resp|
    extract_object_headers(resp)
    resp.data[:data] = resp.http_response.body
  end

end

#get_object_acl(options = {}) ⇒ Core::Response

Gets the access control list for an object.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :key (required, String)

Returns:



1312
 
# File 'lib/aws/s3/client.rb', line 1312

object_method(:get_object_acl, :get, 'acl', XML::GetBucketAcl)

#get_object_torrent(options = {}) ⇒ Core::Response

Gets the torrent for a key.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :key (required, String)

Returns:



1530
1531
1532
1533
1534
1535
 
# File 'lib/aws/s3/client.rb', line 1530

object_method(:get_object_torrent, :get, 'torrent') do
  process_response do |resp|
    extract_object_headers(resp)
    resp.data[:data] = resp.http_response.body
  end
end

#head_object(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :key (required, String)
  • :version_id (String)
  • :if_modified_since (Time) —

    If specified, the response will contain an additional :modified value that returns true if the object was modified after the given time. If :modified is false, then the response :data value will be nil.

  • :if_unmodified_since (Time) —

    If specified, the response will contain an additional :unmodified value that is true if the object was not modified after the given time. If :unmodified returns false, the :data value will be nil.

  • :if_match (String) —

    If specified, the response will contain an additional :matches value that is true if the object ETag matches the value for this option. If :matches is false, the :data value of the response will be nil.

  • :if_none_match (String) —

    If specified, the response will contain an additional :matches value that is true if and only if the object ETag matches the value for this option. If :matches is true, the :data value of the response will be nil.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the :sse_customer_algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :range (Range<Integer>) —

    A byte range of data to request.

Returns:



1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
 
# File 'lib/aws/s3/client.rb', line 1576

object_method(:head_object, :head,
              :header_options => {
                :if_modified_since => "If-Modified-Since",
                :if_unmodified_since => "If-Unmodified-Since",
                :if_match => "If-Match",
                :if_none_match => "If-None-Match",
                :sse_customer_algorithm => 'x-amz-server-side-encryption-customer-algorithm',
                :sse_customer_key => 'x-amz-server-side-encryption-customer-key',
                :sse_customer_key_md5 => 'x-amz-server-side-encryption-customer-key-MD5',
              }) do

  configure_request do |req, options|
    super(req, options)
    if options[:version_id]
      req.add_param('versionId', options[:version_id])
    end

    ["If-Modified-Since",
     "If-Unmodified-Since"].each do |date_header|
      case value = req.headers[date_header]
      when DateTime
        req.headers[date_header] = Time.parse(value.to_s).rfc2822
      when Time
        req.headers[date_header] = value.rfc2822
      end
    end

    if options[:range]
      range = options[:range]
      if range.is_a?(Range)
        offset = range.exclude_end? ? -1 : 0
        range = "bytes=#{range.first}-#{range.last + offset}"
      end
      req.headers['Range'] = range
    end
  end

  process_response do |resp|
    extract_object_headers(resp)
  end

end

#initiate_multipart_upload(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :key (required, String)
  • :website_redirect_location (String) —

    If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL.

  • :metadata (Hash)
  • :acl (Symbol)
  • :cache_control (String)
  • :content_disposition (String)
  • :content_encoding (String)
  • :content_type (String)
  • :storage_class+ (String) — default: 'STANDARD' —

    Controls whether Reduced Redundancy Storage is enabled for the object. Valid values are 'STANDARD' and 'REDUCED_REDUNDANCY'.

  • :server_side_encryption (Symbol, String) — default: nil —

    The algorithm used to encrypt the object on the server side (e.g. :aes256).

  • :expires (String) —

    The date and time at which the object is no longer cacheable.

  • :acl (String) —

    A canned ACL (e.g. 'private', 'public-read', etc). See the S3 API documentation for a complete list of valid values.

  • :grant_read (String)
  • :grant_write (String)
  • :grant_read_acp (String)
  • :grant_write_acp (String)
  • :grant_full_control (String)
  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the :sse_customer_algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

Returns:



1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
 
# File 'lib/aws/s3/client.rb', line 1737

object_method(:initiate_multipart_upload, :post, 'uploads',
              XML::InitiateMultipartUpload,
              :header_options => {
                :website_redirect_location => 'x-amz-website-redirect-location',
                :acl => 'x-amz-acl',
                :grant_read => 'x-amz-grant-read',
                :grant_write => 'x-amz-grant-write',
                :grant_read_acp => 'x-amz-grant-read-acp',
                :grant_write_acp => 'x-amz-grant-write-acp',
                :grant_full_control => 'x-amz-grant-full-control',
                :cache_control => 'Cache-Control',
                :content_disposition => 'Content-Disposition',
                :content_encoding => 'Content-Encoding',
                :content_type => 'Content-Type',
                :expires => 'Expires',
                :sse_customer_algorithm => 'x-amz-server-side-encryption-customer-algorithm',
                :sse_customer_key => 'x-amz-server-side-encryption-customer-key',
                :sse_customer_key_md5 => 'x-amz-server-side-encryption-customer-key-MD5',
              }) do

  configure_request do |req, options|
    set_metadata(req, options)
    set_storage_class(req, options)
    set_server_side_encryption(req, options)
    super(req, options)
  end

  process_response do |resp|
    extract_object_headers(resp)
  end

end

#list_buckets(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Returns:



915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
 
# File 'lib/aws/s3/client.rb', line 915

add_client_request_method(:list_buckets) do

  configure_request do |req, options|
    req.http_method = "GET"
  end

  process_response do |resp|
    resp.data = XML::ListBuckets.parse(resp.http_response.body)
  end

  simulate_response do |resp|
    resp.data = Core::XML::Parser.new(XML::ListBuckets.rules).simulate
  end

end

#list_multipart_uploads(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :delimiter (String)
  • :key_marker (String)
  • :max_keys (String)
  • :upload_id_marker (String)
  • :max_uploads (String)
  • :prefix (String)

Returns:



1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
 
# File 'lib/aws/s3/client.rb', line 1780

bucket_method(:list_multipart_uploads,
              :get, 'uploads',
              XML::ListMultipartUploads) do
  configure_request do |req, options|
    super(req, options)
    params = %w(delimiter key_marker max_keys) +
      %w(upload_id_marker max_uploads prefix)
    params.each do |param|
      if options[param.to_sym]
        req.add_param(param.gsub(/_/, '-'), options[param.to_sym])
      end
    end
  end
end

#list_object_versions(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :prefix (String)
  • :delimiter (String)
  • :max_keys (String)
  • :key_marker (String)
  • :version_id_marker (String)

Returns:



1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
 
# File 'lib/aws/s3/client.rb', line 1116

bucket_method(:list_object_versions, :get, 'versions',
  XML::ListObjectVersions) do

  configure_request do |req, options|
    super(req, options)
    params = %w(delimiter key_marker max_keys prefix version_id_marker)
    params.each do |param|
      if options[param.to_sym]
        req.add_param(param.gsub(/_/, '-'), options[param.to_sym])
      end
    end
  end

end

#list_objects(options = {}) ⇒ Core::Response Also known as: get_bucket

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :delimiter (String)
  • :marker (String)
  • :max_keys (String)
  • :prefix (String)

Returns:



1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
 
# File 'lib/aws/s3/client.rb', line 1680

bucket_method(:list_objects, :get, XML::ListObjects) do
  configure_request do |req, options|
    super(req, options)
    params = %w(delimiter marker max_keys prefix)
    params.each do |param|
      if options[param.to_sym]
        req.add_param(param.gsub(/_/, '-'), options[param.to_sym])
      end
    end
  end
end

#list_parts(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :key (required, String)
  • :upload_id (required, String)
  • :max_parts (Integer)
  • :part_number_marker (Integer)

Returns:



1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
 
# File 'lib/aws/s3/client.rb', line 1935

object_method(:list_parts, :get, XML::ListParts) do

  configure_request do |req, options|
      require_upload_id!(options[:upload_id])
    super(req, options)
    req.add_param('uploadId', options[:upload_id])
    req.add_param('max-parts', options[:max_parts])
    req.add_param('part-number-marker', options[:part_number_marker])
  end

end

#put_bucket_acl(options = {}) ⇒ Core::Response Also known as: set_bucket_acl

Sets the access control list for a bucket. You must specify an ACL via one of the following methods:

  • as a canned ACL (via :acl)
  • as a list of grants (via the :grant_* options)
  • as an access control policy document (via :access_control_policy)

Examples:

Using a canned acl

s3_client.put_bucket_acl(
  :bucket_name => 'bucket-name',
  :acl => 'public-read')

Using grants

s3_client.put_bucket_acl(
  :bucket_name => 'bucket-name',
  :grant_read => 'uri="http://acs.amazonaws.com/groups/global/AllUsers"',
  :grant_full_control => 'emailAddress="xyz@amazon.com", id="8a9...fa7"')

Using an access control policy document

policy_xml = <<-XML
  <AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Owner>
      <ID>852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID</ID>
      <DisplayName>OwnerDisplayName</DisplayName>
    </Owner>
    <AccessControlList>
      <Grant>
        <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
          <ID>BucketOwnerCanonicalUserID</ID>
          <DisplayName>OwnerDisplayName</DisplayName>
        </Grantee>
        <Permission>FULL_CONTROL</Permission>
      </Grant>
      <Grant>
        <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
          <URI xmlns="">http://acs.amazonaws.com/groups/global/AllUsers</URI>
        </Grantee>
        <Permission xmlns="">READ</Permission>
      </Grant>
    </AccessControlList>
  </AccessControlPolicy>

XML
s3_client.put_bucket_acl(
  :bucket_name => 'bucket-name',
  :access_control_policy => policy_xml)

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :access_control_policy (String) —

    An access control policy description as a string of XML. See the S3 API documentation for a description.

  • :acl (String) —

    A canned ACL (e.g. 'private', 'public-read', etc). See the S3 API documentation for a complete list of valid values.

  • :grant_read (String)
  • :grant_write (String)
  • :grant_read_acp (String)
  • :grant_write_acp (String)
  • :grant_full_control (String)

Returns:



1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
 
# File 'lib/aws/s3/client.rb', line 1193

bucket_method(:put_bucket_acl, :put, 'acl', :header_options => {
  :acl => 'x-amz-acl',
  :grant_read => 'x-amz-grant-read',
  :grant_write => 'x-amz-grant-write',
  :grant_read_acp => 'x-amz-grant-read-acp',
  :grant_write_acp => 'x-amz-grant-write-acp',
  :grant_full_control => 'x-amz-grant-full-control',
}) do

  configure_request do |req, options|
    move_access_control_policy(options)
    require_acl!(options)
    super(req, options)
    req.body = options[:access_control_policy] if
       options[:access_control_policy]
  end

end

#put_bucket_cors(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :rules (required, Array<Hash>) —

    An array of rule hashes. * :id - (String) A unique identifier for the rule. The ID value can be up to 255 characters long. The IDs help you find a rule in the configuration. * :allowed_methods - (required,Array) A list of HTTP methods that you want to allow the origin to execute. Each rule must identify at least one method. * :allowed_origins - (required,Array) A list of origins you want to allow cross-domain requests from. This can contain at most one * wild character. * :allowed_headers - (Array) A list of headers allowed in a pre-flight OPTIONS request via the Access-Control-Request-Headers header. Each header name specified in the Access-Control-Request-Headers header must have a corresponding entry in the rule. Amazon S3 will send only the allowed headers in a response that were requested. This can contain at most one * wild character. * :max_age_seconds - (Integer) The time in seconds that your browser is to cache the preflight response for the specified resource. * :expose_headers - (Array) One or more headers in the response that you want customers to be able to access from their applications (for example, from a JavaScript XMLHttpRequest object).

Returns:



776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
 
# File 'lib/aws/s3/client.rb', line 776

bucket_method(:put_bucket_cors, :put) do
  configure_request do |req, options|

    req.add_param('cors')

    options[:rules].each do |rule|
      require_allowed_methods!(rule[:allowed_methods])
      require_allowed_origins!(rule[:allowed_origins])
    end

    xml = Nokogiri::XML::Builder.new do |xml|
      xml.CORSConfiguration do
        options[:rules].each do |rule|
          xml.CORSRule do

            xml.ID(rule[:id]) if rule[:id]

            (rule[:allowed_methods] || []).each do |method|
              xml.AllowedMethod(method)
            end

            (rule[:allowed_origins] || []).each do |origin|
              xml.AllowedOrigin(origin)
            end

            (rule[:allowed_headers] || []).each do |header|
              xml.AllowedHeader(header)
            end

            xml.MaxAgeSeconds(rule[:max_age_seconds]) if
              rule[:max_age_seconds]

            (rule[:expose_headers] || []).each do |header|
              xml.ExposeHeader(header)
            end

          end
        end
      end
    end.doc.root.to_xml

    req.body = xml
    req.headers['content-md5'] = md5(xml)

    super(req, options)

  end
end

#put_bucket_logging(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :logging_enabled (Boolean) —

    Set to true if turning on bucket logging. If not set or false, all of the following options will be ignored.

  • :target_bucket (String) —

    The name of the bucket in which you want Amazon S3 to store server access logs. You can push logs to any bucket you own, including the bucket being logged.

  • :target_prefix (String) —

    Allows you to specify a prefix for the keys that the log files will be stored under. Recommended if you will be writing logs from multiple buckets to the same target bucket.

  • :grants (Array<Hash>) —

    An array of hashes specifying permission grantees. For each hash, specify ONLY ONE of :id, :uri, or :email_address. * :email_address - (String) E-mail address of the person being granted logging permissions. * :id - (String) The canonical user ID of the grantee. * :uri - (String) URI of the grantee group. * :permission - (String) Logging permissions given to the Grantee for the bucket. The bucket owner is automatically granted FULL_CONTROL to all logs delivered to the bucket. This optional element enables you grant access to others. Valid Values: FULL_CONTROL | READ | WRITE

Returns:



1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
 
# File 'lib/aws/s3/client.rb', line 1041

bucket_method(:put_bucket_logging, :put) do
  configure_request do |req, options|

    req.add_param('logging')

    xml = Nokogiri::XML::Builder.new
    xml.BucketLoggingStatus('xmlns' => XMLNS) do |xml|
      if options[:logging_enabled] == true
        xml.LoggingEnabled do
          xml.TargetBucket(options[:target_bucket])
          xml.TargetPrefix(options[:target_prefix])
          unless options[:grants].nil?

            xml.TargetGrants do
              options[:grants].each do |grant|
                xml.Grant do
                  if !grant[:email_address].nil?
                    xml.Grantee('xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance',
                            'xsi:type' => 'AmazonCustomerByEmail') do
                      xml.EmailAddress(grant[:email_address])
                    end
                  elsif !grant[:uri].nil?
                    xml.Grantee('xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance',
                            'xsi:type' => 'Group') do
                      xml.URI(grant[:uri])
                    end
                  elsif !grant[:id].nil?
                    xml.Grantee('xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance',
                            'xsi:type' => 'CanonicalUser') do
                      xml.ID(grant[:id])
                    end
                  end

                  xml.Permission(grant[:permission])
                end
              end
            end
          end
        end
      end
    end

    xml = xml.doc.root.to_xml
    req.body = xml
    req.headers['content-md5'] = md5(xml)

    super(req, options)

  end
end

#put_bucket_tagging(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :tags (Hash)

Returns:



858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
 
# File 'lib/aws/s3/client.rb', line 858

bucket_method(:put_bucket_tagging, :put) do
  configure_request do |req, options|

    req.add_param('tagging')

    xml = Nokogiri::XML::Builder.new
    xml.Tagging do |xml|
      xml.TagSet do
        options[:tags].each_pair do |key,value|
          xml.Tag do
            xml.Key(key)
            xml.Value(value)
          end
        end
      end
    end

    xml = xml.doc.root.to_xml
    req.body = xml
    req.headers['content-md5'] = md5(xml)

    super(req, options)

  end
end

#put_bucket_website(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)

Returns:



617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
 
# File 'lib/aws/s3/client.rb', line 617

bucket_method(:put_bucket_website, :put, 'website') do

  configure_request do |req, options|
    req.body = Nokogiri::XML::Builder.new do |xml|
      xml.WebsiteConfiguration(:xmlns => XMLNS) do

        if redirect = options[:redirect_all_requests_to]
          xml.RedirectAllRequestsTo do
            xml.HostName(redirect[:host_name])
            xml.Protocol(redirect[:protocol]) if redirect[:protocol]
          end
        end

        if indx = options[:index_document]
          xml.IndexDocument do
            xml.Suffix(indx[:suffix])
          end
        end

        if err = options[:error_document]
          xml.ErrorDocument do
            xml.Key(err[:key])
          end
        end

        rules = options[:routing_rules]
        if rules.is_a?(Array) && !rules.empty?
          xml.RoutingRules do
            rules.each do |rule|
              xml.RoutingRule do

                redirect = rule[:redirect]
                xml.Redirect do
                  xml.Protocol(redirect[:protocol]) if redirect[:protocol]
                  xml.HostName(redirect[:host_name]) if redirect[:host_name]
                  xml.ReplaceKeyPrefixWith(redirect[:replace_key_prefix_with]) if redirect[:replace_key_prefix_with]
                  xml.ReplaceKeyWith(redirect[:replace_key_with]) if redirect[:replace_key_with]
                  xml.HttpRedirectCode(redirect[:http_redirect_code]) if redirect[:http_redirect_code]
                end

                if condition = rule[:condition]
                  xml.Condition do
                    xml.KeyPrefixEquals(condition[:key_prefix_equals]) if condition[:key_prefix_equals]
                    xml.HttpErrorCodeReturnedEquals(condition[:http_error_code_returned_equals]) if condition[:http_error_code_returned_equals]
                  end
                end

              end
            end
          end
        end

      end
    end.doc.root.to_xml
    super(req, options)
  end

end

#put_object(options = {}) ⇒ Core::Response

Puts data into an object, replacing the current contents.

s3_client.put_object({ :bucket_name => 'bucket-name', :key => 'readme.txt', :data => 'This is the readme for ...', })

object on the server side, e.g. :aes256)

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :key (required, String)
  • :data (required, String, Pathname, File, IO) —

    The data to upload. This can be provided as a string, a Pathname object, or any object that responds to #read and #eof? (e.g. IO, File, Tempfile, StringIO, etc).

  • :content_length (Integer) —

    Required if you are using block form to write data or if it is not possible to determine the size of :data. A best effort is made to determine the content length of strings, files, tempfiles, io objects, and any object that responds to #length or #size.

  • :website_redirect_location (String) —

    If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL.

  • :metadata (Hash) —

    A hash of metadata to be included with the object. These will be sent to S3 as headers prefixed with x-amz-meta.

  • :acl (Symbol) — default: :private —

    A canned access control policy. Accepted values include: * :private * :public_read * ...

  • :storage_class+ (String) — default: 'STANDARD' —

    Controls whether Reduced Redundancy Storage is enabled for the object. Valid values are 'STANDARD' and 'REDUCED_REDUNDANCY'.

  • :server_side_encryption (Symbol, String) — default: nil —

    The algorithm used to encrypt the object on the server side (e.g. :aes256).

  • :cache_control (String) —

    Can be used to specify caching behavior.

  • :content_disposition (String) —

    Specifies presentational information.

  • :content_encoding (String) —

    Specifies the content encoding.

  • :content_md5 (String) —

    The base64 encoded content md5 of the :data.

  • :content_type (String) —

    Specifies the content type.

  • :expires (String) —

    The date and time at which the object is no longer cacheable.

  • :acl (String) —

    A canned ACL (e.g. 'private', 'public-read', etc). See the S3 API documentation for a complete list of valid values.

  • :grant_read (String)
  • :grant_write (String)
  • :grant_read_acp (String)
  • :grant_write_acp (String)
  • :grant_full_control (String)
  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the :sse_customer_algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

Returns:



1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
 
# File 'lib/aws/s3/client.rb', line 1390

object_method(:put_object, :put, :header_options => {
  :website_redirect_location => 'x-amz-website-redirect-location',
  :acl => 'x-amz-acl',
  :grant_read => 'x-amz-grant-read',
  :grant_write => 'x-amz-grant-write',
  :grant_read_acp => 'x-amz-grant-read-acp',
  :grant_write_acp => 'x-amz-grant-write-acp',
  :grant_full_control => 'x-amz-grant-full-control',
  :content_md5 => 'Content-MD5',
  :cache_control => 'Cache-Control',
  :content_disposition => 'Content-Disposition',
  :content_encoding => 'Content-Encoding',
  :content_type => 'Content-Type',
  :expires => 'Expires',
  :sse_customer_algorithm => 'x-amz-server-side-encryption-customer-algorithm',
  :sse_customer_key => 'x-amz-server-side-encryption-customer-key',
  :sse_customer_key_md5 => 'x-amz-server-side-encryption-customer-key-MD5',
}) do

  configure_request do |request, options|

    options = compute_write_options(options)
    set_body_stream_and_content_length(request, options)

    set_metadata(request, options)
    set_storage_class(request, options)
    set_server_side_encryption(request, options)

    super(request, options)

  end

  process_response do |resp|
    extract_object_headers(resp)
  end

  simulate_response do |response|
    response.data[:etag] = 'abc123'
    response.data[:version_id] = nil
  end

end

#put_object_acl(options = {}) ⇒ Core::Response Also known as: set_object_acl

Sets the access control list for an object. You must specify an ACL via one of the following methods:

  • as a canned ACL (via :acl)
  • as a list of grants (via the :grant_* options)
  • as an access control policy document (via :access_control_policy)

Examples:

Using a canned acl

s3_client.put_object_acl(
  :bucket_name => 'bucket-name',
  :key => 'object-key',
  :acl => 'public-read')

Using grants

s3_client.put_bucket_acl(
  :bucket_name => 'bucket-name',
  :key => 'object-key',
  :grant_read => 'uri="http://acs.amazonaws.com/groups/global/AllUsers"',
  :grant_full_control => 'emailAddress="xyz@amazon.com", id="8a9...fa7"')

Using an access control policy document

policy_xml = <<-XML
  <AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Owner>
      <ID>852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID</ID>
      <DisplayName>OwnerDisplayName</DisplayName>
    </Owner>
    <AccessControlList>
      <Grant>
        <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
          <ID>BucketOwnerCanonicalUserID</ID>
          <DisplayName>OwnerDisplayName</DisplayName>
        </Grantee>
        <Permission>FULL_CONTROL</Permission>
      </Grant>
      <Grant>
        <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
          <URI xmlns="">http://acs.amazonaws.com/groups/global/AllUsers</URI>
        </Grantee>
        <Permission xmlns="">READ</Permission>
      </Grant>
    </AccessControlList>
  </AccessControlPolicy>

XML
s3_client.put_bucket_acl(
  :bucket_name => 'bucket-name',
  :key => 'object-key',
  :access_control_policy => policy_xml)

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :key (required, String)
  • :access_control_policy (String) —

    An access control policy description as a string of XML. See the S3 API documentation for a description.

  • :acl (String) —

    A canned ACL (e.g. 'private', 'public-read', etc). See the S3 API documentation for a complete list of valid values.

  • :grant_read (String)
  • :grant_write (String)
  • :grant_read_acp (String)
  • :grant_write_acp (String)
  • :grant_full_control (String)

Returns:



1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
 
# File 'lib/aws/s3/client.rb', line 1286

object_method(:put_object_acl, :put, 'acl', :header_options => {
  :acl => 'x-amz-acl',
  :grant_read => 'x-amz-grant-read',
  :grant_write => 'x-amz-grant-write',
  :grant_read_acp => 'x-amz-grant-read-acp',
  :grant_write_acp => 'x-amz-grant-write-acp',
  :grant_full_control => 'x-amz-grant-full-control',
}) do

  configure_request do |req, options|
    move_access_control_policy(options)
    require_acl!(options)
    super(req, options)
    req.body = options[:access_control_policy] if
       options[:access_control_policy]
  end

end

#restore_object(options = {}) ⇒ Core::Response

Restores a temporary copy of an archived object.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :key (required, String)
  • :days (required, Integer) —

    the number of days to keep the restored object.

Returns:

Since:

  • 1.7.2



1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
 
# File 'lib/aws/s3/client.rb', line 1650

object_method(:restore_object, :post, 'restore',
    :header_options => { :content_md5 => 'Content-MD5' }) do
  configure_request do |req, options|
    super(req, options)

    validate!(:days, options[:days]) do
      "must be greater or equal to 1" if options[:days].to_i <= 0
    end

    xml = Nokogiri::XML::Builder.new do |xml|
      xml.RestoreRequest('xmlns' => XMLNS) do
        xml.Days(options[:days].to_i) if options[:days]
      end
    end.doc.root.to_xml

    req.body = xml
    req.headers['content-type'] = 'application/xml'
    req.headers['content-md5'] = md5(xml)
  end
end

#set_bucket_lifecycle_configuration(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :lifecycle_configuration (required, String)

Returns:



704
705
706
707
708
709
710
711
712
713
714
 
# File 'lib/aws/s3/client.rb', line 704

bucket_method(:set_bucket_lifecycle_configuration, :put) do

  configure_request do |req, options|
    xml = options[:lifecycle_configuration]
    req.add_param('lifecycle')
    req.body = xml
    req.headers['content-md5'] = md5(xml)
    super(req, options)
  end

end

#set_bucket_policy(options = {}) ⇒ Core::Response

Sets the access policy for a bucket.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :policy (required, String) —

    This can be a String or any object that responds to #to_json.

Returns:



938
939
940
941
942
943
944
945
946
947
948
 
# File 'lib/aws/s3/client.rb', line 938

bucket_method(:set_bucket_policy, :put, 'policy') do

  configure_request do |req, options|
    require_policy!(options[:policy])
    super(req, options)
    policy = options[:policy]
    policy = policy.to_json unless policy.respond_to?(:to_str)
    req.body = policy
  end

end

#set_bucket_versioning(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :state (required, String)
  • :mfa_delete (String)
  • :mfa (String)

Returns:



977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
 
# File 'lib/aws/s3/client.rb', line 977

bucket_method(:set_bucket_versioning, :put, 'versioning', :header_options => { :mfa => "x-amz-mfa" }) do

  configure_request do |req, options|
    state = options[:state].to_s.downcase.capitalize
    unless state =~ /^(Enabled|Suspended)$/
      raise ArgumentError, "invalid versioning state `#{state}`"
    end

    # Leave validation of MFA options to S3
    mfa_delete = options[:mfa_delete].to_s.downcase.capitalize if options[:mfa_delete]

    # Generate XML request for versioning
    req.body = Nokogiri::XML::Builder.new do |xml|
      xml.VersioningConfiguration('xmlns' => XMLNS) do
        xml.Status(state)
        xml.MfaDelete(mfa_delete) if mfa_delete
      end
    end.doc.root.to_xml

    super(req, options)
  end

end

#upload_part(options = {}) ⇒ Core::Response

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket_name (required, String)
  • :key (required, String)
  • :upload_id (required, String)
  • :part_number (required, Integer)
  • :data (required, String, Pathname, File, IO) —

    The data to upload. This can be provided as a string, a Pathname object, or any object that responds to #read and #eof? (e.g. IO, File, Tempfile, StringIO, etc).

Returns:



1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
 
# File 'lib/aws/s3/client.rb', line 1841

object_method(:upload_part, :put,
              :header_options => {
                :content_md5 => 'Content-MD5',
                :sse_customer_algorithm => 'x-amz-server-side-encryption-customer-algorithm',
                :sse_customer_key => 'x-amz-server-side-encryption-customer-key',
                :sse_customer_key_md5 => 'x-amz-server-side-encryption-customer-key-MD5',
              }) do
  configure_request do |request, options|

    options = compute_write_options(options)
    set_body_stream_and_content_length(request, options)

    require_upload_id!(options[:upload_id])
    request.add_param('uploadId', options[:upload_id])

    require_part_number!(options[:part_number])
    request.add_param('partNumber', options[:part_number])

    super(request, options)

  end

  process_response do |resp|
    extract_object_headers(resp)
  end

  simulate_response do |response|
    response.data[:etag] = 'abc123'
  end
end