AWS SDK for Ruby
Developer Guide

Creating and Using an Amazon S3 Bucket

This example demonstrates how to use the AWS SDK for Ruby to:

  1. Display a list of buckets in Amazon S3.

  2. Create a bucket.

  3. Upload an object (a file) to the bucket.

  4. Copy files to the bucket.

  5. Delete files from the bucket.

For the complete code for this example, see Complete Example.

Prerequisites

To set up and run this example, you must first:

  1. Install the AWS SDK for Ruby. For more information, see Installing the AWS SDK for Ruby.

  2. Set the AWS access credentials that the AWS SDK for Ruby will use to verify your access to AWS services and resources. For more information, see Configuring the AWS SDK for Ruby.

Be sure the AWS credentials map to an AWS Identity and Access Management (IAM) entity with access to the AWS actions and resources described in this example.

This example assumes you have set the credentials in the AWS credentials profile file and named the file david.

Configure the SDK

For this example, add require statements so that you can use the classes and methods provided by the AWS SDK for Ruby for Amazon S3 and work with JSON-formatted data. Then create an Aws::S3::Client object in the AWS Region where you want to create the bucket and the specified AWS profile. This code creates the Aws::S3::Client object in the us-east-1 region. Additional variables are also declared for the two buckets used in this example.

require 'aws-sdk-s3' # v2: require 'aws-sdk' require 'json' profile_name = 'david' region = "us-east-1" bucket = 'doc-sample-bucket' my_bucket = 'david-cloud' # S3 # Configure SDK s3 = Aws::S3::Client.new(profile: profile_name, region: region)

Get a List of Buckets

Call the list_buckets method. This returns an instance of the Aws::S3::Types::ListBucketsOutput class, which represents the list of buckets. Then use the buckets attribute of the ListBucketsOutput class to access the buckets' properties, such as name for each bucket's name.

resp = s3.list_buckets resp.buckets.each do |bucket| puts bucket.name end

Create a Bucket

Call the create_bucket method, specifying the bucket's name.

Note

Bucket names must be unique across Amazon S3—not just unique to your AWS account.

s3.create_bucket(bucket: bucket)

Upload an Object (a File) to a Bucket

Call the put_object method, specifying settings such as the bucket's name and the name of the file to create. For the file's contents, you can specify an instance of a Ruby File class or, in this example, a string representing the file's data.

To confirm whether the file was uploaded successfully, call the list_objects_v2 method. This returns an instance of the Aws::S3::Types::ListObjectsV2Output class, which represents the bucket's objects. Then use the contents method of the ListObjectsV2Output class to access the objects' properties, such as key for each object's name.

s3.put_object(bucket: bucket, key: "file1", body: "My first s3 object") # Check the file exists resp = s3.list_objects_v2(bucket: bucket) resp.contents.each do |obj| puts obj.key end

Copy Files between Buckets

Call the copy_object method, specifying the name of the target bucket to receive the object (bucket), the names of the source bucket and object to copy over (copy_source), and the name of the new object that is copied over into the target bucket (key).

In this example, the name of the bucket containing the objects to copy over is #{my_bucket}, which is the bucket named david-cloud. After the copy operation, test_file in the david-cloud bucket is renamed file2 in the doc-sample-bucket bucket, and test_file1 in the david-cloud bucket is renamed file3 in the doc-sample-bucket bucket.

s3.copy_object(bucket: bucket, copy_source: "#{my_bucket}/test_file", key: 'file2') s3.copy_object(bucket: bucket, copy_source: "#{my_bucket}/test_file1", key: 'file3')

Delete Files from a Bucket

Call the delete_objects method. For the delete argument, use an instance of the Aws::S3::Types::Delete type to represent the objects to delete. In this example, objects represents two files to delete.

To confirm whether the files were deleted successfully, call the list_objects_v2 method as before. This time, when you use the contents method of the class, the deleted file names (represented here by key) should not be displayed.

s3.delete_objects( bucket: 'doc-sample-bucket', delete: { objects: [ { key: 'file2' }, { key: 'file3' } ] } ) # Verify objects now have been deleted resp = s3.list_objects_v2(bucket: bucket) resp.contents.each do |obj| puts obj.key end

Complete Example

Here is the complete code for this example.

require 'aws-sdk-s3' # v2: require 'aws-sdk' require 'json' profile_name = 'david' region = "us-east-1" bucket = 'doc-sample-bucket' my_bucket = 'david-cloud' # S3 # Configure SDK s3 = Aws::S3::Client.new(profile: profile_name, region: region) # Display a List of Amazon S3 Buckets resp = s3.list_buckets resp.buckets.each do |bucket| puts bucket.name end # Create a S3 bucket from S3::client s3.create_bucket(bucket: bucket) # Upload a file to s3 bucket, directly putting string data s3.put_object(bucket: bucket, key: "file1", body: "My first s3 object") # Check the file exists resp = s3.list_objects_v2(bucket: bucket) resp.contents.each do |obj| puts obj.key end # Copy files from bucket to bucket s3.copy_object(bucket: bucket, copy_source: "#{my_bucket}/test_file", key: 'file2') s3.copy_object(bucket: bucket, copy_source: "#{my_bucket}/test_file1", key: 'file3') # Delete multiple objects in a single HTTP request s3.delete_objects( bucket: 'doc-sample-bucket', delete: { objects: [ { key: 'file2' }, { key: 'file3' } ] } ) # Verify objects now have been deleted resp = s3.list_objects_v2(bucket: bucket) resp.contents.each do |obj| puts obj.key end

Alternative Approaches

The following example creates a bucket named my-bucket in the us-west-2 region. This example uses an instance of the Aws::S3::Resource class instead of the Aws::S3::Client class.

require 'aws-sdk-s3' # v2: require 'aws-sdk' s3 = Aws::S3::Resource.new(region: 'us-west-2') s3.create_bucket(bucket: 'my-bucket')