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 = Aws::S3::Resource.new(region: '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 = Aws::S3::Resource.new(region: '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: