AWS SDK for Ruby
Developer Guide

Hello World Tutorial for the AWS SDK for Ruby

This tutorial shows you how to use the AWS SDK for Ruby to create a command line program that performs some common Amazon S3 operations.

Using the AWS SDK for Ruby in Your Program

Add a require statement to the top of your Ruby source file so you can use the classes and methods provided by the AWS SDK for Ruby.

require 'aws-sdk'

Creating an Amazon S3 Resource

Create an Aws::S3::Resource object in the appropriate region. The following example creates an Amazon S3 resource object in the us-west-2 region. Note that the region is not important because Amazon S3 resources are not specific to a region.

s3 = 'us-west-2')

Creating a Bucket

To store anything on Amazon S3, you need a bucket to put it in.

Create an Aws::S3::Bucket object. The following example creates the bucket my_bucket with the name my-bucket.

my_bucket = s3.bucket('my-bucket') my_bucket.create

Adding a File to the Bucket

Use the #upload_file method to add a file to the bucket. The following example adds the file named my_file to the bucket named my-bucket.

name = File.basename 'my_file' obj = s3.bucket('my-bucket').object(name) obj.upload_file('my_file')

Listing the Contents of a Bucket

To list the contents of a bucket, use the Aws::S3::Bucket:Objects method. The following example lists up to 50 bucket items for the bucket my-bucket.

my_bucket.objects.limit(50).each do |obj| puts " #{obj.key} => #{obj.etag}" end

Complete Program

The following is the entire hello-s3.rb program.

require 'aws-sdk' NO_SUCH_BUCKET = "The bucket '%s' does not exist!" USAGE = <<DOC Usage: hello-s3 bucket_name [operation] [file_name] Where: bucket_name (required) is the name of the bucket operation is the operation to perform on the bucket: create - creates a new bucket upload - uploads a file to the bucket list - (default) lists up to 50 bucket items file_name is the name of the file to upload, required when operation is 'upload' DOC # Set the name of the bucket on which the operations are performed # This argument is required bucket_name = nil if ARGV.length > 0 bucket_name = ARGV[0] else puts USAGE exit 1 end # The operation to perform on the bucket operation = 'list' # default operation = ARGV[1] if (ARGV.length > 1) # The file name to use with 'upload' file = nil file = ARGV[2] if (ARGV.length > 2) # Get an Amazon S3 resource s3 = 'us-west-2') # Get the bucket by name bucket = s3.bucket(bucket_name) case operation when 'create' # Create a bucket if it doesn't already exist if bucket.exists? puts "The bucket '%s' already exists!" % bucket_name else bucket.create puts "Created new S3 bucket: %s" % bucket_name end when 'upload' if file == nil puts "You must enter the name of the file to upload to S3!" exit end if bucket.exists? name = File.basename file # Check if file is already in the bucket if bucket.object(name).exists? puts "#{name} already exists in the bucket" else obj = s3.bucket(bucket_name).object(name) obj.upload_file(file) puts "Uploaded '%s' to S3!" % name end else NO_SUCH_BUCKET % bucket_name end when 'list' if bucket.exists? # Enumerate the bucket contents and object etags puts "Contents of '%s':" % bucket_name puts ' Name => GUID' bucket.objects.limit(50).each do |obj| puts " #{obj.key} => #{obj.etag}" end else NO_SUCH_BUCKET % bucket_name end else puts "Unknown operation: '%s'!" % operation puts USAGE end

Running the Program

To list the contents of a bucket, use either of the following commands, where bucket-name is the name of the bucket to list. You don't have to include list because it's the default operation.

ruby hello-s3.rb bucket-name list ruby hello-s3.rb bucket-name

To create a bucket, use the following command, where bucket-name is the name of the bucket you want to create.

ruby hello-s3.rb bucket-name create

If Amazon S3 already has a bucket named bucket-name, the service issues an error message and does not create another copy.

After you create your bucket, you can upload an object to the bucket. The following command adds your_file.txt to the bucket.

ruby hello-s3.rb bucket-name upload your_file.txt

Next Steps

Now that you've completed your first AWS SDK for Ruby application, here are some suggestions to extend the code you just wrote:

  • Use the buckets collection from the Aws::S3::Resource class to get a list of buckets.

  • Use #get method from the Bucket class to download an object from the bucket.

  • Use the code in Adding a File to the Bucket to confirm the item exists in the bucket, and then update that bucket item.