AWS SDK for Ruby V2

This repository contains the code for the V2 AWS SDK for Ruby. Code is organized into three gems. Installing aws-sdk --pre will install the full v2 Ruby SDK.

• aws-sdk
  • aws-sdk-resources
  • aws-sdk-core

For version 1.0 of the Ruby SDK, see aws/aws-sdk-ruby.

Links of Interest

• Documentation
• Release Notes
• Upgrading Notes
• Issues
• Forums
• License

Installation

You can install the AWS SDK Core from rubygems:

gem install aws-sdk-core

If you are using Bundler, we recommend that you express a major version dependency (this library uses semantic versioning):

gem 'aws-sdk-core', '~> 2.0'

Note: AWS SDK Core requires Ruby 1.9.3+.

Configuration

To use the Ruby SDK, you must configure a region and your AWS account access credentials.

Region

You can export a default region to ENV:

export AWS_REGION='us-west-2'

Or you can configure a region in code:

# default region
Aws.config[:region] = 'us-west-2'

# per-service :region
s3 = Aws::S3::Client.new(region:'us-east-1')

Credentials

Please take care to never commit credentials to source control. We strongly recommended loading credentials from an external source. By default, the Ruby SDK will attempt to load credentials from the following sources:

• ENV['AWS_ACCESS_KEY_ID'] and ENV['AWS_SECRET_ACCESS_KEY']
• The shared credentials ini file at HOME/.aws/credentials
• From an instance profile when running on EC2

Alternatively, you can specify your credentials directly using one of the following credential classes:

• Aws::Credentials
• Aws::SharedCredentials
• Aws::InstanceProfileCredentials

# default credentials
Aws.config[:credentials] = Aws::SharedCredentials.new(profile_name:'myprofile')

# per-service :credentials
s3 = Aws::S3::Client.new(credentials: Aws::SharedCredentials.new(profile_name:'myprofile')

Basic Usage

To make a request, you need to construct a service client.

s3 = Aws::S3::Client.new

Each client provides one method per API operation. Refer to the API documentation for a complete list of available methods.

# get a list of buckets in Amazon S3
resp = s3.list_buckets
puts resp.buckets.map(&:name)

API methods accept a request params as a hash, and return structured responses.

resp = s3.list_objects(bucket: 'aws-sdk-core', 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. A simple paging interface is provided that works with every AWS request.

# yields once per response, even works with non-paged requests
s3.list_objects(bucket:'aws-sdk').each do |resp|
  puts resp.contents.map(&:key)
end

If you prefer to control paging yourself, all returned responses have the same helper methods:

# 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?

Waiters

Waiters are a utility to poll for a particular state. Waiters are named and are invoked from a client object via #wait_until.

begin
  ec2.wait_until(:instance_running, instance_ids:['i-12345678'])
  puts "instance running"
rescue Aws::Waiters::Errors::WaiterFailed => error
  puts "failed waiting for instance running: #{error.message}"
end

Waiters are configurable and have sensible defaults. You can configure:

• maximum number of attempts before failing
• time between polling requests
• callbacks
  • before each attempt
  • before waiting/sleeping
  • callbacks can trigger success or failure

See the documentation for each service client class to get a list of supported waiters and additional examples.

Resource Interfaces

Resource interfaces are currently experimental. While aws-sdk-core is very stable, aws-sdk-resources should be considered unstable.

A handful of services provide resource-oriented interfaces that abstract the client APIs.

s3 = Aws::S3::Resource.new

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

# enumerate every object in a bucket
bucket.objects.each do |obj|
  puts "#{object.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

Currently there are Resource-oriented interfaces for:

• Aws::S3
• Aws::IAM
• Aws::EC2 - partial
• Aws::SQS
• Aws::SNS
• Aws::Glacier

Documentation is currently fairly sparse on the resource classes, expect a lot of improvement on these over the coming weeks.

Interactive Console

AWS SDK Core ships with a REPL that acts as an interactive console. You can access the REPL by running aws.rb from the command line.

$ aws.rb
Aws> ec2.describe_instances.reservations.first.instances.first
<struct
 instance_id="i-1234567",
 image_id="ami-7654321",
 state=<struct  code=16, name="running">,
 ...>

Call #service_classes to get a list of available service helpers and the class they construct.

Aws> service_clients
{:autoscaling=>Aws::AutoScaling::Client,
 :cloudformation=>Aws::CloudFormation::Client,
 :cloudfront=>Aws::CloudFront::Client,
 :cloudsearch=>Aws::CloudSearch::Client,
 ...
 :swf=>Aws::SWF::Client}

Versioning

This project uses semantic versioning. When the project leaves the developer preview state, we will continue by versioning from 2.0. Until then, all versions will be suffixed by a release candidate version.

Supported Services

Service Name	Service Class	API Versions
Amazon CloudFront	CloudFront	2014-05-31
Amazon CloudSearch	CloudSearch	2013-01-01
Amazon CloudSearch Domain	CloudSearchDomain	2013-01-01
Amazon CloudWatch	CloudWatch	2010-08-01
Amazon CloudWatch Logs	CloudWatchLogs	2014-03-28
Amazon Cognito Identity	CognitoIdentity	2014-06-30
Amazon Cognito Sync	CognitoSync	2014-06-30
Amazon DynamoDB	DynamoDB	2012-08-10
Amazon Elastic Compute Cloud	EC2	2014-09-01
Amazon Elastic MapReduce	EMR	2009-03-31
Amazon Elastic Transcoder	ElasticTranscoder	2012-09-25
Amazon ElastiCache	ElastiCache	2014-09-30
Amazon Glacier	Glacier	2012-06-01
Amazon Kinesis	Kinesis	2013-12-02
Amazon Redshift	Redshift	2012-12-01
Amazon Relational Database Service	RDS	2014-09-01
Amazon Route 53	Route53	2013-04-01
Amazon Route 53 Domains	Route53Domains	2014-05-15
Amazon Simple Email Service	SES	2010-12-01
Amazon Simple Notification Service	SNS	2010-03-31
Amazon Simple Queue Service	SQS	2012-11-05
Amazon Simple Storage Service	S3	2006-03-01
Amazon Simple Workflow Service	SWF	2012-01-25
Amazon SimpleDB	SimpleDB	2009-04-15
Auto Scaling	AutoScaling	2011-01-01
AWS CloudFormation	CloudFormation	2010-05-15
AWS CloudTrail	CloudTrail	2013-11-01
AWS Data Pipeline	DataPipeline	2012-10-29
AWS Direct Connect	DirectConnect	2012-10-25
AWS Elastic Beanstalk	ElasticBeanstalk	2010-12-01
AWS Identity and Access Management	IAM	2010-05-08
AWS Import/Export	ImportExport	2010-06-01
AWS OpsWorks	OpsWorks	2013-02-18
AWS Security Token Service	STS	2011-06-15
AWS Storage Gateway	StorageGateway	2013-06-30
AWS Support	Support	2013-04-15
Elastic Load Balancing	ElasticLoadBalancing	2012-06-01

License

This library is distributed under the apache license, version 2.0

copyright 2013. amazon web services, inc. all rights reserved.

licensed under the apache license, version 2.0 (the "license");
you may not use this file except in compliance with the license.
you may obtain a copy of the license at

    http://www.apache.org/licenses/license-2.0

unless required by applicable law or agreed to in writing, software
distributed under the license is distributed on an "as is" basis,
without warranties or conditions of any kind, either express or implied.
see the license for the specific language governing permissions and
limitations under the license.