https://github.com/qoobaa/s3

Library for accessing S3 objects and buckets, supports EU and US buckets
https://github.com/qoobaa/s3

Last synced: 3 months ago
JSON representation

Library for accessing S3 objects and buckets, supports EU and US buckets

• Host: GitHub
• URL: https://github.com/qoobaa/s3
• Owner: qoobaa
• License: mit
• Created: 2009-06-25T13:14:24.000Z (over 15 years ago)
• Default Branch: master
• Last Pushed: 2022-10-05T23:22:34.000Z (over 2 years ago)
• Last Synced: 2024-10-12T18:53:40.826Z (4 months ago)
• Language: Ruby
• Homepage:
• Size: 337 KB
• Stars: 258
• Watchers: 8
• Forks: 112
• Open Issues: 22
• Metadata Files:
  • Readme: README.rdoc
  • License: LICENSE.txt
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

• awesome-ruby-toolbox - S3 - S3 library provides access to Amazon's Simple Storage Service. It supports both: European and US buckets through REST API. (Provision, Deploy & Host / Amazon Web Services)

README

        
= S3

{}[https://travis-ci.org/qoobaa/s3]

S3 library provides access to {Amazon's Simple Storage Service}[http://aws.amazon.com/s3/].

It supports *all* S3 regions through the {REST API}[http://docs.amazonwebservices.com/AmazonS3/latest/API/APIRest.html].

== Installation

    gem install s3

== Usage

=== Initialize the service

    require "s3"

    service = S3::Service.new(:access_key_id => "...",

                              :secret_access_key => "...")

    #=> #

=== List buckets

    service.buckets

    #=> [#,

    #    #]

=== Find bucket

    first_bucket = service.buckets.find("first-bucket")

    #=> #

or

    first_bucket = service.bucket("first-bucket")

    #=> #

service.bucket("first-bucket") does not check whether a bucket with the name "first-bucket" exists, but it also does not issue any HTTP requests. Thus, the second example is much faster than buckets.find. You can use first_bucket.exists? to check whether the bucket exists after calling service.bucket.

=== Create bucket

    new_bucket = service.buckets.build("newbucketname")

    new_bucket.save(:location => :eu)

Remember that bucket name for EU can't include "_" (underscore).

Please refer to: http://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html for more information about bucket name restrictions.

=== List objects in a bucket

    first_bucket.objects

    #=> [#,

    #    #]

=== Find object in a bucket

    object = first_bucket.objects.find("lenna.png")

    #=> #

=== Access object metadata (cached from find)

    object.content_type

    #=> "image/png"

=== Access object content (downloads the object)

    object.content

    #=> "\x89PNG\r\n\x1A\n\x00\x00\x00\rIHDR\x00..."

=== Delete an object

    object.destroy

    #=> true

=== Create an object

    new_object = bucket.objects.build("bender.png")

    #=> #

    new_object.content = open("bender.png")

    new_object.acl = :public_read

    new_object.save

    #=> true

Please note that new objects are created with "private" ACL by

default.

=== Request access to a private object

Returns a temporary url to the object that expires on the timestamp given. Defaults to one hour expire time.

    new_object.temporary_url(Time.now + 1800)

=== Fetch ACL

   object = bucket.objects.find('lenna.png')

   object.request_acl # or bucket.request_acl

This will return hash with all users/groups and theirs permissions

=== Modify ACL

   object = bucket.objects.find("lenna.png")

   object.copy(:key => "lenna.png", :bucket => bucket, :acl => :public_read)

=== Upload file direct to amazon

==== Rails 3

Check the {example in this gist}[https://gist.github.com/3169039], which describes how to use

a simple form element to upload files directly to S3.

== See also

* rubygems[http://rubygems.org/gems/s3]

* repository[http://github.com/qoobaa/s3]

* {issue tracker}[http://github.com/qoobaa/s3/issues]

* documentation[http://rubydoc.info/github/qoobaa/s3/master/frames]

== Copyright

Copyright (c) 2009 Jakub Kuźma, Mirosław Boruta. See LICENSE[http://github.com/qoobaa/s3/raw/master/LICENSE] for details.