AWS SDK for Ruby - Version 3

Links of Interest

using a credentials object

ec2 = Aws::EC2::Client.new(region: ‘us-west-2’, credentials: credentials)

using a profile name

ec2 = Aws::EC2::Client.new(profile: ‘my_profile’)


Please take care to **never commit credentials to source control**. We strongly
recommended loading credentials from an external source.

```ruby
require 'aws-sdk'
require 'json'

creds = JSON.load(File.read('secrets.json'))
Aws.config[:credentials] = Aws::Credentials.new(
  creds['AccessKeyId'],
  creds['SecretAccessKey']
)

For more information on how to configure credentials, see the developer guide for configuring AWS SDK for Ruby.

API Clients

Construct a service client to make API calls. Each client provides a 1-to-1 mapping of methods to API operations. Refer to the API documentation for a complete list of available methods.

# list buckets in Amazon S3
s3 = Aws::S3::Client.new
resp = s3.list_buckets
resp.buckets.map(&:name)
#=> ["bucket-1", "bucket-2", ...]

API methods accept a hash of additional request parameters and return structured response data.

# list the first two objects in a bucket
resp = s3.list_objects(bucket: 'aws-sdk', max_keys: 2)
resp.contents.each do |object|
  puts "#{object.key} => #{object.etag}"
end

Paging Responses

Many AWS operations limit the number of results returned with each response. To make it easy to get the next page of results, every AWS response object is enumerable:

# yields one response object per API call made, this will enumerate
# EVERY object in the named bucket
s3.list_objects(bucket:'aws-sdk').each do |response|
  puts response.contents.map(&:key)
end

If you prefer to control paging yourself, response objects have helper methods that control paging:

# make a request that returns a truncated response
resp = s3.list_objects(bucket: 'aws-sdk')

resp.last_page? #=> false
resp.next_page? #=> true
resp = resp.next_page # send a request for the next response page
resp = resp.next_page until resp.last_page?

Resource Interfaces

Resource interfaces are object oriented classes that represent actual resources in AWS. Resource interfaces built on top of API clients and provide additional functionality.

Only a few services implement a resource interface. They are defined by hand in JSON and have limitations. Please use the Client API instead.

s3 = Aws::S3::Resource.new

# reference an existing bucket by name
bucket = s3.bucket('aws-sdk')

# enumerate every object in a bucket
bucket.objects.each do |obj|
  puts "#{obj.key} => #{obj.etag}"
end

# batch operations, delete objects in batches of 1k
bucket.objects(prefix: '/tmp-files/').delete

# single object operations
obj = bucket.object('hello')
obj.put(body:'Hello World!')
obj.etag
obj.delete

REPL - AWS Interactive Console

The aws-sdk gem ships with a REPL that provides a simple way to test the Ruby SDK. You can access the REPL by running aws-v3.rb from the command line.

$ aws-v3.rb
[1] pry(Aws)> ec2.describe_instances.reservations.first.instances.first
[Aws::EC2::Client 200 0.216615 0 retries] describe_instances()
<struct
 instance_id="i-1234567",
 image_id="ami-7654321",
 state=<struct  code=16, name="running">,
 ...>

You can enable HTTP wire logging by setting the verbose flag:

$ aws-v3.rb -v

In the REPL, every service class has a helper that returns a new client object. Simply downcase the service module name for the helper:

s3 => #<Aws::S3::Client>
ec2 => #<Aws::EC2::Client>
etc

Opening Issues

If you encounter a bug or have a feature request, we would like to hear about it. Search the existing issues and try to make sure your problem doesn’t already exist before opening a new issue.

The GitHub issues are intended for bug reports and feature requests. For help and questions with using aws-sdk-ruby please make use of the resources listed in the Getting Help section.

Versioning

This project uses semantic versioning. You can safely express a dependency on a major version and expect all minor and patch versions to be backwards compatible.

A CHANGELOG can be found at each gem’s root path (i.e. aws-sdk-s3 can be found at gems/aws-sdk-s3/CHANGELOG.md). The CHANGELOG is also accessible via the RubyGems.org page under “LINKS” section.

AWS SDK for Ruby