Class: AWS::S3::S3Object

S3Objects represent the data you store on S3. They have a key (their name) and a value (their data). All objects belong to a bucket.

You can store an object on S3 by specifying a key, its data and the name of the bucket you want to put it in:

  S3Object.store('me.jpg', open('headshot.jpg'), 'photos')

The content type of the object will be inferred by its extension. If the appropriate content type can not be inferred, S3 defaults to binary/octet-stream.

If you want to override this, you can explicitly indicate what content type the object should have with the :content_type option:

  file = 'black-flowers.m4a'
  S3Object.store(
    file,
    open(file),
    'jukebox',
    :content_type => 'audio/mp4a-latm'
  )

You can read more about storing files on S3 in the documentation for S3Object.store.

If you just want to fetch an object you‘ve stored on S3, you just specify its name and its bucket:

  picture = S3Object.find 'headshot.jpg', 'photos'

N.B. The actual data for the file is not downloaded in both the example where the file appeared in the bucket and when fetched directly. You get the data for the file like this:

  picture.value

You can fetch just the object‘s data directly:

  S3Object.value 'headshot.jpg', 'photos'

Or stream it by passing a block to stream:

  open('song.mp3', 'w') do |file|
    S3Object.stream('song.mp3', 'jukebox') do |chunk|
      file.write chunk
    end
  end

The data of the file, once download, is cached, so subsequent calls to value won‘t redownload the file unless you tell the object to reload its value:

  # Redownloads the file's data
  song.value(:reload)

Other functionality includes:

  # Check if an object exists?
  S3Object.exists? 'headshot.jpg', 'photos'

  # Copying an object
  S3Object.copy 'headshot.jpg', 'headshot2.jpg', 'photos'

  # Renaming an object
  S3Object.rename 'headshot.jpg', 'portrait.jpg', 'photos'

  # Deleting an object
  S3Object.delete 'headshot.jpg', 'photos'

More about objects and their metadata

You can find out the content type of your object with the content_type method:

  song.content_type
  # => "audio/mpeg"

You can change the content type as well if you like:

  song.content_type = 'application/pdf'
  song.store

(Keep in mind that due to limitiations in S3‘s exposed API, the only way to change things like the content_type is to PUT the object onto S3 again. In the case of large files, this will result in fully re-uploading the file.)

A bevie of information about an object can be had using the about method:

  pp song.about
  {"last-modified"    => "Sat, 28 Oct 2006 21:29:26 GMT",
   "content-type"     => "binary/octet-stream",
   "etag"             => "\"dc629038ffc674bee6f62eb64ff3a\"",
   "date"             => "Sat, 28 Oct 2006 21:30:41 GMT",
   "x-amz-request-id" => "B7BC68F55495B1C8",
   "server"           => "AmazonS3",
   "content-length"   => "3418766"}

You can get and set metadata for an object:

  song.metadata
  # => {}
  song.metadata[:album] = "A River Ain't Too Much To Love"
  # => "A River Ain't Too Much To Love"
  song.metadata[:released] = 2005
  pp song.metadata
  {"x-amz-meta-released" => 2005,
    "x-amz-meta-album"   => "A River Ain't Too Much To Love"}
  song.store

That metadata will be saved in S3 and is hence forth available from that object:

  song = S3Object.find('black-flowers.mp3', 'jukebox')
  pp song.metadata
  {"x-amz-meta-released" => "2005",
    "x-amz-meta-album"   => "A River Ain't Too Much To Love"}
  song.metadata[:released]
  # => "2005"
  song.metadata[:released] = 2006
  pp song.metadata
  {"x-amz-meta-released" => 2006,
   "x-amz-meta-album"    => "A River Ain't Too Much To Love"}

External Aliases

store	->	create
store	->	save

Public Class methods

about(key, bucket = nil, options = {})

Fetch information about the object with key from bucket. Information includes content type, content length, last modified time, and others.

If the specified key does not exist, NoSuchKey is raised.

More about objects and their metadata

Methods

Included Modules

External Aliases

Public Class methods

Conditional GET options

Other options

Public Instance methods