Initialize connection to S3
options parameter must include values for :aws_access_key_id and :aws_secret_access_key in order to create a connection
s3 = Fog::Storage.new( :provider => "AWS", :aws_access_key_id => your_aws_access_key_id, :aws_secret_access_key => your_aws_secret_access_key )
options<~Hash> - config arguments for connection. Defaults to {}.
S3 object with connection to aws.
# File lib/fog/aws/storage.rb, line 259 def initialize(options={}) require 'fog/core/parser' require 'mime/types' @use_iam_profile = options[:use_iam_profile] setup_credentials(options) @connection_options = options[:connection_options] || {} if @endpoint = options[:endpoint] endpoint = URI.parse(@endpoint) @host = endpoint.host @path = if endpoint.path.empty? '/' else endpoint.path end @port = endpoint.port @scheme = endpoint.scheme else options[:region] ||= 'us-east-1' @region = options[:region] @host = options[:host] || case options[:region] when 'us-east-1' 's3.amazonaws.com' else "s3-#{options[:region]}.amazonaws.com" end @path = options[:path] || '/' @persistent = options.fetch(:persistent, false) @port = options[:port] || 443 @scheme = options[:scheme] || 'https' end @connection = Fog::Connection.new("#{@scheme}://#{@host}:#{@port}#{@path}", @persistent, @connection_options) end
Abort a multipart upload
bucket_name<~String> - Name of bucket to abort multipart upload on
object_name<~String> - Name of object to abort multipart upload on
upload_id<~String> - Id of upload to add part to
docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadAbort.html
# File lib/fog/aws/requests/storage/abort_multipart_upload.rb, line 16 def abort_multipart_upload(bucket_name, object_name, upload_id) request({ :expects => 204, :headers => {}, :host => "#{bucket_name}.#{@host}", :method => 'DELETE', :path => CGI.escape(object_name), :query => {'uploadId' => upload_id} }) end
Complete a multipart upload
bucket_name<~String> - Name of bucket to complete multipart upload for
object_name<~String> - Name of object to complete multipart upload for
upload_id<~String> - Id of upload to add part to
parts<~Array>: Array of etags for parts
:etag<~String> - Etag for this part
response<~Excon::Response>:
headers<~Hash>:
'Bucket'<~String> - bucket of new object
'ETag'<~String> - etag of new object (will be needed to complete upload)
'Key'<~String> - key of new object
'Location'<~String> - location of new object
docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadComplete.html
# File lib/fog/aws/requests/storage/complete_multipart_upload.rb, line 28 def complete_multipart_upload(bucket_name, object_name, upload_id, parts) data = "<CompleteMultipartUpload>" parts.each_with_index do |part, index| data << "<Part>" data << "<PartNumber>#{index + 1}</PartNumber>" data << "<ETag>#{part}</ETag>" data << "</Part>" end data << "</CompleteMultipartUpload>" request({ :body => data, :expects => 200, :headers => { 'Content-Length' => data.length }, :host => "#{bucket_name}.#{@host}", :method => 'POST', :parser => Fog::Parsers::Storage::AWS::CompleteMultipartUpload.new, :path => CGI.escape(object_name), :query => {'uploadId' => upload_id} }) end
Copy an object from one S3 bucket to another
source_bucket_name<~String> - Name of source bucket
source_object_name<~String> - Name of source object
target_bucket_name<~String> - Name of bucket to create copy in
target_object_name<~String> - Name for new copy of object
options<~Hash>:
'x-amz-metadata-directive'<~String> - Specifies whether to copy metadata from source or replace with data in request. Must be in ['COPY', 'REPLACE']
'x-amz-copy_source-if-match'<~String> - Copies object if its etag matches this value
'x-amz-copy_source-if-modified_since'<~Time> - Copies object it it has been modified since this time
'x-amz-copy_source-if-none-match'<~String> - Copies object if its etag does not match this value
'x-amz-copy_source-if-unmodified-since'<~Time> - Copies object it it has not been modified since this time
'x-amz-storage-class'<~String> - Default is 'STANDARD', set to 'REDUCED_REDUNDANCY' for non-critical, reproducable data
response<~Excon::Response>:
body<~Hash>:
'ETag'<~String> - etag of new object
'LastModified'<~Time> - date object was last modified
docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectCOPY.html
# File lib/fog/aws/requests/storage/copy_object.rb, line 32 def copy_object(source_bucket_name, source_object_name, target_bucket_name, target_object_name, options = {}) headers = { 'x-amz-copy-source' => "/#{source_bucket_name}/#{CGI.escape(source_object_name)}" }.merge!(options) request({ :expects => 200, :headers => headers, :host => "#{target_bucket_name}.#{@host}", :method => 'PUT', :parser => Fog::Parsers::Storage::AWS::CopyObject.new, :path => CGI.escape(target_object_name) }) end
Delete an S3 bucket
bucket_name<~String> - name of bucket to delete
response<~Excon::Response>:
status<~Integer> - 204
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketDELETE.html
# File lib/fog/aws/requests/storage/delete_bucket.rb, line 18 def delete_bucket(bucket_name) request({ :expects => 204, :headers => {}, :host => "#{bucket_name}.#{@host}", :method => 'DELETE' }) end
Delete lifecycle configuration for a bucket
bucket_name<~String> - name of bucket to delete lifecycle configuration from
response<~Excon::Response>:
status<~Integer> - 204
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketDELETElifecycle.html
# File lib/fog/aws/requests/storage/delete_bucket_lifecycle.rb, line 18 def delete_bucket_lifecycle(bucket_name) request({ :expects => 204, :headers => {}, :host => "#{bucket_name}.#{@host}", :method => 'DELETE', :query => {'lifecycle' => nil} }) end
Delete policy for a bucket
bucket_name<~String> - name of bucket to delete policy from
response<~Excon::Response>:
status<~Integer> - 204
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketDELETEpolicy.html
# File lib/fog/aws/requests/storage/delete_bucket_policy.rb, line 18 def delete_bucket_policy(bucket_name) request({ :expects => 204, :headers => {}, :host => "#{bucket_name}.#{@host}", :method => 'DELETE', :query => {'policy' => nil} }) end
Delete website configuration for a bucket
bucket_name<~String> - name of bucket to delete website configuration from
response<~Excon::Response>:
status<~Integer> - 204
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketDELETEwebsite.html
# File lib/fog/aws/requests/storage/delete_bucket_website.rb, line 18 def delete_bucket_website(bucket_name) request({ :expects => 204, :headers => {}, :host => "#{bucket_name}.#{@host}", :method => 'DELETE', :query => {'website' => nil} }) end
Delete an object from S3
bucket_name<~String> - Name of bucket containing object to delete
object_name<~String> - Name of object to delete
response<~Excon::Response>:
status<~Integer> - 204
docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectDELETE.html
# File lib/fog/aws/requests/storage/delete_object.rb, line 19 def delete_object(bucket_name, object_name, options = {}) if version_id = options.delete('versionId') path = "#{CGI.escape(object_name)}?versionId=#{CGI.escape(version_id)}" else path = CGI.escape(object_name) end headers = options request({ :expects => 204, :headers => headers, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'DELETE', :path => path }) end
List information about objects in an S3 bucket
bucket_name<~String> - name of bucket to list object keys from
options<~Hash> - config arguments for list. Defaults to {}.
'delimiter'<~String> - causes keys with the same string between the prefix value and the first occurence of delimiter to be rolled up
'marker'<~String> - limits object keys to only those that appear lexicographically after its value.
'max-keys'<~Integer> - limits number of object keys returned
'prefix'<~String> - limits object keys to those beginning with its value.
response<~Excon::Response>:
body<~Hash>:
'Delimeter'<~String> - Delimiter specified for query
'IsTruncated'<~Boolean> - Whether or not the listing is truncated
'Marker'<~String> - Marker specified for query
'MaxKeys'<~Integer> - Maximum number of keys specified for query
'Name'<~String> - Name of the bucket
'Prefix'<~String> - Prefix specified for query
'CommonPrefixes'<~Array> - Array of strings for common prefixes
'Contents'<~Array>:
'ETag'<~String>: Etag of object
'Key'<~String>: Name of object
'LastModified'<~String>: Timestamp of last modification of object
'Owner'<~Hash>:
'DisplayName'<~String> - Display name of object owner
'ID'<~String> - Id of object owner
'Size'<~Integer> - Size of object
'StorageClass'<~String> - Storage class of object
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGET.html
# File lib/fog/aws/requests/storage/get_bucket.rb, line 43 def get_bucket(bucket_name, options = {}) unless bucket_name raise ArgumentError.new('bucket_name is required') end request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::Storage::AWS::GetBucket.new, :query => options }) end
Get access control list for an S3 bucket
bucket_name<~String> - name of bucket to get access control list for
response<~Excon::Response>:
body<~Hash>:
'AccessControlPolicy'<~Hash>
'Owner'<~Hash>:
'DisplayName'<~String> - Display name of object owner
'ID'<~String> - Id of object owner
'AccessControlList'<~Array>:
'Grant'<~Hash>:
'Grantee'<~Hash>:
* 'DisplayName'<~String> - Display name of grantee * 'ID'<~String> - Id of grantee
or
* 'URI'<~String> - URI of group to grant access for
'Permission'<~String> - Permission, in [FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP]
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETacl.html
# File lib/fog/aws/requests/storage/get_bucket_acl.rb, line 32 def get_bucket_acl(bucket_name) unless bucket_name raise ArgumentError.new('bucket_name is required') end request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::Storage::AWS::AccessControlList.new, :query => {'acl' => nil} }) end
Get bucket lifecycle configuration
bucket_name<~String> - name of bucket to get lifecycle configuration for
response<~Excon::Response>:
body<~Hash>:
'Rules'<~Array> - object expire rules
* 'ID'<~String> - Unique identifier for the rule * 'Prefix'<~String> - Prefix identifying one or more objects to which the rule applies * 'Enabled'<~Boolean> - if rule is currently being applied * 'Days'<~Integer> - lifetime, in days, of the objects that are subject to the rule
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETlifecycle.html
# File lib/fog/aws/requests/storage/get_bucket_lifecycle.rb, line 25 def get_bucket_lifecycle(bucket_name) request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::Storage::AWS::GetBucketLifecycle.new, :query => {'lifecycle' => nil} }) end
Get location constraint for an S3 bucket
bucket_name<~String> - name of bucket to get location constraint for
response<~Excon::Response>:
body<~Hash>:
'LocationConstraint'<~String> - Location constraint of the bucket
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETlocation.html
# File lib/fog/aws/requests/storage/get_bucket_location.rb, line 21 def get_bucket_location(bucket_name) request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::Storage::AWS::GetBucketLocation.new, :query => {'location' => nil} }) end
Get logging status for an S3 bucket
bucket_name<~String> - name of bucket to get logging status for
response<~Excon::Response>:
body<~Hash>:
'BucketLoggingStatus'<~Hash>: (will be empty if logging is disabled)
'LoggingEnabled'<~Hash>:
'TargetBucket'<~String> - bucket where logs are stored
'TargetPrefix'<~String> - prefix logs are stored with
'TargetGrants'<~Array>:
'Grant'<~Hash>:
'Grantee'<~Hash>:
* 'DisplayName'<~String> - Display name of grantee * 'ID'<~String> - Id of grantee
or
* 'URI'<~String> - URI of group to grant access for
'Permission'<~String> - Permission, in [FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP]
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETlogging.html
# File lib/fog/aws/requests/storage/get_bucket_logging.rb, line 32 def get_bucket_logging(bucket_name) unless bucket_name raise ArgumentError.new('bucket_name is required') end request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::Storage::AWS::GetBucketLogging.new, :query => {'logging' => nil} }) end
List information about object versions in an S3 bucket
bucket_name<~String> - name of bucket to list object keys from
options<~Hash> - config arguments for list. Defaults to {}.
'delimiter'<~String> - causes keys with the same string between the prefix value and the first occurence of delimiter to be rolled up
'key-marker'<~String> - limits object keys to only those that appear lexicographically after its value.
'max-keys'<~Integer> - limits number of object keys returned
'prefix'<~String> - limits object keys to those beginning with its value.
'version-id-marker'<~String> - limits object versions to only those that appear lexicographically after its value
response<~Excon::Response>:
body<~Hash>:
'Delimeter'<~String> - Delimiter specified for query
'KeyMarker'<~String> - Key marker specified for query
'MaxKeys'<~Integer> - Maximum number of keys specified for query
'Name'<~String> - Name of the bucket
'Prefix'<~String> - Prefix specified for query
'VersionIdMarker'<~String> - Version id marker specified for query
'IsTruncated'<~Boolean> - Whether or not this is the totality of the bucket
'Versions'<~Array>:
* 'DeleteMarker'<~Hash>: * 'IsLatest'<~Boolean> - Whether or not this is the latest version * 'Key'<~String> - Name of object * 'LastModified'<~String>: Timestamp of last modification of object * 'Owner'<~Hash>: * 'DisplayName'<~String> - Display name of object owner * 'ID'<~String> - Id of object owner * 'VersionId'<~String> - The id of this version
or
* 'Version'<~Hash>: * 'ETag'<~String>: Etag of object * 'IsLatest'<~Boolean> - Whether or not this is the latest version * 'Key'<~String> - Name of object * 'LastModified'<~String>: Timestamp of last modification of object * 'Owner'<~Hash>: * 'DisplayName'<~String> - Display name of object owner * 'ID'<~String> - Id of object owner * 'Size'<~Integer> - Size of object * 'StorageClass'<~String> - Storage class of object * 'VersionId'<~String> - The id of this version
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETVersion.html
# File lib/fog/aws/requests/storage/get_bucket_object_versions.rb, line 57 def get_bucket_object_versions(bucket_name, options = {}) unless bucket_name raise ArgumentError.new('bucket_name is required') end request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::Storage::AWS::GetBucketObjectVersions.new, :query => {'versions' => nil}.merge!(options) }) end
Get bucket policy for an S3 bucket
bucket_name<~String> - name of bucket to get policy for
response<~Excon::Response>:
body<~Hash> - policy document
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETpolicy.html
# File lib/fog/aws/requests/storage/get_bucket_policy.rb, line 18 def get_bucket_policy(bucket_name) unless bucket_name raise ArgumentError.new('bucket_name is required') end response = request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :query => {'policy' => nil} }) response.body = Fog::JSON.decode(response.body) unless response.body.nil? end
Get versioning status for an S3 bucket
bucket_name<~String> - name of bucket to get versioning status for
response<~Excon::Response>:
body<~Hash>:
'VersioningConfiguration'<~Hash>
* Status<~String>: Versioning status in ['Enabled', 'Suspended', nil]
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETversioningStatus.html
# File lib/fog/aws/requests/storage/get_bucket_versioning.rb, line 22 def get_bucket_versioning(bucket_name) unless bucket_name raise ArgumentError.new('bucket_name is required') end request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::Storage::AWS::GetBucketVersioning.new, :query => {'versioning' => nil} }) end
Get website configuration for an S3 bucket
bucket_name<~String> - name of bucket to get website configuration for
response<~Excon::Response>:
body<~Hash>:
IndexDocument<~Hash>
Suffix<~String> - Suffix appended when directory is requested
ErrorDocument<~Hash>
Key<~String> - Object key to return for 4XX class errors
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETwebsite.html
# File lib/fog/aws/requests/storage/get_bucket_website.rb, line 24 def get_bucket_website(bucket_name) unless bucket_name raise ArgumentError.new('bucket_name is required') end request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::Storage::AWS::GetBucketWebsite.new, :query => {'website' => nil} }) end
Get an object from S3
bucket_name<~String> - Name of bucket to read from
object_name<~String> - Name of object to read
options<~Hash>:
'If-Match'<~String> - Returns object only if its etag matches this value, otherwise returns 412 (Precondition Failed).
'If-Modified-Since'<~Time> - Returns object only if it has been modified since this time, otherwise returns 304 (Not Modified).
'If-None-Match'<~String> - Returns object only if its etag differs from this value, otherwise returns 304 (Not Modified)
'If-Unmodified-Since'<~Time> - Returns object only if it has not been modified since this time, otherwise returns 412 (Precodition Failed).
'Range'<~String> - Range of object to download
'versionId'<~String> - specify a particular version to retrieve
response<~Excon::Response>:
body<~String> - Contents of object
headers<~Hash>:
'Content-Length'<~String> - Size of object contents
'Content-Type'<~String> - MIME type of object
'ETag'<~String> - Etag of object
'Last-Modified'<~String> - Last modified timestamp for object
docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectGET.html
# File lib/fog/aws/requests/storage/get_object.rb, line 31 def get_object(bucket_name, object_name, options = {}, &block) unless bucket_name raise ArgumentError.new('bucket_name is required') end unless object_name raise ArgumentError.new('object_name is required') end params = { :headers => {} } if version_id = options.delete('versionId') params[:query] = {'versionId' => version_id} end params[:headers].merge!(options) if options['If-Modified-Since'] params[:headers]['If-Modified-Since'] = Fog::Time.at(options['If-Modified-Since'].to_i).to_date_header end if options['If-Unmodified-Since'] params[:headers]['If-Unmodified-Since'] = Fog::Time.at(options['If-Unmodified-Since'].to_i).to_date_header end if block_given? params[:response_block] = Proc.new end request(params.merge!({ :expects => [ 200, 206 ], :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :path => CGI.escape(object_name), })) end
Get access control list for an S3 object
bucket_name<~String> - name of bucket containing object
object_name<~String> - name of object to get access control list for
options<~Hash>:
'versionId'<~String> - specify a particular version to retrieve
response<~Excon::Response>:
body<~Hash>:
'AccessControlPolicy'<~Hash>
'Owner'<~Hash>:
'DisplayName'<~String> - Display name of object owner
'ID'<~String> - Id of object owner
'AccessControlList'<~Array>:
'Grant'<~Hash>:
'Grantee'<~Hash>:
* 'DisplayName'<~String> - Display name of grantee * 'ID'<~String> - Id of grantee
or
* 'URI'<~String> - URI of group to grant access for
'Permission'<~String> - Permission, in [FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP]
docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectGETacl.html
# File lib/fog/aws/requests/storage/get_object_acl.rb, line 35 def get_object_acl(bucket_name, object_name, options = {}) unless bucket_name raise ArgumentError.new('bucket_name is required') end unless object_name raise ArgumentError.new('object_name is required') end query = {'acl' => nil} if version_id = options.delete('versionId') query['versionId'] = version_id end request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::Storage::AWS::AccessControlList.new, :path => CGI.escape(object_name), :query => query }) end
Get torrent for an S3 object
bucket_name<~String> - name of bucket containing object
object_name<~String> - name of object to get torrent for
response<~Excon::Response>:
body<~Hash>:
'AccessControlPolicy'<~Hash>
'Owner'<~Hash>:
'DisplayName'<~String> - Display name of object owner
'ID'<~String> - Id of object owner
'AccessControlList'<~Array>:
'Grant'<~Hash>:
'Grantee'<~Hash>:
'DisplayName'<~String> - Display name of grantee
'ID'<~String> - Id of grantee
'Permission'<~String> - Permission, in [FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP]
docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectGETtorrent.html
# File lib/fog/aws/requests/storage/get_object_torrent.rb, line 29 def get_object_torrent(bucket_name, object_name) unless bucket_name raise ArgumentError.new('bucket_name is required') end unless object_name raise ArgumentError.new('object_name is required') end request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :path => CGI.escape(object_name), :query => {'torrent' => nil} }) end
Get configured payer for an S3 bucket
bucket_name<~String> - name of bucket to get payer for
response<~Excon::Response>:
body<~Hash>:
'Payer'<~String> - Specifies who pays for download and requests
docs.amazonwebservices.com/AmazonS3/latest/API/RESTrequestPaymentGET.html
# File lib/fog/aws/requests/storage/get_request_payment.rb, line 21 def get_request_payment(bucket_name) request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::Storage::AWS::GetRequestPayment.new, :query => {'requestPayment' => nil} }) end
List information about S3 buckets for authorized user
response<~Excon::Response>:
body<~Hash>:
'Buckets'<~Hash>:
'Name'<~String> - Name of bucket
'CreationTime'<~Time> - Timestamp of bucket creation
'Owner'<~Hash>:
'DisplayName'<~String> - Display name of bucket owner
'ID'<~String> - Id of bucket owner
docs.amazonwebservices.com/AmazonS3/latest/API/RESTServiceGET.html
# File lib/fog/aws/requests/storage/get_service.rb, line 23 def get_service request({ :expects => 200, :headers => {}, :host => @host, :idempotent => true, :method => 'GET', :parser => Fog::Parsers::Storage::AWS::GetService.new, :url => @host }) end
Get headers for an object from S3
bucket_name<~String> - Name of bucket to read from
object_name<~String> - Name of object to read
options<~Hash>:
'If-Match'<~String> - Returns object only if its etag matches this value, otherwise returns 412 (Precondition Failed).
'If-Modified-Since'<~Time> - Returns object only if it has been modified since this time, otherwise returns 304 (Not Modified).
'If-None-Match'<~String> - Returns object only if its etag differs from this value, otherwise returns 304 (Not Modified)
'If-Unmodified-Since'<~Time> - Returns object only if it has not been modified since this time, otherwise returns 412 (Precodition Failed).
'Range'<~String> - Range of object to download
'versionId'<~String> - specify a particular version to retrieve
response<~Excon::Response>:
body<~String> - Contents of object
headers<~Hash>:
'Content-Length'<~String> - Size of object contents
'Content-Type'<~String> - MIME type of object
'ETag'<~String> - Etag of object
'Last-Modified'<~String> - Last modified timestamp for object
docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectHEAD.html
# File lib/fog/aws/requests/storage/head_object.rb, line 31 def head_object(bucket_name, object_name, options={}) unless bucket_name raise ArgumentError.new('bucket_name is required') end unless object_name raise ArgumentError.new('object_name is required') end if version_id = options.delete('versionId') query = {'versionId' => version_id} end headers = {} headers['If-Modified-Since'] = Fog::Time.at(options['If-Modified-Since'].to_i).to_date_header if options['If-Modified-Since'] headers['If-Unmodified-Since'] = Fog::Time.at(options['If-Unmodified-Since'].to_i).to_date_header if options['If-Modified-Since'] headers.merge!(options) request({ :expects => 200, :headers => headers, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'HEAD', :path => CGI.escape(object_name), :query => query }) end
Initiate a multipart upload to an S3 bucket
bucket_name<~String> - Name of bucket to create object in
object_name<~String> - Name of object to create
options<~Hash>:
'Cache-Control'<~String> - Caching behaviour
'Content-Disposition'<~String> - Presentational information for the object
'Content-Encoding'<~String> - Encoding of object data
'Content-MD5'<~String> - Base64 encoded 128-bit MD5 digest of message (defaults to Base64 encoded MD5 of object.read)
'Content-Type'<~String> - Standard MIME type describing contents (defaults to MIME::Types.of.first)
'x-amz-acl'<~String> - Permissions, must be in ['private', 'public-read', 'public-read-write', 'authenticated-read']
“x-amz-meta-#{name}” - Headers to be returned with object, note total size of request without body must be less than 8 KB.
response<~Excon::Response>:
body<~Hash>:
'Bucket'<~String> - Bucket where upload was initiated
'Key'<~String> - Object key where the upload was initiated
'UploadId'<~String> - Id for initiated multipart upload
docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadInitiate.html
# File lib/fog/aws/requests/storage/initiate_multipart_upload.rb, line 32 def initiate_multipart_upload(bucket_name, object_name, options = {}) request({ :expects => 200, :headers => options, :host => "#{bucket_name}.#{@host}", :method => 'POST', :parser => Fog::Parsers::Storage::AWS::InitiateMultipartUpload.new, :path => CGI.escape(object_name), :query => {'uploads' => nil} }) end
List multipart uploads for a bucket
bucket_name<~String> - Name of bucket to list multipart uploads for
upload_id<~String> - upload id to list objects for
options<~Hash> - config arguments for list. Defaults to {}.
'key-marker'<~String> - limits parts to only those that appear lexicographically after this key.
'max-uploads'<~Integer> - limits number of uploads returned
'upload-id-marker'<~String> - limits uploads to only those that appear lexicographically after this upload id.
response<~Excon::Response>:
body<~Hash>:
'Bucket'<~string> - Bucket where the multipart upload was initiated
'IsTruncated'<~Boolean> - Whether or not the listing is truncated
'KeyMarker'<~String> - first key in list, only upload ids after this lexographically will appear
'MaxUploads'<~Integer> - Maximum results to return
'NextKeyMarker'<~String> - last key in list, for further pagination
'NextUploadIdMarker'<~String> - last key in list, for further pagination
'Upload'<~Hash>:
'Initiated'<~Time> - Time when upload was initiated
'Initiator'<~Hash>:
'DisplayName'<~String> - Display name of upload initiator
'ID'<~String> - Id of upload initiator
'Key'<~String> - Key where multipart upload was initiated
'Owner'<~Hash>:
'DisplayName'<~String> - Display name of upload owner
'ID'<~String> - Id of upload owner
'StorageClass'<~String> - Storage class of object
'UploadId'<~String> - upload id of upload containing part
'UploadIdMarker'<String> - first key in list, only upload ids after this lexographically will appear
docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadListMPUpload.html
# File lib/fog/aws/requests/storage/list_multipart_uploads.rb, line 45 def list_multipart_uploads(bucket_name, options = {}) request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::Storage::AWS::ListMultipartUploads.new, :query => options.merge!({'uploads' => nil}) }) end
List parts for a multipart upload
bucket_name<~String> - Name of bucket to list parts for
object_name<~String> - Name of object to list parts for
upload_id<~String> - upload id to list objects for
options<~Hash> - config arguments for list. Defaults to {}.
'max-parts'<~Integer> - limits number of parts returned
'part-number-marker'<~String> - limits parts to only those that appear lexicographically after this part number.
response<~Excon::Response>:
body<~Hash>:
'Bucket'<~string> - Bucket where the multipart upload was initiated
'Initiator'<~Hash>:
'DisplayName'<~String> - Display name of upload initiator
'ID'<~String> - Id of upload initiator
'IsTruncated'<~Boolean> - Whether or not the listing is truncated
'Key'<~String> - Key where multipart upload was initiated
'MaxParts'<~String> - maximum number of replies alllowed in response
'NextPartNumberMarker'<~String> - last item in list, for further pagination
'Part'<~Array>:
'ETag'<~String> - ETag of part
'LastModified'<~Timestamp> - Last modified for part
'PartNumber'<~String> - Part number for part
'Size'<~Integer> - Size of part
'PartNumberMarker'<~String> - Part number after which listing begins
'StorageClass'<~String> - Storage class of object
'UploadId'<~String> - upload id of upload containing part
docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadListParts.html
# File lib/fog/aws/requests/storage/list_parts.rb, line 42 def list_parts(bucket_name, object_name, upload_id, options = {}) options['uploadId'] = upload_id request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::Storage::AWS::ListParts.new, :path => CGI.escape(object_name), :query => options.merge!({'uploadId' => upload_id}) }) end
Create an S3 bucket
bucket_name<~String> - name of bucket to create
options<~Hash> - config arguments for bucket. Defaults to {}.
'LocationConstraint'<~Symbol> - sets the location for the bucket
'x-amz-acl'<~String> - Permissions, must be in ['private', 'public-read', 'public-read-write', 'authenticated-read']
response<~Excon::Response>:
status<~Integer> - 200
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUT.html
# File lib/fog/aws/requests/storage/put_bucket.rb, line 21 def put_bucket(bucket_name, options = {}) if location_constraint = options.delete('LocationConstraint') data = <<-DATA <CreateBucketConfiguration> <LocationConstraint>#{location_constraint}</LocationConstraint> </CreateBucketConfiguration> DATA else data = nil end request({ :expects => 200, :body => data, :headers => options, :idempotent => true, :host => "#{bucket_name}.#{@host}", :method => 'PUT' }) end
Change access control list for an S3 bucket
bucket_name<~String> - name of bucket to modify
acl<~Hash>:
Owner<~Hash>:
ID<~String>: id of owner
DisplayName<~String>: display name of owner
AccessControlList<~Array>:
Grantee<~Hash>:
* 'DisplayName'<~String> - Display name of grantee * 'ID'<~String> - Id of grantee
or
* 'EmailAddress'<~String> - Email address of grantee
or
* 'URI'<~String> - URI of group to grant access for
Permission<~String> - Permission, in [FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP]
acl<~String> - Permissions, must be in ['private', 'public-read', 'public-read-write', 'authenticated-read']
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUTacl.html
# File lib/fog/aws/requests/storage/put_bucket_acl.rb, line 30 def put_bucket_acl(bucket_name, acl) data = "" headers = {} if acl.is_a?(Hash) data = Fog::Storage::AWS.hash_to_acl(acl) else if !['private', 'public-read', 'public-read-write', 'authenticated-read'].include?(acl) raise Excon::Errors::BadRequest.new('invalid x-amz-acl') end headers['x-amz-acl'] = acl end headers['Content-MD5'] = Base64.encode64(Digest::MD5.digest(data)).strip headers['Content-Type'] = 'application/json' headers['Date'] = Fog::Time.now.to_date_header request({ :body => data, :expects => 200, :headers => headers, :host => "#{bucket_name}.#{@host}", :method => 'PUT', :query => {'acl' => nil} }) end
Change lifecycle configuration for an S3 bucket
bucket_name<~String> - name of bucket to set lifecycle configuration for
lifecycle<~Hash>:
'Rules'<~Array> - object expire rules
* 'ID'<~String> - Unique identifier for the rule * 'Prefix'<~String> - Prefix identifying one or more objects to which the rule applies * 'Enabled'<~Boolean> - if rule is currently being applied * 'Days'<~Integer> - lifetime, in days, of the objects that are subject to the rule
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUTlifecycle.html
# File lib/fog/aws/requests/storage/put_bucket_lifecycle.rb, line 19 def put_bucket_lifecycle(bucket_name, lifecycle) builder = Nokogiri::XML::Builder.new do LifecycleConfiguration { lifecycle['Rules'].each do |rule| Rule { ID rule['ID'] Prefix rule['Prefix'] Status rule['Enabled'] ? 'Enabled' : 'Disabled' Expiration { Days rule['Days'] } } end } end body = builder.to_xml request({ :body => body, :expects => 200, :headers => {'Content-MD5' => Base64.encode64(Digest::MD5.digest(body)).chomp!, 'Content-Type' => 'application/xml'}, :host => "#{bucket_name}.#{@host}", :method => 'PUT', :query => {'lifecycle' => nil} }) end
Change logging status for an S3 bucket
bucket_name<~String> - name of bucket to modify
logging_status<~Hash>:
Owner<~Hash>:
ID<~String>: id of owner
DisplayName<~String>: display name of owner
AccessControlList<~Array>:
Grantee<~Hash>:
* 'DisplayName'<~String> - Display name of grantee * 'ID'<~String> - Id of grantee
or
* 'EmailAddress'<~String> - Email address of grantee
or
* 'URI'<~String> - URI of group to grant access for
Permission<~String> - Permission, in [FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP]
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUTlogging.html
# File lib/fog/aws/requests/storage/put_bucket_logging.rb, line 27 def put_bucket_logging(bucket_name, logging_status) if logging_status['LoggingEnabled'].empty? data = <<-DATA <BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01" /> DATA else data = <<-DATA <BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01"> <LoggingEnabled> <TargetBucket>#{logging_status['LoggingEnabled']['TargetBucket']}</TargetBucket> <TargetPrefix>#{logging_status['LoggingEnabled']['TargetBucket']}</TargetPrefix> <TargetGrants> DATA acl['AccessControlList'].each do |grant| data << " <Grant>" type = case grant['Grantee'].keys.sort when ['DisplayName', 'ID'] 'CanonicalUser' when ['EmailAddress'] 'AmazonCustomerByEmail' when ['URI'] 'Group' end data << " <Grantee xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:type=\"#{type}\">" for key, value in grant['Grantee'] data << " <#{key}>#{value}</#{key}>" end data << " </Grantee>" data << " <Permission>#{grant['Permission']}</Permission>" data << " </Grant>" end data << <<-DATA </TargetGrants> </LoggingEnabled> </BucketLoggingStatus> DATA end request({ :body => data, :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :method => 'PUT', :query => {'logging' => nil} }) end
Change bucket policy for an S3 bucket
bucket_name<~String> - name of bucket to modify
policy<~Hash> - policy document
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUTpolicy.html
# File lib/fog/aws/requests/storage/put_bucket_policy.rb, line 15 def put_bucket_policy(bucket_name, policy) request({ :body => Fog::JSON.encode(policy), :expects => 204, :headers => {}, :host => "#{bucket_name}.#{@host}", :method => 'PUT', :query => {'policy' => nil} }) end
Change versioning status for an S3 bucket
bucket_name<~String> - name of bucket to modify
status<~String> - Status to change to in ['Enabled', 'Suspended']
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUTVersioningStatus.html
# File lib/fog/aws/requests/storage/put_bucket_versioning.rb, line 15 def put_bucket_versioning(bucket_name, status) data = <<-DATA <VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Status>#{status}</Status> </VersioningConfiguration> DATA request({ :body => data, :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :method => 'PUT', :query => {'versioning' => nil} }) end
Change website configuration for an S3 bucket
bucket_name<~String> - name of bucket to modify
suffix<~String> - suffix to append to requests for the bucket
options<~Hash>
key<~String> - key to use for 4XX class errors
docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUTwebsite.html
# File lib/fog/aws/requests/storage/put_bucket_website.rb, line 17 def put_bucket_website(bucket_name, suffix, options = {}) data = <<-DATA <WebsiteConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <IndexDocument> <Suffix>#{suffix}</Suffix> </IndexDocument> DATA if options[:key] data << <<-DATA <ErrorDocument> <Key>#{options[:key]}</Key> </ErrorDocument> DATA end data << '</WebsiteConfiguration>' request({ :body => data, :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :method => 'PUT', :query => {'website' => nil} }) end
Create an object in an S3 bucket
bucket_name<~String> - Name of bucket to create object in
object_name<~String> - Name of object to create
options<~Hash>:
'Cache-Control'<~String> - Caching behaviour
'Content-Disposition'<~String> - Presentational information for the object
'Content-Encoding'<~String> - Encoding of object data
'Content-Length'<~String> - Size of object in bytes (defaults to object.read.length)
'Content-MD5'<~String> - Base64 encoded 128-bit MD5 digest of message
'Content-Type'<~String> - Standard MIME type describing contents (defaults to MIME::Types.of.first)
'Expires'<~String> - Cache expiry
'x-amz-acl'<~String> - Permissions, must be in ['private', 'public-read', 'public-read-write', 'authenticated-read']
'x-amz-storage-class'<~String> - Default is 'STANDARD', set to 'REDUCED_REDUNDANCY' for non-critical, reproducable data
“x-amz-meta-#{name}” - Headers to be returned with object, note total size of request without body must be less than 8 KB.
response<~Excon::Response>:
headers<~Hash>:
'ETag'<~String> - etag of new object
docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectPUT.html
# File lib/fog/aws/requests/storage/put_object.rb, line 32 def put_object(bucket_name, object_name, data, options = {}) data = Fog::Storage.parse_data(data) headers = data[:headers].merge!(options) request({ :body => data[:body], :expects => 200, :headers => headers, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'PUT', :path => CGI.escape(object_name) }) end
Change access control list for an S3 object
bucket_name<~String> - name of bucket to modify
object_name<~String> - name of object to get access control list for
acl<~Hash>:
Owner<~Hash>:
ID<~String>: id of owner
DisplayName<~String>: display name of owner
AccessControlList<~Array>:
Grantee<~Hash>:
* 'DisplayName'<~String> - Display name of grantee * 'ID'<~String> - Id of grantee
or
* 'EmailAddress'<~String> - Email address of grantee
or
* 'URI'<~String> - URI of group to grant access for
Permission<~String> - Permission, in [FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP]
acl<~String> - Permissions, must be in ['private', 'public-read', 'public-read-write', 'authenticated-read']
options<~Hash>:
'versionId'<~String> - specify a particular version to retrieve
docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectPUTacl.html
# File lib/fog/aws/requests/storage/put_object_acl.rb, line 33 def put_object_acl(bucket_name, object_name, acl, options = {}) query = {'acl' => nil} if version_id = options.delete('versionId') query['versionId'] = version_id end data = "" headers = {} if acl.is_a?(Hash) data = Fog::Storage::AWS.hash_to_acl(acl) else if !['private', 'public-read', 'public-read-write', 'authenticated-read'].include?(acl) raise Excon::Errors::BadRequest.new('invalid x-amz-acl') end headers['x-amz-acl'] = acl end headers['Content-MD5'] = Base64.encode64(Digest::MD5.digest(data)).strip headers['Content-Type'] = 'application/json' headers['Date'] = Fog::Time.now.to_date_header request({ :body => data, :expects => 200, :headers => headers, :host => "#{bucket_name}.#{@host}", :method => 'PUT', :path => CGI.escape(object_name), :query => query }) end
Change who pays for requests to an S3 bucket
bucket_name<~String> - name of bucket to modify
payer<~String> - valid values are BucketOwner or Requester
docs.amazonwebservices.com/AmazonS3/latest/API/RESTrequestPaymentPUT.html
# File lib/fog/aws/requests/storage/put_request_payment.rb, line 15 def put_request_payment(bucket_name, payer) data = <<-DATA <RequestPaymentConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Payer>#{payer}</Payer> </RequestPaymentConfiguration> DATA request({ :body => data, :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :method => 'PUT', :query => {'requestPayment' => nil} }) end
# File lib/fog/aws/storage.rb, line 294 def reload @connection.reset end
# File lib/fog/aws/storage.rb, line 298 def signature(params) string_to_sign = <<-DATA #{params[:method].to_s.upcase} #{params[:headers]['Content-MD5']} #{params[:headers]['Content-Type']} #{params[:headers]['Date']} DATA amz_headers, canonical_amz_headers = {}, '' for key, value in params[:headers] if key[0..5] == 'x-amz-' amz_headers[key] = value end end amz_headers = amz_headers.sort {|x, y| x[0] <=> y[0]} for key, value in amz_headers canonical_amz_headers << "#{key}:#{value}\n" end string_to_sign << canonical_amz_headers subdomain = params[:host].split(".#{@host}").first unless subdomain =~ /^(?:[a-z]|\d(?!\d{0,2}(?:\.\d{1,3}){3}$))(?:[a-z0-9]|\.(?![\.\-])|\-(?![\.])){1,61}[a-z0-9]$/ Fog::Logger.warning("fog: the specified s3 bucket name(#{subdomain}) is not a valid dns name, which will negatively impact performance. For details see: http://docs.amazonwebservices.com/AmazonS3/latest/dev/BucketRestrictions.html") params[:host] = params[:host].split("#{subdomain}.")[-1] if params[:path] params[:path] = "#{subdomain}/#{params[:path]}" else params[:path] = subdomain end subdomain = nil end canonical_resource = @path.dup unless subdomain.nil? || subdomain == @host canonical_resource << "#{Fog::AWS.escape(subdomain).downcase}/" end canonical_resource << params[:path].to_s canonical_resource << '?' for key in (params[:query] || {}).keys.sort if %w{ acl lifecycle location logging notification partNumber policy requestPayment response-cache-control response-content-disposition response-content-encoding response-content-language response-content-type response-expires torrent uploadId uploads versionId versioning versions website }.include?(key) canonical_resource << "#{key}#{"=#{params[:query][key]}" unless params[:query][key].nil?}&" end end canonical_resource.chop! string_to_sign << canonical_resource signed_string = @hmac.sign(string_to_sign) Base64.encode64(signed_string).chomp! end
Sync clock against S3 to avoid skew errors
# File lib/fog/aws/requests/storage/sync_clock.rb, line 8 def sync_clock response = begin get_service rescue Excon::Errors::HTTPStatusError => error error.response end Fog::Time.now = Time.parse(response.headers['Date']) end
Upload a part for a multipart upload
bucket_name<~String> - Name of bucket to add part to
object_name<~String> - Name of object to add part to
upload_id<~String> - Id of upload to add part to
part_number<~String> - Index of part in upload
data<~File||String> - Content for part
options<~Hash>:
'Content-MD5'<~String> - Base64 encoded 128-bit MD5 digest of message
response<~Excon::Response>:
headers<~Hash>:
'ETag'<~String> - etag of new object (will be needed to complete upload)
docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadUploadPart.html
# File lib/fog/aws/requests/storage/upload_part.rb, line 25 def upload_part(bucket_name, object_name, upload_id, part_number, data, options = {}) data = Fog::Storage.parse_data(data) headers = options headers['Content-Length'] = data[:headers]['Content-Length'] request({ :body => data[:body], :expects => 200, :idempotent => true, :headers => headers, :host => "#{bucket_name}.#{@host}", :method => 'PUT', :path => CGI.escape(object_name), :query => {'uploadId' => upload_id, 'partNumber' => part_number} }) end
# File lib/fog/aws/storage.rb, line 382 def request(params, &block) refresh_credentials_if_expired params[:headers]['Date'] = Fog::Time.now.to_date_header params[:headers]['x-amz-security-token'] = @aws_session_token if @aws_session_token params[:headers]['Authorization'] = "AWS #{@aws_access_key_id}:#{signature(params)}" # FIXME: ToHashParser should make this not needed original_params = params.dup begin response = @connection.request(params, &block) rescue Excon::Errors::TemporaryRedirect => error uri = URI.parse(error.response.headers['Location']) Fog::Logger.warning("fog: followed redirect to #{uri.host}, connecting to the matching region will be more performant") response = Fog::Connection.new("#{@scheme}://#{uri.host}:#{@port}", false, @connection_options).request(original_params, &block) end response end
# File lib/fog/aws/storage.rb, line 373 def setup_credentials(options) @aws_access_key_id = options[:aws_access_key_id] @aws_secret_access_key = options[:aws_secret_access_key] @aws_session_token = options[:aws_session_token] @aws_credentials_expire_at = options[:aws_credentials_expire_at] @hmac = Fog::HMAC.new('sha1', @aws_secret_access_key) end