advertisement
AWS SDK for Ruby
Developer Guide
AWS SDK for Ruby: Developer Guide
Copyright © 2017 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
AWS SDK for Ruby Developer Guide
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by
Amazon.
AWS SDK for Ruby Developer Guide
Table of Contents
iii
AWS SDK for Ruby Developer Guide
iv
AWS SDK for Ruby Developer Guide
v
AWS SDK for Ruby Developer Guide
About This Guide
AWS SDK for Ruby Developer Guide
Welcome to the AWS SDK for Ruby.
The AWS SDK for Ruby helps take the complexity out of coding by providing Ruby classes for almost all
AWS services, including Amazon Simple Storage Service, Amazon Elastic Compute Cloud, and Amazon
DynamoDB. For a complete list of services supported by the AWS SDK for Ruby, see the Supported
Services section of the AWS SDK for Ruby Readme file.
About This Guide
The AWS SDK for Ruby Developer Guide provides information about how to install, set up, and use the
AWS SDK for Ruby to create Ruby applications that use AWS services.
This guide contains the following sections:
Getting Started with the AWS SDK for Ruby (p. 3)
Describes how to set up and use the AWS SDK for Ruby.
Steps you through creating an application using the AWS SDK for Ruby.
Programming with the AWS SDK for Ruby (p. 16)
Provides general information about developing software with the AWS SDK for Ruby.
AWS SDK for Ruby Code Examples (p. 22)
Provides code examples that developers can use to program AWS services with the AWS SDK for
Ruby.
Describes the history of this document.
Additional Documentation and Resources
For more resources for AWS SDK for Ruby developers, see the following:
1
AWS SDK for Ruby Developer Guide
Deploying to the AWS Cloud
• AWS SDK for Ruby API Reference
• Developer blog
• Developer forums (you must have an AWS account to access the forums)
• Gitter channel
• @awsforruby on Twitter
• On GitHub:
• Releases (includes source, gems, and documentation)
• Source
• Change log
• Migration Guide
• Issues
• Feature requests
• Upgrading notes
Deploying to the AWS Cloud
You can use AWS services such as AWS Elastic Beanstalk, AWS OpsWorks, and AWS CodeDeploy to deploy your application to the AWS Cloud. For deploying Ruby applications with Elastic Beanstalk, see
Working with Ruby in the Elastic Beanstalk Developer Guide. For deploying a Ruby on Rails application with AWS OpsWorks, see Deploying Ruby on Rails Applications to AWS OpsWorks . For an overview of
AWS deployment services, see Overview of Deployment Options on AWS .
2
AWS SDK for Ruby Developer Guide
QuickStart Guide to Using the AWS SDK for Ruby
Getting Started with the AWS SDK for Ruby
If you're new to the AWS SDK for Ruby, you should start here. This section contains information about installing, setting up, and using the SDK to create a Ruby application to access Amazon S3.
Topics
•
QuickStart Guide to Using the AWS SDK for Ruby (p. 3)
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
•
Using the AWS SDK for Ruby REPL (p. 8)
•
Using the SDK with Ruby on Rails (p. 8)
•
Migrating from version 1 to version 2 of the AWS SDK for Ruby (p. 9)
QuickStart Guide to Using the AWS SDK for Ruby
This section shows you how to use the AWS SDK for Ruby to create a simple Ruby application that lists your Amazon S3 buckets.
• If you haven't installed the SDK, see
Installing the AWS SDK for Ruby (p. 4) .
• If you haven't configured the SDK, see
Configuring the AWS SDK for Ruby (p. 5)
.
Write the Code
The following example lists the names of up to 50 of your buckets. Copy the code and save it as buckets.rb
. Note that although the Resource object is created in the us-west-2
region, Amazon S3 returns buckets to which you have access, regardless of the region.
require 'aws-sdk' s3 = Aws::S3::Resource.new(region: 'us-west-2') s3.buckets.limit(50).each do |b|
puts "#{b.name}" end
3
AWS SDK for Ruby Developer Guide
Run the Code
Run the Code
Enter the following command to execute buckets.rb
.
ruby buckets.rb
Note for Windows users
When you use SSL certificates on Windows and run your Ruby code, you will see an error similar to the following.
C:\Ruby>ruby buckets.rb
C:/Ruby200-x64/lib/ruby/2.0.0/net/http.rb:921:in `connect': SSL_connect returned=1
errno=0 state=SSLv3 read server certificate B: certificate verify failed
(Seahorse::Client::NetworkingError)
from C:/Ruby200-x64/lib/ruby/2.0.0/net/http.rb:921:in `block in connect'
from C:/Ruby200-x64/lib/ruby/2.0.0/timeout.rb:66:in `timeout'
from C:/Ruby200-x64/lib/ruby/2.0.0/net/http.rb:921:in `connect'
from C:/Ruby200-x64/lib/ruby/2.0.0/net/http.rb:862:in `do_start'
from C:/Ruby200-x64/lib/ruby/2.0.0/net/http.rb:857:in `start'
...
To fix this issue, add the following line to your Ruby source file, somewhere before your first AWS call.
Aws.use_bundled_cert!
Installing the AWS SDK for Ruby
This section includes prerequisites and installation instructions.
Prerequisites
Before you install the AWS SDK for Ruby, you need an AWS account and Ruby version 1.9 or later.
If you don't have an AWS account, use the following procedure to create one.
To sign up for AWS
1. Open http://aws.amazon.com/ and choose Create an AWS Account.
2. Follow the online instructions.
Installing the AWS SDK for Ruby
If your project uses Bundler , add the following line to your
Gemfile
to add the AWS SDK for Ruby to your project.
gem 'aws-sdk'
If you don't use Bundler, the easiest way to install the SDK is to use RubyGems . To install the latest version of the SDK, use the following command.
4
AWS SDK for Ruby Developer Guide
Configuring the AWS SDK for Ruby gem install aws-sdk
If the previous command fails on your Unix-based system, use sudo
to install the SDK, as shown in the following command.
sudo gem install aws-sdk
Configuring the AWS SDK for Ruby
Learn how to configure the AWS SDK for Ruby. To use the SDK, you must set either AWS credentials or create an AWS STS access token, and set the AWS Region you want to use.
Setting AWS Credentials
Before you can use the AWS SDK for Ruby to make a call to an AWS service, you must set the AWS access credentials that the SDK will use to verify your access to AWS services and resources.
The AWS SDK for Ruby searches for credentials in the following order:
1.
Setting Credentials in a Client Object (p. 6)
2.
Setting Credentials Using Aws.config (p. 6)
3.
Setting Credentials Using Environment Variables (p. 5)
4.
Setting Shared Credentials (p. 5)
5.
Setting Credentials Using IAM (p. 6)
The following sections describe the various ways you can set credentials, starting with the most flexible approach. For more information about AWS credentials and recommended approaches for credential management, see AWS Security Credentials in the Amazon Web Services General Reference.
Setting Shared Credentials
Set shared credentials in the AWS credentials profile file on your local system.
On Unix-based systems, such as Linux or OS X, this file is located in the following location.
~/.aws/credentials
On Windows, this file is located in the following location.
%HOMEPATH%\.aws\credentials
This file must have the following format, where default
is the name of the default configuration profile given to these credentials, your_access_key_id
is the value of your access key, and your_secret_access_key
is the value of your secret access key.
[default] aws_access_key_id = your_access_key_id aws_secret_access_key = your_secret_access_key
Setting Credentials Using Environment Variables
Set the
AWS_ACCESS_KEY_ID
and
AWS_SECRET_ACCESS_KEY
environment variables.
5
AWS SDK for Ruby Developer Guide
Creating an AWS STS Access Token
Use the export
command to set these variables on Unix-based systems, such as Linux or OS X. The following example sets the value of your access key to your_access_key_id
and the value of your secret access key to your_secret_access_key
.
export AWS_ACCESS_KEY_ID=your_access_key_id export AWS_SECRET_ACCESS_KEY=your_secret_access_key
To set these variables on Windows, use the set
command, as shown in the following example.
set AWS_ACCESS_KEY_ID=your_access_key_id set AWS_SECRET_ACCESS_KEY=your_secret_access_key
Setting Credentials Using Aws.config
Set the credentials in your code by updating the values in the
Aws.config
hash.
The following example sets the value of your access key to your_access_key_id
and the value of your secret access key to your_secret_access_key
. Any client or resource you create subsequently will use these credentials.
Aws.config.update({
credentials: Aws::Credentials.new('your_access_key_id', 'your_secret_access_key')
})
Setting Credentials in a Client Object
Set the credentials in your code by specifying them when you create an AWS client.
The following example creates an Amazon S3 client using the access key your_access_key_id
and the secret access key your_secret_access_key
.
s3 = Aws::S3::Client.new(
access_key_id: 'your_access_key_id',
secret_access_key: 'your_secret_access_key'
)
Setting Credentials Using IAM
For an Amazon Elastic Compute Cloud instance, create an IAM role, and then give your Amazon EC2 instance access to that role. For more information, see IAM Roles for Amazon EC2 in the Amazon EC2
User Guide for Linux Instances or IAM Roles for Amazon EC2 in the Amazon EC2 User Guide for Windows
Instances.
Creating an AWS STS Access Token
Use the Aws::AssumeRoleCredentials method to create an AWS STS access token.
The following example uses an access token to create an Amazon S3 client object, where linked::account::arn
is the Amazon Resource Name (ARN) of the role to assume and session-name
is an identifier for the assumed role session.
role_credentials = Aws::AssumeRoleCredentials.new(
client: Aws::STS::Client.new,
role_arn: "linked::account::arn",
role_session_name: "session-name"
6
AWS SDK for Ruby Developer Guide
Setting a Region
) s3 = Aws::S3::Client.new(credentials: role_credentials)
Setting a Region
You need to set a region when using most AWS services. You can set the AWS Region in ways similar to setting your AWS credentials. The AWS SDK for Ruby searches for a region in the following order:
•
Setting the Region in a Client or Resource Object (p. 7)
•
Setting the Region Using Aws.config (p. 7)
•
Setting the Region Using Environment Variables (p. 7)
The rest of this section describes how to set a region, starting with the most flexible approach.
Setting the Region Using Environment Variables
Set the region by setting the
AWS_REGION
environment variable.
Use the export
command to set this variable on Unix-based systems, such as Linux or OS X. The following example sets the region to us-west-2
.
export AWS_REGION=us-west-2
To set this variable on Windows, use the set
command. The following example sets the region to uswest-2
.
set AWS_REGION=us-west-2
Setting the Region Using Aws.config
Set the region by adding a region
value to the
Aws.config
hash. The following example updates the
Aws.config
hash to use the us-west-1
region.
Aws.config.update({region: 'us-west-1'})
Any clients or resources you subsequently create are bound to this region.
Setting the Region in a Client or Resource Object
Set the region when you create an AWS client or resource. The following example creates an Amazon S3 resource object in the us-west-1
region.
s3 = Aws::S3::Resource.new(region: 'us-west-1')
Setting a Nonstandard Endpoint
If you need to use a nonstandard endpoint in the region you've selected, add an endpoint
entry to
Aws.config
or set the endpoint:
when creating a service client or resource object. The following example creates an Amazon S3 resource object in the other_endpoint
endpoint.
s3 = Aws::S3::Resource.new(endpoint: other_endpoint)
7
AWS SDK for Ruby Developer Guide
Using the AWS SDK for Ruby REPL
Using the AWS SDK for Ruby REPL
Developers can use aws.rb
, the interactive command-line read-evaluate-print loop (REPL) console tool that is part of the aws-sdk-core
gem.
Although aws.rb
does work with the Interactive Ruby Shell ( irb
), we recommend that you install pry
, which provides a more powerful REPL environment.
Use the following command to install pry
.
gem install pry
To use aws.rb
, you invoke it in a console window using one of the following two command lines.
aws.rb
aws.rb -v
The second command line invokes the REPL with extensive HTTP wire logging, which provides information about the communication between the AWS SDK for Ruby and AWS. Use this command line with caution, however, because it also adds overhead that can make your code run slower.
The REPL defines a helper object for every service class. Downcase the service module name to get the name of the helper object. For example, the names of the Amazon S3 and Amazon EC2 helper objects are s3
and ec2
, respectively.
Using the SDK with Ruby on Rails
Ruby on Rails provides a web development framework for Ruby that makes it easy to create websites with Ruby.
The AWS SDK for Ruby provides a gem to enable easy integration with Rails. You can use AWS Elastic
Beanstalk, AWS OpsWorks, or AWS CodeDeploy to deploy and run your Rails applications in the AWS
Cloud.
Integrating the AWS SDK for Ruby with Rails
AWS provides a gemfile, aws-sdk-rails
, that supports integration of the AWS SDK for Ruby with Rails.
You can view its GitHub repository at https://github.com/aws/aws-sdk-rails .
Add the gem to your application's Gemfile, as shown in the following example.
gem 'aws-sdk-rails'
The gem includes the AWS SDK for Ruby, so adding the gem is all you need to do to add AWS support to your Rails application.
Amazon SES Support for ActionMailer
When you use the aws-sdk-rails
gem in a config/environments
file of your Rails project (for example, config/environments/production.rb
), you can use Amazon Simple Email Service (Amazon SES) as the back end for the
ActionMailer
class, as shown in the following example.
8
AWS SDK for Ruby Developer Guide
Logging config.action_mailer.delivery_method = :aws_sdk
For more information about
ActionMailer
, see the Action Mailer Basics on the Ruby on Rails website.
Logging
The aws-sdk-rails
gem configures the SDK logger to use
Rails.logger
.
The gem also configures the SDK log messages to use the
:info
log level. You can change the log level by setting
:log_level
in the Aws.config hash. The following example sets the log level to
:debug
.
Aws.config.update({log_level: :debug})
Migrating from version 1 to version 2 of the AWS
SDK for Ruby
The purpose of this topic is to help you migrate from version 1 of the AWS SDK for Ruby to version 2.
Side-by-Side Usage
It is not necessary to replace the version 1 AWS SDK for Ruby with version 2. You can use them together in the same application. See this blog post for more information.
A quick example follows: require 'aws-sdk-v1' # version 1 require 'aws-sdk' # version 2 s3 = AWS::S3::Client.new # version 1 s3 = Aws::S3::Client.new # version 2
You do not need to rewrite existing working version 1 code to start using the version 2 SDK. A valid migration strategy is to only write new code against the version 2 SDK.
General Differences
Version 2 differs from version 1 in a number of important ways.
• Different root namespace,
Aws
vs
AWS
. This enables side-by-side usage.
•
Aws.config
is now a vanilla Ruby hash, instead of a method.
• Strict constructor options - When constructing a client or resource object in the version 1 SDK, unknown constructor options are ignored. In version 2, unknown constructor options trigger an
ArgumentError
. For example:
# version 1
AWS::S3::Client.new(http_reed_timeout: 10)
# oops, typo'd option is ignored
# version 2
Aws::S3::Client.new(http_reed_timeout: 10)
9
AWS SDK for Ruby Developer Guide
Client Differences
# => raises ArgumentError
Client Differences
Between version 1 and version 2, the client classes have the fewest external differences. Many service clients will have compatible interfaces after client construction. Some important differences:
•
Aws::S3::Client
- The version 1 Amazon S3 client class was hand-coded. Version 2 is generated from a service model. Method names an inputs are very different in version 2.
•
Aws::EC2::Client
- Version 2 uses plural names for output lists, version 1 uses the suffix
_set
. For example:
# version 1 resp = AWS::EC2::Client.new.describe_security_groups
resp.security_group_set
#=> [...]
# version 2 resp = Aws::EC2::Client.new.describe_security_groups
resp.security_groups
#=> [...]
•
Aws::SWF::Client
- Version two uses structured responses, where version 1 uses vanilla Ruby hashes.
• Service class renames - Version 2 uses a different name for multiple services:
•
AWS::SimpleWorkflow
has become
Aws::SWF
•
AWS::ELB
has become
Aws::ElasticLoadBalancing
•
AWS::SimpleEmailService
has become
Aws::SES
• Client configuration options - Some of the version 1 configuration options have been renamed in version 2. Others have been removed or replaced. Here are the primary changes:
•
:use_ssl
has been removed. Version 2 uses SSL everywhere. To disable SSL you must configure an
:endpoint
that uses http://
.
•
:ssl_ca_file
=>
:ssl_ca_bundle
•
:ssl_ca_path
=>
:ssl_ca_directory
• Added
:ssl_ca_store
.
•
:endpoint
must now be a fully qualified HTTP or HTTPS uri instead of a hostname.
• Removed
:*_port
options for each service, replaced by
:endpoint
.
•
:user_agent_prefix
is now
:user_agent_suffix
Resource Differences
There are significant differences between the resource interfaces in version 1 and version 2. Version 1 was entirely hand-coded, where as version 2 resource interfaces are generated from a model. Version 2 resource interfaces are significantly more consistent. Some of the systemic differences include:
• Separate resource class - In version 2, the service name is a module and not a class. In this module is the resource interface:
# version 1 s3 = AWS::S3.new
# version 2 s3 = Aws::S3::Resource.new
10
AWS SDK for Ruby Developer Guide
Resource Differences
• Referencing resources - The version 2 SDK separates collections and individual resource getters into two different methods:
# version 1 s3.buckets['bucket-name'].objects['key'].delete
# version 2 s3.bucket('bucket-name').object('key').delete
• Batch operations - In version 1, all batch operations were hand-coded utilities. In version 2, many batch operations are auto-generated batching operations over the API.
Version 2 batching interfaces are very different from version 1.
11
AWS SDK for Ruby Developer Guide
Using the AWS SDK for Ruby in Your Program
Hello World Tutorial
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 as 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'll 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
.
12
AWS SDK for Ruby Developer Guide
Listing the Contents of a 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)
13
AWS SDK for Ruby Developer Guide
Running the Program
# 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 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. We don't have to include list
because it is the default operation.
ruby hello-s3.rb bucket-name list
14
AWS SDK for Ruby Developer Guide
Next Steps 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 (p. 12)
to confirm the item exists in the bucket, and then update that bucket item.
15
AWS SDK for Ruby Developer Guide
Debugging Tip: Getting Wire
Trace Information from a Client
Programming with the AWS SDK for
Ruby
This section provides information about developing software with the AWS SDK for Ruby, including how to use some of the SDK's advanced features.
Topics
•
Debugging Tip: Getting Wire Trace Information from a Client (p. 16)
•
Stubbing Client Responses and Errors (p. 17)
•
•
•
Specifying a Client Timeout Duration (p. 21)
Debugging Tip: Getting Wire Trace Information from a Client
You can get wire trace information from an AWS client when you create it by setting the http_wire_trace
option. This information helps differentiate client changes, service issues, and user errors. The following example creates an Amazon S3 client with wire tracing enabled.
s3 = Aws::S3::Client.new(http_wire_trace: true)
Given the following code and the argument bucket_name
, the output displays a message that says whether a bucket with that name exists.
require 'aws-sdk' s3 = Aws::S3::Resource.new(client: Aws::S3::Client.new(http_wire_trace: true)) if s3.bucket(ARGV[0]).exists?
puts "Bucket #{ARGV[0]} exists" else
16
AWS SDK for Ruby Developer Guide
Stubbing Client Responses and Errors
puts "Bucket #{ARGV[0]} does not exist" end
If the bucket exists, the output looks something like the following, where ACCESS_KEY is the value of your access key. (Returns were added to the
HEAD
line for readability.) opening connection to bucket_name.s3-us-west-1.amazonaws.com:443...
opened starting SSL for bucket_name.s3-us-west-1.amazonaws.com:443...
SSL established
<- "HEAD / HTTP/1.1\r\n
Content-Type: \r\n
Accept-Encoding: \r\n
User-Agent: aws-sdk-ruby2/2.2.7 ruby/2.1.7 x64-mingw32\r\n
X-Amz-Date: 20160121T191751Z\r\n
Host: bucket_name.s3-us-west-1.amazonaws.com\r\n
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\r
\n
Authorization: AWS4-HMAC-SHA256 Credential=ACCESS_KEY/20160121/us-west-1/s3/ aws4_request,
SignedHeaders=host;x-amz-content-sha256;x-amz-date,
Signature=2ca8301c5e829700940d3cc3bca2a3e8d79d177f2c046c34a1a285770db63820\r\n
Content-Length: 0\r\n
Accept: */*\r\n
\r\n"
-> "HTTP/1.1 301 Moved Permanently\r\n"
-> "x-amz-bucket-region: us-west-2\r\n"
-> "x-amz-request-id: F3C75F33EF0792C4\r\n"
-> "x-amz-id-2: N6BzRLx8b68NmF50g1IxLzT
+E4uWPuAIRe7Pl4XKl5STT4tfNO7gBsO8qrrAnG4CbVpU0iIRXmk=\r\n"
-> "Content-Type: application/xml\r\n"
-> "Transfer-Encoding: chunked\r\n"
-> "Date: Thu, 21 Jan 2016 19:17:54 GMT\r\n"
-> "Server: AmazonS3\r\n"
-> "\r\n"
Conn keep-alive
Bucket bucket_name exists
Stubbing Client Responses and Errors
Learn how to stub client responses and client errors in an AWS SDK for Ruby application.
Stubbing Client Responses
When you stub a response, the AWS SDK for Ruby disables network traffic and the client returns stubbed
(or fake) data. If you don't supply stubbed data, the client returns:
• Lists as empty arrays
• Maps as empty hashes
• Numeric values as zero
• Dates as now
The following example returns stubbed names for the list of Amazon S3 buckets.
require 'aws-sdk'
17
AWS SDK for Ruby Developer Guide
Stubbing Client Errors s3 = Aws::S3::Client.new(stub_responses: true) bucket_data = s3.stub_data(:list_buckets, :buckets => [{name:'aws-sdk'}, {name:'awssdk2'}]) s3.stub_responses(:list_buckets, bucket_data) bucket_names = s3.list_buckets.buckets.map(&:name)
# List each bucket by name bucket_names.each do |name|
puts name end
Running this code displays the following.
aws-sdk aws-sdk2
Note
After you supply any stubbed data, the default values no longer apply for any remaining instance attributes. This means that in the previous example, the remaining instance attribute, creation_date
, is not now
but nil
.
The AWS SDK for Ruby validates your stubbed data. If you pass in data of the wrong type, it raises an
ArgumentError
exception. For example, if instead of the previous assignment to bucket_data
, you used the following: bucket_data = s3.stub_data(:list_buckets, buckets:['aws-sdk', 'aws-sdk2'])
The AWS SDK for Ruby raises two
ArgumentError
exceptions.
expected params[:buckets][0] to be a hash expected params[:buckets][1] to be a hash
Stubbing Client Errors
You can also stub errors that the AWS SDK for Ruby raises for specific methods. The following example displays
Caught Timeout::Error error calling head_bucket on aws-sdk
.
require 'aws-sdk' s3 = Aws::S3::Client.new(stub_responses: true) s3.stub_responses(:head_bucket, Timeout::Error) begin
s3.head_bucket({bucket: 'aws-sdk'}) rescue Exception => ex
puts "Caught #{ex.class} error calling 'head_bucket' on 'aws-sdk'" end
Paging Response Data
Some AWS calls provide paged responses to limit the amount of data returned with each response. A page of data represents up to 1,000 items.
18
AWS SDK for Ruby Developer Guide
Paged Responses Are Enumerable
Paged Responses Are Enumerable
The simplest way to handle paged response data is to use the built-in enumerator in the response object, as shown in the following example.
s3 = Aws::S3::Client.new
s3.list_objects(bucket:'aws-sdk').each do |response|
puts response.contents.map(&:key) end
This yields one response object per API call made, and enumerates objects in the named bucket. The SDK retrieves additional pages of data to complete the request.
Handling Paged Responses Manually
To handle paging yourself, use the response's next_page?
method to verify there are more pages to retrieve, or use the last_page?
method to verify there are no more pages to retrieve.
If there are more pages, use the next_page
(notice there is no
?
) method to retrieve the next page of results, as shown in the following example.
s3 = Aws::S3::Client.new
# Get the first page of data response = s3.list_objects(bucket:'aws-sdk')
# Get additional pages while response.next_page? do
response = response.next_page
# Use the response data here...
end
Note
If you call the next_page
method and there are no more pages to retrieve, the SDK raises an
Aws::PageableResponse::LastPageError exception.
Paged Data Classes
Paged data in the AWS SDK for Ruby is handled by the Aws::PageableResponse class, which is included with Seahorse::Client::Response to provide access to paged data.
Using Waiters
Waiters are utility methods that poll for a particular state to occur on a client. Waiters can fail after a number of attempts at a polling interval defined for the service client. For an example of how a waiter is used, see
Creating a Simple Table with a Single Primary Key (p. 30) .
Invoking a Waiter
To invoke a waiter, call
#wait_until
on a service client. In the following example, a waiter waits until the instance i-12345678
is running before continuing.
ec2 = Aws::EC2::Client.new
19
AWS SDK for Ruby Developer Guide
Wait Failures 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
The first parameter is the waiter name, which is specific to the service client and indicates which operation is being waited for. The second parameter is a hash of parameters that are passed to the client method called by the waiter, which varies according to the waiter name.
For a list of operations that can be waited for and the client methods called for each operation, see the
#waiter_names
and
#wait_until
field documentation for the client you are using.
Wait Failures
Waiters can fail with any of the following exceptions:
Aws::Waiters::Errors::FailureStateError
A failure state was encountered while waiting.
Aws::Waiters::Errors::NoSuchWaiterError
The specified waiter name is not defined for the client being used.
Aws::Waiters::Errors::TooManyAttemptsError
The number of attempts exceeded the waiter's max_attempts
value.
Aws::Waiters::Errors::UnexpectedError
An unexpected error occurred while waiting.
Aws::Waiters::Errors::WaiterFailed
One of the wait states was exceeded or another failure occurred while waiting.
All of these errors—except
NoSuchWaiterError
—are based on
WaiterFailed
. To catch errors in a waiter, use
WaiterFailed
, as shown in the following example.
rescue Aws::Waiters::Errors::WaiterFailed => error
puts "failed waiting for instance running: #{error.message}" end
Configuring a Waiter
Each waiter has a default polling interval and a maximum number of attempts it will make before returning control to your program. To set these values, use the max_attempts
and delay:
parameters in your
#wait_until
call. The following example waits for up to 25 seconds, polling every 5 seconds.
# Poll for ~25 seconds client.wait_until(...) do |w|
w.max_attempts = 5
w.delay = 5 end
To disable wait failures, set the value of either of these parameters to nil
.
20
AWS SDK for Ruby Developer Guide
Extending a Waiter
Extending a Waiter
To modify the behavior of waiters, you can register callbacks that are triggered before each polling attempt and before waiting.
The following example implements an exponential backoff in a waiter by doubling the amount of time to wait on every attempt.
ec2 = Aws::EC2::Client.new
ec2.wait_until(:instance_running, instance_ids:['i-12345678']) do |w|
w.interval = 0 # disable normal sleep
w.before_wait do |n, resp|
sleep(n ** 2)
end end
The following example disables the maximum number of attempts, and instead waits for 1 hour (3600 seconds) before failing.
started_at = Time.now
client.wait_until(...) do |w|
# Disable max attempts
w.max_attempts = nil
# Poll for 1 hour, instead of a number of attempts
before_wait do |attempts, response|
throw :failure if Time.now - started_at > 3600
end end
Specifying a Client Timeout Duration
The following example creates an Amazon S3 client in the region us-west-2
, and specifies to wait 5 seconds between two retries on every client operation. By default, the SDK performs up to three retries, with 15 seconds between retries, for a total of up to four attempts. Therefore, an operation could take
60 seconds to time out, so the example could take 15 seconds to time out.
s3 = Aws::S3::Client.new(region: 'us-west-2', retry_limit: 2, http_open_timeout: 5)
21
AWS SDK for Ruby Developer Guide
Amazon CloudWatch Examples
AWS SDK for Ruby Code Examples
This section provides examples you can use to access AWS services by using the AWS SDK for Ruby.
Topics
•
Amazon CloudWatch Examples (p. 22)
•
Amazon DynamoDB Examples (p. 29)
•
•
AWS Elastic Beanstalk Examples (p. 49)
•
AWS Identity and Access Management Examples (p. 51)
•
•
Amazon Relational Database Service Examples (p. 64)
•
•
•
Amazon CloudWatch Examples
You can use the following examples to access Amazon CloudWatch (CloudWatch) by using the AWS SDK for Ruby. For more information about CloudWatch, see the CloudWatch Developer Guide .
Examples
Topics
•
Getting Information about All Alarms (p. 23)
•
•
Enabling and Disabling Alarm Actions (p. 24)
•
Getting Info about Custom Metrics (p. 25)
•
Sending Events to Amazon CloudWatch Events (p. 26)
22
AWS SDK for Ruby Developer Guide
Getting Information about All Alarms
Getting Information about All Alarms
The following example displays information about your CloudWatch alarms.
require 'aws-sdk' client = Aws::CloudWatch::Client.new(region: 'us-west-2')
# use client.describe_alarms({alarm_names: ['Name1', 'Name2']})
# to get information about alarms Name1 and Name2 resp = client.describe_alarms
resp.metric_alarms.each do |alarm|
puts 'Name: ' + alarm.alarm_name
puts 'State: ' + alarm.state_value
puts ' reason: ' + alarm.state_reason
puts 'Metric: ' + alarm.metric_name
puts 'Namespace: ' + alarm.namespace
puts 'Statistic: ' + alarm.statistic
puts 'Dimensions (' + alarm.dimensions.length.to_s + '):'
alarm.dimensions.each do |d|
puts ' Name: ' + d.name
puts ' Value: ' + d.value
end
puts 'Period: ' + alarm.period.to_s
puts 'Unit: ' + alarm.unit.to_s
puts 'Eval periods: ' + alarm.evaluation_periods.to_s
puts 'Threshold: ' + alarm.threshold.to_s
puts 'Comp operator: ' + alarm.comparison_operator
puts end
Creating an Alarm
The following example creates a CloudWatch alarm my-alarm that sends a message through the Amazon
SNS topic with the ARN
ARN
when the Amazon S3 bucket my-bucket has more than 50 items in a 24-hour period.
require 'aws-sdk'
# Placeholder for put_metric_alarm args args = {} args[:alarm_name] = 'my-alarm' args[:alarm_description] = 'Triggers alarm when S3 bucket my-bucket has more than 50 items' args[:alarm_actions] = 'ARN' args[:namespace] = 'AWS/S3' args[:metric_name] = 'NumberOfObjects' dim1 = {} dim1[:name] = 'BucketName' dim1[:value] = 'my-bucket' dim2 = {} dim2[:name] = 'StorageType' dim2[:value] = 'AllStorageTypes' dimensions = [] dimensions << dim1 dimensions << dim2
23
AWS SDK for Ruby Developer Guide
Enabling and Disabling Alarm Actions args[:dimensions] = dimensions args[:statistic] = 'Maximum'
# NumberOfObjects REQUIRES this value args[:period] = 86400
# NumberOfObjects REQUIRES this value args[:unit] = nil args[:evaluation_periods] = 1 args[:threshold] = 50 args[:comparison_operator] = 'GreaterThanThreshold' cw = Aws::CloudWatch::Client.new(region: 'us-west-2') cw.put_metric_alarm(args)
Enabling and Disabling Alarm Actions
An Amazon CloudWatch alarm watches a single metric over a time period you specify. The CloudWatch alarm performs one or more actions based on the value of the metric, relative to a given threshold over a number of time periods. For more information, see Creating Amazon CloudWatch Alarms .
In this example, you use the AWS SDK for Ruby with CloudWatch to:
1. Enable an action for a CloudWatch alarm by using Aws::CloudWatch::Client#put_metric_alarm .
2. Disable all actions for an alarm by using Aws::CloudWatch::Client#disable_alarm_actions .
The complete code for this example is available on GitHub.
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
You'll also need to replace arn:aws:sns:REGION-ID:ACCOUNT-ID:TOPIC-NAME with the ARN for a valid
Amazon SNS topic.
Example
require 'aws-sdk'
# Uncomment for Windows.
# Aws.use_bundled_cert!
cw = Aws::CloudWatch::Client.new(region: 'us-east-1')
# Enable an action for an Amazon CloudWatch alarm.
# If the alarm does not exist, create it.
# If the alarm exists, update its settings.
alarm_name = "TooManyObjectsInBucket" cw.put_metric_alarm({
24
AWS SDK for Ruby Developer Guide
Getting Info about Custom Metrics
alarm_name: alarm_name,
alarm_description: "Alarm whenever an average of more than one object exists in the
specified Amazon S3 bucket for more than one day.",
actions_enabled: true, # Run actions if the alarm's state changes.
metric_name: "NumberOfObjects",
alarm_actions: [ "arn:aws:sns:REGION-ID:ACCOUNT-ID:TOPIC-NAME" ], # Notify this Amazon
SNS topic only if the alarm's state changes to ALARM.
namespace: "AWS/S3",
statistic: "Average",
dimensions: [
{
name: "BucketName",
value: "my-bucket"
},
{
name: "StorageType",
value: "AllStorageTypes"
}
],
period: 86400, # Daily (24 hours * 60 minutes * 60 seconds = 86400 seconds).
unit: "Count",
evaluation_periods: 1, # More than one day.
threshold: 1, # One object.
comparison_operator: "GreaterThanThreshold" # More than one object.
})
# Disable all actions for the alarm.
cw.disable_alarm_actions({
alarm_names: [ alarm_name ]
})
Getting Info about Custom Metrics
A CloudWatch alarm watches a single metric over a time period you specify. The CloudWatch alarm performs one or more actions based on the value of the metric, relative to a given threshold over a number of time periods. For more information, see Creating Amazon CloudWatch Alarms .
In this example, you use the AWS SDK for Ruby with CloudWatch to:
1. Send custom metrics to CloudWatch by using Aws::CloudWatch::Client#put_metric_data .
2. Get information about custom metrics by using Aws::CloudWatch::Client#list_metrics-instance .
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
Example
require 'aws-sdk'
# Uncomment for Windows.
# Aws.use_bundled_cert!
cw = Aws::CloudWatch::Client.new(region: 'us-east-1')
25
AWS SDK for Ruby Developer Guide
Sending Events to Amazon CloudWatch Events
# Send custom metrics to Amazon CloudWatch.
# In this example, add metrics to the custom namespace "SITE/TRAFFIC":
# For the custom dimension named "SiteName", for the value named "example.com", add
# "UniqueVisitors" of 5885 and "UniqueVisits" of 8628.
# For the custom dimension named "PageURL", for the value named "my-page.html", add
# "PageViews" of 18057.
cw.put_metric_data({
namespace: "SITE/TRAFFIC",
metric_data: [
{
metric_name: "UniqueVisitors",
dimensions: [
{
name: "SiteName",
value: "example.com"
}
],
value: 5885.0,
unit: "Count"
},
{
metric_name: "UniqueVisits",
dimensions: [
{
name: "SiteName",
value: "example.com"
}
],
value: 8628.0,
unit: "Count"
},
{
metric_name: "PageViews",
dimensions: [
{
name: "PageURL",
value: "my-page.html"
}
],
value: 18057.0,
unit: "Count"
}
]
})
# Get information about custom metrics.
list_metrics_output = cw.list_metrics({
namespace: "SITE/TRAFFIC"
}) list_metrics_output.metrics.each do |metric|
puts metric.metric_name
metric.dimensions.each do |dimension|
puts "#{dimension.name} = #{dimension.value}"
end
puts "\n" end
Sending Events to Amazon CloudWatch Events
CloudWatch Events delivers a near real-time stream of system events that describe changes in AWS resources to AWS Lambda functions or other targets. To learn more, see What is Amazon CloudWatch
Events?
. In this example, you use the AWS SDK for Ruby with CloudWatch Events to:
26
AWS SDK for Ruby Developer Guide
Sending Events to Amazon CloudWatch Events
1. Create a rule in CloudWatch Events by using Aws::CloudWatchEvents::Client#put_rule .
2. Add a target to the rule by using Aws::CloudWatchEvents::Client#put_targets .
3. Send an event to CloudWatch Events so that it can be matched to the rule.
4. View the results in Amazon CloudWatch Logs and metrics by using Aws::CloudWatch::Client#get_metric_statistics and
Aws::CloudWatchLogs::Client#describe_log_streams .
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
You also need to:
• Replace the placeholder value assigned to lambda_function_arn with an actual Lambda function ARN.
1. Create a Lambda function, as described here .
2. Name the function LogEC2InstanceStateChange.
3. For a role, select Choose an Existing Role. For the existing role, select lambda_basic_execution.
4. After you create the function, copy the ARN and paste it into your code.
• Replace the placeholder value assigned to cwe_service_role_arn with an appropriate AWS IAM service role ARN.
1. In the IAM console, create a role and attach a policy that grants full access to CloudWatch Events.
2. Ensure that the role has a trust relationship to events.amazonaws.com. For an example policy and role, see the comments in the example code on GitHub .
3. After you create the role, attach the policy, and establish the trust relationship, copy the role ARN and paste it into your code.
• Replace the placeholder value assigned to instance_id with an actual Amazon EC2 instance ID.
Example
require 'aws-sdk'
# Uncomment for Windows.
# Aws.use_bundled_cert!
cwe = Aws::CloudWatchEvents::Client.new(region: 'us-east-1')
# Replace this value with the ARN of the AWS Lambda function you created earlier.
lambda_function_arn = "arn:aws:lambda:REGION-ID:ACCOUNT-
ID:function:LogEC2InstanceStateChange"
# Replace this value with the ARN of the AWS IAM service role you created earlier.
cwe_service_role_arn = "arn:aws:iam::ACCOUNT-ID:role/SERVICE-ROLE-NAME"
# Create a rule in Amazon CloudWatch Events.
rule_name = "my-ec2-rule"
# The rule will use this pattern to route the event to the target.
# This pattern is used whenever an Amazon EC2 instance begins running.
event_pattern = {
27
AWS SDK for Ruby Developer Guide
Sending Events to Amazon CloudWatch Events
"source" => [
"aws.ec2"
],
"detail-type" => [
"EC2 Instance State-change Notification"
],
"detail" => {
"state" => [
"running"
]
}
}.to_json
cwe.put_rule({
name: rule_name,
event_pattern: event_pattern,
state: "ENABLED",
role_arn: cwe_service_role_arn
})
# Add a target to the rule.
cwe.put_targets({
rule: rule_name,
targets: [
{
id: "my-rule-target",
arn: lambda_function_arn
}
]
})
# To test the rule, stop and then restart an existing Amazon EC2 instance.
# For example: ec2 = Aws::EC2::Client.new(region: 'us-east-1')
# Replace this with an actual instance ID.
instance_id = "i-INSTANCE-ID" puts "Attempting to stop the instance. This may take a few minutes..." ec2.stop_instances({
instance_ids: [ instance_id ]
})
# Make sure the instance is stopped before attempting to restart it.
ec2.wait_until(:instance_stopped, instance_ids: [ instance_id ]) puts "Attempt to restart the instance. This may take a few minutes..." ec2.start_instances({
instance_ids: [ instance_id ]
})
# Make sure the instance is running before continuing on.
ec2.wait_until(:instance_running, instance_ids: [ instance_id ])
# See if and when the rule was triggered.
cw = Aws::CloudWatch::Client.new(region: 'us-east-1') invocations = cw.get_metric_statistics({
namespace: "AWS/Events",
metric_name: "Invocations",
dimensions: [
{
name: "RuleName",
value: rule_name,
28
AWS SDK for Ruby Developer Guide
Amazon DynamoDB Examples
},
],
start_time: Time.now - 600, # Look back over the past 10 minutes to see if the rule was
triggered (10 minutes * 60 seconds = 600 seconds).
end_time: Time.now,
period: 60, # Look back every 60 seconds over those past 10 minutes to see how many times
the rule may have been triggered.
statistics: [ "Sum" ],
unit: "Count"
}) if invocations.datapoints.count > 0
puts "Rule invocations:"
invocations.datapoints.each do |datapoint|
puts " #{datapoint.sum} invocation(s) at #{datapoint.timestamp}"
end else
puts "No rule invocations." end
# View the latest related log in Amazon CloudWatch Logs.
cwl = Aws::CloudWatchLogs::Client.new(region: 'us-east-1') describe_log_streams_response = cwl.describe_log_streams({
log_group_name: "/aws/lambda/LogEC2InstanceStateChange",
order_by: "LastEventTime",
descending: true
}) get_log_events_response = cwl.get_log_events({
log_group_name: "/aws/lambda/LogEC2InstanceStateChange",
log_stream_name: describe_log_streams_response.log_streams[0].log_stream_name # Get the
latest log stream only.
}) puts "\nLog messages:\n\n" get_log_events_response.events.each do |event|
puts event.message
end
Amazon DynamoDB Examples
You can use the following examples to access Amazon DynamoDB services by using the AWS SDK for
Ruby. For more information about DynamoDB, see the Amazon DynamoDB documentation . Specifically, see Ruby and DynamoDB to learn how to:
• Create a table and load sample data in JSON format.
• Perform create, read, update, and delete operations on the table.
• Run simple queries.
The topic also provides a link to a downloadable version of DynamoDB, which includes an interactive web interface so you can experiment with DynamoDB offline.
Examples
Topics
•
Getting Information about All Tables (p. 30)
29
AWS SDK for Ruby Developer Guide
Getting Information about All Tables
•
Creating a Simple Table with a Single Primary Key (p. 30)
•
Adding an Item to a Table (p. 31)
•
Getting Information about the Items in a Table (p. 31)
•
Getting Information about a Specific Item in a Table (p. 31)
•
•
Getting Information about All Tables
The following example lists the names and number of items in each table in the us-west-2
region.
require 'aws-sdk' dynamoDB = Aws::DynamoDB::Resource.new(region: 'us-west-2') dynamoDB.tables.each do |t|
puts "Name: #{t.name}"
puts "#Items: #{t.item_count}" end
Creating a Simple Table with a Single Primary Key
The following example creates the table
Users
with three attributes:
ID
,
FirstName
, and
LastName
in the us-west-2
region.
The wait_until
call blocks you from using the table until DynamoDB has created it. By default, the
DynamoDB client's wait_until
method checks every 20 seconds, up to a maximum of 500 seconds, to see if the table was created.
require 'aws-sdk' attribute_defs = [
{ attribute_name: 'ID', attribute_type: 'N' },
{ attribute_name: 'FirstName', attribute_type: 'S' },
{ attribute_name: 'LastName', attribute_type: 'S' }
] key_schema = [
{ attribute_name: 'ID', key_type: 'HASH' }
] index_schema = [
{ attribute_name: 'FirstName', key_type: 'HASH' },
{ attribute_name: 'LastName', key_type: 'RANGE' }
] global_indexes = [{
index_name: 'LastNameFirstNameIndex',
key_schema: index_schema,
projection: { projection_type: 'ALL' },
provisioned_throughput: { read_capacity_units: 5, write_capacity_units: 10 }
}] request = {
attribute_definitions: attribute_defs,
table_name: 'Users',
key_schema: key_schema,
30
AWS SDK for Ruby Developer Guide
Adding an Item to a Table
global_secondary_indexes: global_indexes,
provisioned_throughput: { read_capacity_units: 5, write_capacity_units: 10 }
} dynamodb_client = Aws::DynamoDB::Client.new(region: 'us-west-2') dynamodb_client.create_table(request) dynamodb_client.wait_until(:table_exists, table_name: 'Users')
Adding an Item to a Table
The following example adds an item with the
ID
value of 123456,
FirstName
value of John, and
LastName
value of Doe to the
Users
table in the us-west-2
region.
require 'aws-sdk' dynamoDB = Aws::DynamoDB::Resource.new(region: 'us-west-2') table = dynamoDB.table('Users') table.put_item({
item:
{
"ID" => 123456,
"FirstName" => 'Snoop',
"LastName" => 'Doug'
}})
Getting Information about the Items in a Table
The following example lists up to 50 items from the
Users
table in the us-west-2
region.
require 'aws-sdk' dynamoDB = Aws::DynamoDB::Resource.new(region: 'us-west-2') table = dynamoDB.table('Users') scan_output = table.scan({
limit: 50,
select: "ALL_ATTRIBUTES"
}) scan_output.items.each do |item|
keys = item.keys
keys.each do |k|
puts "#{k}: #{item[k]}"
end end
Getting Information about a Specific Item in a Table
The following example displays the first and last name of an item with an
ID
of 123456 in the
Users table in the us-west-2
region.
require 'aws-sdk'
31
AWS SDK for Ruby Developer Guide
Updating a Table dynamoDB = Aws::DynamoDB::Resource.new(region: 'us-west-2') table = dynamoDB.table('Users') resp = table.get_item({
key: { 'ID' => 123456 }
}) first_name = resp.item['FirstName'] last_name = resp.item['LastName'] puts "First name: #{first_name}" puts "Last name: #{last_name}"
Updating a Table
The following example updates all the items in the
Users
table in the us-west-2
region to include a new field, airmiles
, and sets the value to 10000.
require 'aws-sdk' dynamoDB = Aws::DynamoDB::Resource.new(region: 'us-west-2') table = dynamoDB.table('Users')
# Get the IDs of all of the users resp = table.scan({ select: "ALL_ATTRIBUTES" }) resp.items.each do |item|
id = item['ID']
request = {
key: { 'ID' => id },
update_expression: 'set airmiles=:pVal',
expression_attribute_values: { ':pVal' => '10000' }
}
# Update the item in the table:
table.update_item(request) end
Creating an Index
The following example adds a new index, air-mileage-index
, to the
Users
table in the us-west-2 region. Once the status of the index is
ACTIVE
, you can search for items in the table based on the value of their airmiles
.
require 'aws-sdk' request = {
attribute_definitions: [
{
attribute_name: 'airmiles',
attribute_type: 'N',
},
],
table_name: 'Users',
global_secondary_index_updates: [
{
32
AWS SDK for Ruby Developer Guide
Amazon EC2 Examples
create: {
index_name: 'air-mileage-index',
key_schema: [
{
attribute_name: 'airmiles',
key_type: 'HASH',
},
],
projection: {
projection_type: 'ALL',
},
provisioned_throughput: {
read_capacity_units: 5,
write_capacity_units: 10,
},
},
},
],
} dynamoDB = Aws::DynamoDB::Client.new(region: 'us-west-2') dynamoDB.update_table(request)
Amazon EC2 Examples
You can use the following examples to access Amazon Elastic Compute Cloud (Amazon EC2) using the
AWS SDK for Ruby. For more information about Amazon EC2, see the Amazon EC2 Documentation .
Examples
Topics
•
•
Creating an Internet Gateway and Attaching It to a VPC (p. 34)
•
Creating a Public Subnet (p. 34)
•
Creating a Route Table and Associating It with a Subnet (p. 35)
•
Using Elastic IP Addresses in Amazon EC2 (p. 35)
•
Creating a Security Group (p. 37)
•
Working with Security Groups in Amazon EC2 (p. 37)
•
Working with Key Pairs (p. 40)
•
Getting Information about All Instances (p. 43)
•
Getting Information about All Instances with a Specific Tag Value (p. 43)
•
Getting Information about a Specific Instance (p. 43)
•
•
•
•
•
Managing Amazon EC2 Instances in Amazon EC2 (p. 45)
•
Terminating an Instance (p. 47)
•
Getting Information about Regions and Availability Zones (p. 47)
33
AWS SDK for Ruby Developer Guide
Creating a VPC
Creating a VPC
The following example creates the virtual private cloud (VPC)
MyGroovyVPC
with the CIDR block
10.200.0.0/16
, and then displays the VPC's ID.
The example creates a virtual network with 65,536 private IP addresses.
require 'aws-sdk' ec2 = Aws::EC2::Resource.new(region: 'us-west-2') vpc = ec2.create_vpc({ cidr_block: '10.200.0.0/16' })
# So we get a public DNS vpc.modify_attribute({
enable_dns_support: { value: true }
}) vpc.modify_attribute({
enable_dns_hostnames: { value: true }
})
# Name our VPC vpc.create_tags({ tags: [{ key: 'Name', value: 'MyGroovyVPC' }]}) puts vpc.vpc_id
Creating an Internet Gateway and Attaching It to a
VPC
The following example creates an Internet gateway
MyGroovyIGW
, attaches it to a VPC that has ID
VPC_ID
, and then displays the Internet gateway's ID.
require 'aws-sdk' ec2 = Aws::EC2::Resource.new(region: 'us-west-2') igw = ec2.create_internet_gateway
igw.create_tags({ tags: [{ key: 'Name', value: 'MyGroovyIGW' }]}) igw.attach_to_vpc(vpc_id: VPC_ID) puts igw.id
Creating a Public Subnet
The following example creates a public subnet
MyGroovySubnet
in the us-west-2
region and the
Availablity Zone us-west-2a
. The example attaches the public subnet to a VPC with the ID
VPC_ID
that uses the CIDR block
10.200.10.0/24
, and then displays the subnet's ID.
The public subnet created in this example has 256 private IP addresses within the VPC.
require 'aws-sdk' ec2 = Aws::EC2::Resource.new(region: 'us-west-2')
34
AWS SDK for Ruby Developer Guide
Creating a Route Table and Associating It with a Subnet subnet = ec2.create_subnet({
vpc_id: VPC_ID,
cidr_block: '10.200.10.0/24',
availability_zone: 'us-west-2a'
}) subnet.create_tags({ tags: [{ key: 'Name', value: 'MyGroovySubnet' }]}) puts subnet.id
Creating a Route Table and Associating It with a
Subnet
The following example creates a route table
MyGroovyRouteTable
in us-west-2
region on a VPC with the
ID
VPC_ID
. The route table uses the route with the CIDR block
0.0.0.0/0
and the gateway with the ID
IGW_ID
. The example associates the route table with the subnet that has ID
SUBNET_ID
, and then displays the route table's ID.
require 'aws-sdk' ec2 = Aws::EC2::Resource.new(region: 'us-west-2') table = ec2.create_route_table({
vpc_id: VPC_ID
}) table.create_tags({ tags: [{ key: 'Name', value: 'MyGroovyRouteTable' }]}) table.create_route({
destination_cidr_block: '0.0.0.0/0',
gateway_id: IGW_ID
}) table.associate_with_subnet({
subnet_id: SUBNET_ID
}) puts table.id
Using Elastic IP Addresses in Amazon EC2
An Elastic IP address is a static IP address, designed for dynamic cloud computing, that is associated with your AWS account. It's a public IP address, which is reachable from the Internet. If your instance doesn't have a public IP address, you can use an Elastic IP address with your instance so that it can communicate with the Internet.
For more information about Elastic IP addresses in Amazon EC2, see Elastic IP Addresses in the Amazon
EC2 User Guide for Linux Instances or Elastic IP Addresses in the Amazon EC2 User Guide for Windows
Instances.
In this example, you use the AWS SDK for Ruby with Amazon EC2 to:
1. Allocate an Elastic IP address by using the Aws::EC2::Client#allocate_address method.
2. Associate the address with an Amazon EC2 instance by using the Aws::EC2::Client#associate_address method.
3. Get information about addresses associated with the instance by using the
Aws::EC2::Client#describe_addresses method.
4. Release the address by using the Aws::EC2::Client#release_address method.
35
AWS SDK for Ruby Developer Guide
Using Elastic IP Addresses in Amazon EC2
The complete code for this example is available on GitHub.
Prerequisites
Before working with the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
You also need to launch an EC2 instance and note the instance ID.
Note
Before you run the following code, you must replace the
INSTANCE-ID
string with your actual instance ID. This will be something like i-0a123456b7c8defg9
.
Example Script
require 'aws-sdk' ec2 = Aws::EC2::Client.new(region: 'us-east-1') instance_id = "INSTANCE-ID" # For example, "i-0a123456b7c8defg9" def display_addresses(ec2, instance_id)
describe_addresses_result = ec2.describe_addresses({
filters: [
{
name: "instance-id",
values: [ instance_id ]
},
]
})
if describe_addresses_result.addresses.count == 0
puts "No addresses currently associated with the instance."
else
describe_addresses_result.addresses.each do |address|
puts "=" * 10
puts "Allocation ID: #{address.allocation_id}"
puts "Association ID: #{address.association_id}"
puts "Instance ID: #{address.instance_id}"
puts "Public IP: #{address.public_ip}"
puts "Private IP Address: #{address.private_ip_address}"
end
end end puts "Before allocating the address for the instance...." display_addresses(ec2, instance_id) puts "\nAllocating the address for the instance..." allocate_address_result = ec2.allocate_address({
domain: "vpc"
}) puts "\nAfter allocating the address for instance, but before associating the address with
the instance..." display_addresses(ec2, instance_id) puts "\nAssociating the address with the instance..." associate_address_result = ec2.associate_address({
allocation_id: allocate_address_result.allocation_id,
36
AWS SDK for Ruby Developer Guide
Creating a Security Group
instance_id: instance_id,
}) puts "\nAfter associating the address with the instance, but before releasing the address
from the instance..." display_addresses(ec2, instance_id) puts "\nReleasing the address from the instance..." ec2.release_address({
allocation_id: allocate_address_result.allocation_id,
}) puts "\nAfter releasing the address from the instance..." display_addresses(ec2, instance_id)
Creating a Security Group
The following example creates a security group
MyGroovySecurityGroup
in the us-west-2
region on a
VPC with the ID
VPC_ID
. In the example, the security group is allowed access over port 22 (SSH) from all addresses (CIDR block
0.0.0.0/0
) and is given the description "Security group for MyGroovyInstance".
Then, the security group's ID is displayed.
require 'aws-sdk' ec2 = Aws::EC2::Resource.new(region: 'us-west-2') sg = ec2.create_security_group({
group_name: 'MyGroovySecurityGroup',
description: 'Security group for MyGroovyInstance',
vpc_id: VPC_ID
}) sg.authorize_egress({
ip_permissions: [{
ip_protocol: 'tcp',
from_port: 22,
to_port: 22,
ip_ranges: [{
cidr_ip: '0.0.0.0/0'
}]
}) puts sg.id
Working with Security Groups in Amazon EC2
An Amazon EC2 security group acts as a virtual firewall that controls the traffic for one or more instances. You add rules to each security group to allow traffic to or from its associated instances. You can modify the rules for a security group at any time; the new rules are automatically applied to all instances that are associated with the security group.
For more information about the Amazon EC2 security groups, see:
• Amazon EC2 Amazon Security Groups for Linux Instances
• Amazon EC2 Security Groups for Windows Instances
In this example, we use the AWS SDK for Ruby with Amazon EC2 to:
1. Create a security group.
37
AWS SDK for Ruby Developer Guide
Working with Security Groups in Amazon EC2
2. Add rules to the security group.
3. Get information about security groups.
4. Delete the security group.
The full sample script containing all of the following examples is available on GitHub .
Prerequisites
Before working with the code below, you need to install and configure the AWS SDK for Ruby. See the following:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
You'll also need to create a VPC and note the VPC ID.
Configure the SDK
First we require the AWS SDK for Ruby and create an EC2 client. Then we provide a name for the security group we're going to create. We also need to provide the ID of our VPC, which is available in the console after the VPC is created.
Be sure that you replace ``VPC-ID`` with your actual VPC ID.
require 'aws-sdk' ec2 = Aws::EC2::Client.new(region: 'us-east-1') security_group_name = "my-security-group" vpc_id = "VPC-ID" # For example, "vpc-1234ab56".
security_group_created = false # Used later to determine whether it's okay to delete the
security group.
We'll use the security_group_created
variable later in the script to determine if a security group was created and can therefore be deleted.
Create a Security Group
Next we create a security group that allows access over ports 22 (SSH) and 80 (HTTP) from all addresses
(CIDR block
0.0.0.0/0
).
# Create a security group.
begin
create_security_group_result = ec2.create_security_group({
group_name: security_group_name,
description: "An example description for my security group.",
vpc_id: vpc_id
})
# Add rules to the security group.
# For example, allow all inbound HTTP and SSH traffic.
ec2.authorize_security_group_ingress({
group_id: create_security_group_result.group_id,
ip_permissions: [
{
ip_protocol: "tcp",
from_port: 80,
to_port: 80,
38
AWS SDK for Ruby Developer Guide
Working with Security Groups in Amazon EC2
ip_ranges: [
{
cidr_ip: "0.0.0.0/0",
}
]
},
{
ip_protocol: "tcp",
from_port: 22,
to_port: 22,
ip_ranges: [
{
cidr_ip: "0.0.0.0/0",
}
]
}
]
})
security_group_created = true rescue Aws::EC2::Errors::InvalidGroupDuplicate
puts "A security group with the name '#{security_group_name}' already exists." end
If the begin
block executes without exception, we set security_group_created
to true
.
Get Info about a Security Group
Having created a security group, we output information about our existing security groups and their IP permissions.
def describe_ip_permission(ip_permission)
puts "-" * 22
puts "IP Protocol: #{ip_permission.ip_protocol}"
puts "From Port: #{ip_permission.from_port.to_s}"
puts "To Port: #{ip_permission.to_port.to_s}"
if ip_permission.ip_ranges.count > 0
puts "IP Ranges:"
ip_permission.ip_ranges.each do |ip_range|
puts " #{ip_range.cidr_ip}"
end
end
if ip_permission.ipv_6_ranges.count > 0
puts "IPv6 Ranges:"
ip_permission.ipv_6_ranges.each do |ipv_6_range|
puts " #{ipv_6_range.cidr_ipv_6}"
end
end
if ip_permission.prefix_list_ids.count > 0
puts "Prefix List IDs:"
ip_permission.prefix_list_ids.each do |prefix_list_id|
puts " #{prefix_list_id.prefix_list_id}"
end
end
if ip_permission.user_id_group_pairs.count > 0
puts "User ID Group Pairs:"
ip_permission.user_id_group_pairs.each do |user_id_group_pair|
puts " ." * 7
puts " Group ID: #{user_id_group_pair.group_id}"
puts " Group Name: #{user_id_group_pair.group_name}"
puts " Peering Status: #{user_id_group_pair.peering_status}"
puts " User ID: #{user_id_group_pair.user_id}"
puts " VPC ID: #{user_id_group_pair.vpc_id}"
puts " VPC Peering Connection ID: #{user_id_group_pair.vpc_peering_connection_id}"
39
AWS SDK for Ruby Developer Guide
Working with Key Pairs
end
end end describe_security_groups_result = ec2.describe_security_groups
describe_security_groups_result.security_groups.each do |security_group|
puts "\n"
puts "*" * (security_group.group_name.length + 12)
puts "Group Name: #{security_group.group_name}"
puts "Group ID: #{security_group.group_id}"
puts "Description: #{security_group.description}"
puts "VPC ID: #{security_group.vpc_id}"
puts "Owner ID: #{security_group.owner_id}"
if security_group.ip_permissions.count > 0
puts "=" * 22
puts "IP Permissions:"
security_group.ip_permissions.each do |ip_permission|
describe_ip_permission(ip_permission)
end
end
if security_group.ip_permissions_egress.count > 0
puts "=" * 22
puts "IP Permissions Egress:"
security_group.ip_permissions_egress.each do |ip_permission|
describe_ip_permission(ip_permission)
end
end
if security_group.tags.count > 0
puts "=" * 22
puts "Tags:"
security_group.tags.each do |tag|
puts " #{tag.key} = #{tag.value}"
end
end end
Delete a Security Group
At the end of the script, assuming that a security group was successfully created and the security_group_created
flag set to true
, we delete the security group.
if security_group_created
ec2.delete_security_group({ group_id: create_security_group_result.group_id }) end
Working with Key Pairs
These examples show you how to use the AWS SDK for Ruby with Amazon EC2 to:
• Create a key pair.
• Get information about key pairs.
• Delete a key pair.
For more information about key pairs, see Amazon EC2 Key Pairs in the Amazon EC2 User Guide for Linux
Instances or Amazon EC2 Key Pairs and Windows Instances in the Amazon EC2 User Guide for Windows
Instances.
For additional code that you can use to run these examples, see Complete Example (p. 42) .
40
AWS SDK for Ruby Developer Guide
Working with Key Pairs
Create a Key Pair
Call the create_key_pair method, specifying the name of the key pair to create.
key_pair = ec2.create_key_pair({
key_name: key_pair_name
})
In this code:
• ec2
is a variable representing an Aws::EC2::Client object.
• key_pair_name
is a string variable representing the name of the key pair.
• key_pair
is a variable representing an Aws::EC2::KeyPair object that is returned by calling the create_key_pair
method.
For more information, see
.
Get Information about Key Pairs
To get information about a single key pair, use attributes such as:
• key_name , which gets the key pair's name.
• key_fingerprint , which gets the SHA-1 digest of the DER encoded private key.
• key_material , which gets the unencrypted PEM encoded RSA private key.
puts "Created key pair '#{key_pair.key_name}'."
puts "\nSHA-1 digest of the DER encoded private key:"
puts "#{key_pair.key_fingerprint}"
puts "\nUnencrypted PEM encoded RSA private key:"
puts "#{key_pair.key_material}"
In this code, key_pair
is a variable representing an Aws::EC2::KeyPair object, which is returned by calling the create_key_pair method in the previous example.
To get information about multiple key pairs, call the describe_key_pairs method.
key_pairs_result = ec2.describe_key_pairs() if key_pairs_result.key_pairs.count > 0
puts "\nKey pair names:"
key_pairs_result.key_pairs.each do |key_pair|
puts key_pair.key_name
end end
In this code:
• ec2
is a variable representing an Aws::EC2::Client object.
• key_pair_result
is a variable representing an Aws::EC2::Types::DescribeKeyPairsResult object that is returned by calling the describe_key_pairs
method.
• Calling the
Aws::EC2::Types::DescribeKeyPairsResult
object's key_pairs method returns an array of
Aws::EC2::Types::KeyPairInfo objects, which represent the key pairs.
For more information, see
.
41
AWS SDK for Ruby Developer Guide
Working with Key Pairs
Delete a Key Pair
Call the delete_key_pair method, specifying the name of the key pair to delete.
ec2.delete_key_pair({
key_name: key_pair_name
})
In this code:
• ec2
is a variable representing an Aws::EC2::Client object.
• key_pair_name
is a string variable representing the name of the key pair.
For more information, see
.
Complete Example
The following code, which you can adapt and run, combines the preceding examples into a single example.
require 'aws-sdk' ec2 = Aws::EC2::Client.new(region: 'us-east-1') key_pair_name = "my-key-pair"
# Create a key pair.
begin
key_pair = ec2.create_key_pair({
key_name: key_pair_name
})
puts "Created key pair '#{key_pair.key_name}'."
puts "\nSHA-1 digest of the DER encoded private key:"
puts "#{key_pair.key_fingerprint}"
puts "\nUnencrypted PEM encoded RSA private key:"
puts "#{key_pair.key_material}" rescue Aws::EC2::Errors::InvalidKeyPairDuplicate
puts "A key pair named '#{key_pair_name}' already exists." end
# Get information about Amazon EC2 key pairs.
key_pairs_result = ec2.describe_key_pairs() if key_pairs_result.key_pairs.count > 0
puts "\nKey pair names:"
key_pairs_result.key_pairs.each do |key_pair|
puts key_pair.key_name
end end
# Delete the key pair.
ec2.delete_key_pair({
key_name: key_pair_name
})
To run this code, you must:
1. Install the AWS SDK for Ruby. For more information, see Installing the AWS SDK for Ruby (p. 4)
.
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 (p. 5)
. Be
42
AWS SDK for Ruby Developer Guide
Getting Information about All Instances 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 or in the
AWS_ACCESS_KEY_ID
and
AWS_SECRET_ACCESS_KEY
environment variables on your local system.
Getting Information about All Instances
The following example lists the IDs and states (pending, running, shutting down, terminated, stopping, or stopped) for all of your Amazon EC2 instances in the us-west-2
region.
require 'aws-sdk' ec2 = Aws::EC2::Resource.new(region: 'us-west-2')
# To only get the first 10 instances:
# ec2.instances.limit(10).each do |i| ec2.instances.each do |i|
puts "ID: #{i.id}"
puts "State: #{i.state.name}" end
Getting Information about All Instances with a
Specific Tag Value
The following example lists the ID and state (pending, running, shutting down, terminated, stopping, or stopped) of an Amazon EC2 instance with the tag
Group
and tag value
MyGroovyGroup
in the us-west-2 region.
Note
The tag name and value are case-sensitive.
require 'aws-sdk' ec2 = Aws::EC2::Resource.new(region: 'us-west-2')
# Get all instances with tag key 'Group'
# and tag value 'MyGroovyGroup': ec2.instances({filters: [{name: 'tag:Group', values: ['MyGroovyGroup']}]}).each do |i|
puts 'ID: ' + i.id
puts 'State: ' + i.state.name
end
Getting Information about a Specific Instance
The following example lists the state of an instance i-123abc
in the us-west-2
region.
require 'aws-sdk' ec2 = Aws::EC2::Resource.new(region: 'us-west-2') i = ec2.instance('i-123abc') if i.exists?
puts "State: #{i.state.name}" end
43
AWS SDK for Ruby Developer Guide
Creating an Instance
Creating an Instance
The following example creates an Amazon EC2 instance
MyGroovyInstance
, with the tag
Group
and value
MyGroovyGroup
. The instance is created in Availability Zone us-west-2a
with the machine image
MACHINE_IMAGE
for the account with ID
ACCOUNT_ID
, the security group with the ID
SECURITY_GROUP_ID
, and the subnet with the ID
SUBNET_ID
. Then, it displays the instance's ID and public IP address.
Note
In the empty script value, you can add instructions that your Amazon EC2 instance executes when it starts.
require 'aws-sdk' require 'base64'
# User code that's executed when the instance starts script = '' encoded_script = Base64.encode64(script) ec2 = Aws::EC2::Resource.new(region: 'us-west-2') instance = ec2.create_instances({
image_id: 'IMAGE_ID',
min_count: 1,
max_count: 1,
key_name: 'MyGroovyKeyPair',
security_group_ids: ['SECURITY_GROUP_ID'],
user_data: encoded_script,
instance_type: 't2.micro',
placement: {
availability_zone: 'us-west-2a'
},
subnet_id: 'SUBNET_ID',
iam_instance_profile: {
arn: 'arn:aws:iam::' + 'ACCOUNT_ID' + ':instance-profile/aws-opsworks-ec2-role'
}
})
# Wait for the instance to be created, running, and passed status checks ec2.client.wait_until(:instance_status_ok, {instance_ids: [instance[0].id]})
# Name the instance 'MyGroovyInstance' and give it the Group tag 'MyGroovyGroup' instance.create_tags({ tags: [{ key: 'Name', value: 'MyGroovyInstance' }, { key: 'Group',
value: 'MyGroovyGroup' }]}) puts instance.id
puts instance.public_ip_address
Stopping an Instance
The following example stops the instance i-123abc
in the us-west-2
region.
require 'aws-sdk' ec2 = Aws::EC2::Resource.new(region: 'us-west-2') i = ec2.instance('i-123abc') if i.exists?
case i.state.code
when 48 # terminated
puts "#{id} is terminated, so you cannot stop it"
44
AWS SDK for Ruby Developer Guide
Starting an Instance
when 64 # stopping
puts "#{id} is stopping, so it will be stopped in a bit"
when 89 # stopped
puts "#{id} is already stopped"
else
i.stop
end end
Starting an Instance
The following example starts the instance i-123abc
in the us-west-2
region.
require 'aws-sdk' ec2 = Aws::EC2::Resource.new(region: 'us-west-2') i = ec2.instance('i-123abc') if i.exists?
case i.state.code
when 0 # pending
puts "#{id} is pending, so it will be running in a bit"
when 16 # started
puts "#{id} is already started"
when 48 # terminated
puts "#{id} is terminated, so you cannot start it"
else
i.start
end end
Rebooting an Instance
The following example reboots the instance i-123abc
in the us-west-2
region.
require 'aws-sdk' ec2 = Aws::EC2::Resource.new(region: 'us-west-2') i = ec2.instance('i-123abc') if i.exists?
case i.state.code
when 48 # terminated
puts "#{id} is terminated, so you cannot reboot it"
else
i.reboot
end end
Managing Amazon EC2 Instances in Amazon EC2
In this example, you use the AWS SDK for Ruby with Amazon EC2 to:
1. Stop an existing Amazon EC2 instance by using Aws::EC2::Client#stop_instances .
2. Restart the instance by using Aws::EC2::Client#start_instances .
3. Reboot the instance by using Aws::EC2::Client#reboot_instances .
4. Enable detailed monitoring for the instance by using Aws::EC2::Client#monitor_instances .
45
AWS SDK for Ruby Developer Guide
Managing Amazon EC2 Instances in Amazon EC2
5. Get information about available instances by using Aws::EC2::Client#describe_instances .
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
You also need to replace INSTANCE-ID in the code with the instance ID of an existing EC2 instance.
Example
require 'aws-sdk'
# Uncomment for Windows.
# Aws.use_bundled_cert!
def wait_for_instances(ec2, state, ids)
begin
ec2.wait_until(state, instance_ids: ids)
puts "Success: #{state}."
rescue Aws::Waiters::Errors::WaiterFailed => error
puts "Failed: #{error.message}"
end end ec2 = Aws::EC2::Client.new(region: 'us-east-1') instance_id = "INSTANCE-ID" # For example, "i-0a123456b7c8defg9" puts "Attempting to stop instance '#{instance_id}'. This may take a few minutes..." ec2.stop_instances({ instance_ids: [instance_id] }) wait_for_instances(ec2, :instance_stopped, [instance_id]) puts "\nAttempting to restart instance '#{instance_id}'. This may take a few minutes..." ec2.start_instances({ instance_ids: [instance_id] }) wait_for_instances(ec2, :instance_running, [instance_id]) puts "\nAttempting to reboot instance '#{instance_id}'. This may take a few minutes..." ec2.reboot_instances({ instance_ids: [instance_id] }) wait_for_instances(ec2, :instance_status_ok, [instance_id])
# Enable detailed monitoring for the instance.
puts "\nAttempting to enable detailed monitoring for instance '#{instance_id}'..." begin
monitor_instances_result = ec2.monitor_instances({
instance_ids: [instance_id]
})
puts "Detailed monitoring state for instance '#{instance_id}':
#{monitor_instances_result.instance_monitorings[0].monitoring.state}" rescue Aws::EC2::Errors::InvalidState
puts "Instance '#{instance_id}' is not in a monitorable state. Continuing on..." end
# Get information about available instances.
puts "\nAvailable instances:" describe_instances_result = ec2.describe_instances
46
AWS SDK for Ruby Developer Guide
Terminating an Instance describe_instances_result.reservations.each do |reservation|
if reservation.instances.count > 0
reservation.instances.each do |instance|
puts "=" * (instance.instance_id.length + 13)
puts "Instance ID: #{instance.instance_id}"
puts "State: #{instance.state.name}"
puts "Image ID: #{instance.image_id}"
puts "Instance Type: #{instance.instance_type}"
puts "Architecure: #{instance.architecture}"
puts "IAM Instance Profile: #{instance.iam_instance_profile}"
puts "Key Name: #{instance.key_name}"
puts "Launch Time: #{instance.launch_time}"
puts "Detailed Monitoring State: #{instance.monitoring.state}"
puts "Public IP Address: #{instance.public_ip_address}"
puts "Public DNS Name: #{instance.public_dns_name}"
puts "VPC ID: #{instance.vpc_id}"
puts "Subnet ID: #{instance.subnet_id}"
if instance.tags.count > 0
puts "Tags:"
instance.tags.each do |tag|
puts " #{tag.key} = #{tag.value}"
end
end
end
end end
Terminating an Instance
The following example terminates the instance i-123abc
in the us-west-2
region.
require 'aws-sdk' ec2 = Aws::EC2::Resource.new(region: 'us-west-2') i = ec2.instance('i-123abc') if i.exists?
case i.state.code
when 48 # terminated
puts "#{id} is already terminated"
else
i.terminate
end end
Getting Information about Regions and Availability
Zones
These examples show you how to use the AWS SDK for Ruby together with Amazon EC2 to:
• Get information about available Amazon EC2 regions and their endpoints.
• Get information about available Amazon EC2 Availability Zones.
For more information about Amazon EC2 regions and Availability Zones, see Regions and Availability
Zones in the Amazon EC2 User Guide for Linux Instances.
47
AWS SDK for Ruby Developer Guide
Getting Information about Regions and Availability Zones
For additional code that you can use to run these examples, see Complete Example (p. 49) .
Get Information about Regions and Endpoints
To get information about available regions, call the describe_regions method.
describe_regions_result = ec2.describe_regions()
In this code, ec2
is a variable representing an Aws::EC2::Client object. For more information, see
.
To get the region names and endpoints:
1. Get an Aws::EC2::Types::DescribeRegionsResult object, which is returned by the describe_regions method and represented in this code by the describe_regions_result
variable.
2. Use the
DescribeRegionsResult
object's regions attribute to get an array of Aws::EC2::Types::Region objects representing the regions.
3. Get each region's name and endpoint by using the
Region
object's region_name and endpoint attributes.
describe_regions_result.regions.each do |region|
puts "#{region.region_name} (#{region.endpoint})" end
Get Information about Availability Zones
To get information about availability zones, call the describe_availability_zones method.
describe_availability_zones_result = ec2.describe_availability_zones()
The Aws::EC2::Types::DescribeAvailabilityZonesResult object contains an array of
Aws::EC2::Types::AvailabilityZone objects representing the Availability Zones. The
DescribeAvailabilityZonesResult
object is returned by the describe_availability_zones
method and represented in this code by the describe_availability_zones_result
variable.
In this code, ec2
is a variable representing an Aws::EC2::Client object. For more information, see
.
To get the name and state of each availability zone, use the
AvailabilityZone
object's zone_name and state attributes.
describe_availability_zones_result.availability_zones.each do |zone|
puts "#{zone.zone_name} is #{zone.state}"
if zone.messages.count > 0
zone.messages.each do |message|
" #{message.message}"
end
end end
To get any messages about availability zones:
1. Use the
AvailabilityZone
object's messages attribute, which returns an
Aws::EC2::Types::AvailabilityZoneMessage array.
2. If there is at least one message in the array, use each
AvailabilityZoneMessage
object's message attribute to get the message.
48
AWS SDK for Ruby Developer Guide
AWS Elastic Beanstalk Examples
Complete Example
The following code, which you can adapt and run, combines the preceding examples into a single example.
require 'aws-sdk' ec2 = Aws::EC2::Client.new(region: 'us-east-1') puts "Amazon EC2 region(s) (and their endpoint(s)) that are currently available to you:\n
\n" describe_regions_result = ec2.describe_regions() describe_regions_result.regions.each do |region|
puts "#{region.region_name} (#{region.endpoint})" end puts "\nAmazon EC2 availability zone(s) that are available to you for your current region:
\n\n" describe_availability_zones_result = ec2.describe_availability_zones() describe_availability_zones_result.availability_zones.each do |zone|
puts "#{zone.zone_name} is #{zone.state}"
if zone.messages.count > 0
zone.messages.each do |message|
" #{message.message}"
end
end end
To run this code:
1. Install the AWS SDK for Ruby. For more information, see Installing the AWS SDK for Ruby (p. 4)
.
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 (p. 5)
. 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 or in the
AWS_ACCESS_KEY_ID
and
AWS_SECRET_ACCESS_KEY
environment variables on your local system.
AWS Elastic Beanstalk Examples
You can use the following examples to access AWS Elastic Beanstalk (Elastic Beanstalk) using the AWS
SDK for Ruby. For more information about Elastic Beanstalk, see the Elastic Beanstalk Developer Guide .
Examples
Topics
•
Getting Information about All Applications (p. 49)
•
Getting Information about a Specific Application (p. 50)
•
Updating a Ruby on Rails Application (p. 50)
Getting Information about All Applications
The following example lists the names, descriptions, and URLs of all of your Elastic Beanstalk applications in the us-west-2
region.
49
AWS SDK for Ruby Developer Guide
Getting Information about a Specific Application require 'aws-sdk' elb = Aws::ElasticBeanstalk::Client.new(region: 'us-west-2') elb.describe_applications.applications.each do |a|
puts "Name: #{a.application_name}"
puts "Description: #{a.description}"
elb.describe_environments({application_name: a.application_name}).environments.each do | env|
puts " Environment: #{env.environment_name}"
puts " URL: #{env.cname}"
puts " Health: #{env.health}"
end end
Getting Information about a Specific Application
The following example lists the name, description, and URL of the
MyRailsApp
application in the uswest-2
region.
require 'aws-sdk' elb = Aws::ElasticBeanstalk::Client.new(region: 'us-west-2') app = elb.describe_applications({application_names: [args[0]]}) if app.exists?
puts "Name: #{app.application_name}"
puts "Description: #{app.description}"
envs = elb.describe_environments({application_name: app.application_name})
puts "URL: #{envs.environments[0].cname}" end
Updating a Ruby on Rails Application
The following example updates the Ruby on Rails application
MyRailsApp
in the us-west-2
region.
Note
You must be in the root of your Rails app to succesfully run the script.
require 'aws-sdk'
Aws.config.update({region: 'us-west-2'}) elb = Aws::ElasticBeanstalk::Client.new
s3 = Aws::S3::Client.new
app_name = 'MyRailsApp'
# Get S3 bucket containing app app_versions = elb.describe_application_versions({ application_name: app_name }) av = app_versions.application_versions[0] bucket = av.source_bundle.s3_bucket
s3_key = av.source_bundle.s3_key
# Get info on environment envs = elb.describe_environments({ application_name: app_name }) env = envs.environments[0]
50
AWS SDK for Ruby Developer Guide
AWS Identity and Access Management Examples env_name = env.environment_name
# Create new storage location resp = elb.create_storage_location() puts "Created storage location in bucket #{resp.s3_bucket}" resp = s3.list_objects({
prefix: s3_key,
bucket: bucket
})
# Create ZIP file zip_file_basename = SecureRandom.urlsafe_base64.to_s
zip_file_name = zip_file_basename + '.zip'
# Call out to OS to produce ZIP file cmd = "git archive --format=zip -o #{zip_file_name} HEAD"
%x[ #{cmd} ]
# Get ZIP file contents zip_contents = File.read(zip_file_name) key = app_name + "\\" + zip_file_name resp = s3.put_object({
body: zip_contents,
bucket: bucket,
key: key
}) date = Time.new
today = date.day.to_s + "/" + date.month.to_s + "/" + date.year.to_s
elb.create_application_version({
process: false,
application_name: app_name,
version_label: zip_file_basename,
source_bundle: {
s3_bucket: bucket,
s3_key: key
},
description: "Updated #{today}"
}) elb.update_environment({
environment_name: env_name,
version_label: zip_file_basename
})
AWS Identity and Access Management Examples
You can use the following examples to access AWS Identity and Access Management (IAM) using the AWS
SDK for Ruby. For more information about IAM, see the IAM documentation .
Examples
Topics
•
Getting Information about All Users (p. 52)
•
•
Create a User's Access Keys (p. 53)
51
AWS SDK for Ruby Developer Guide
Getting Information about All Users
•
Adding a Managed Policy (p. 53)
•
•
•
Working with IAM Policies (p. 55)
•
Managing IAM Access Keys (p. 56)
•
Working with IAM Server Certificates (p. 58)
•
Managing IAM Account Aliases (p. 59)
Getting Information about All Users
The following example lists the groups, policies, and access key IDs of all IAM users in the us-west-2 region.
require 'aws-sdk' iam = Aws::IAM::Client.new(region: 'us-west-2') iam.list_users.users.each do |user|
name = user.user_name
puts "For user #{name}"
puts " In groups:"
iam.list_groups_for_user({user_name: name}).groups.each do |group|
puts " #{group.group_name}"
end
puts " Policies:"
iam.list_user_policies({user_name: name}).policy_names.each do |policy|
puts " #{policy}"
end
puts " Access keys:"
iam.list_access_keys({user_name: name}).access_key_metadata.each do |key|
puts " #{key.access_key_id}"
end end
Adding a New User
The following example creates the IAM user my_groovy_user
in the us-west-2
region with the password
REPLACE_ME
, and displays the user's account ID. If a user with that name already exists, it displays a message and does not create a new user.
require 'aws-sdk' iam = Aws::IAM::Client.new(region: 'us-west-2') begin
user = iam.create_user(user_name: 'my_groovy_user')
iam.wait_until(:user_exists, user_name: 'my_groovy_user')
user.create_login_profile({password: 'REPLACE_ME'})
arn_parts = user.arn.split(':')
puts 'Account ID: ' + arn_parts[4] rescue Aws::IAM::Errors::EntityAlreadyExists
52
AWS SDK for Ruby Developer Guide
Create a User's Access Keys
puts 'User already exists' end
Create a User's Access Keys
The following example creates an access key and secret key for the IAM user my_groovy_user
in the :code-:us-west-2 region.
require 'aws-sdk' iam = Aws::IAM::Client.new(region: 'us-west-2') begin
user = iam.user(user_name: 'my_groovy_user')
key_pair = user.create_access_key_pair
puts "Access key: #{key_pair.access_key_id}"
puts "Secret key: #{key_pair.secret}" rescue Aws::IAM::Errors::NoSuchEntity => ex
puts 'User does not exist' end
Adding a Managed Policy
The following example adds the managed policy
AmazonS3FullAccess
to the IAM user my_groovy_user
in the us-west-2
region.
require 'aws-sdk'
# Policy ARNs start with: prefix = 'arn:aws:iam::aws:policy/' policy_arn = prefix + 'AmazonS3FullAccess'
# In case the policy or user does not exist begin
client.attach_user_policy({user_name: 'my_groovy_user', policy_arn: policy_arn}) rescue Aws::IAM::Errors::NoSuchEntity => ex
puts "Error attaching policy '#{policy_arn}'"
puts ex.message
end
Creating a Role
The following example creates the role my_groovy_role
so that Amazon EC2 can access Amazon S3 and
Amazon DynamoDB in the us-west-2
region.
require 'aws-sdk' client = Aws::IAM::Client.new(region: 'us-west-2') iam = Aws::IAM::Resource.new(client: client)
# Let EC2 assume a role policy_doc = {
Version:"2012-10-17",
Statement:[
{
53
AWS SDK for Ruby Developer Guide
Managing IAM Users
Effect:"Allow",
Principal:{
Service:"ec2.amazonaws.com"
},
Action:"sts:AssumeRole"
}]
} role = iam.create_role({
role_name: 'my_groovy_role',
assume_role_policy_document: policy_doc.to_json
})
# Give the role full access to S3 role.attach_policy({
policy_arn: 'arn:aws:iam::aws:policy/AmazonS3FullAccess'
})
# Give the role full access to DynamoDB role.attach_policy({
policy_arn: 'arn:aws:iam::aws:policy/AmazonDynamoDBFullAccess'
})
Managing IAM Users
An IAM user represents a person or service that interacts with AWS. For more information about IAM users, see IAM Users .
In this example, you use the AWS SDK for Ruby with IAM to:
1. Get information about available AWS IAM users by using Aws::IAM::Client#list_users .
2. Create a user by using Aws::IAM::Client#create_user .
3. Update the user's name by using Aws::IAM::Client#update_user .
4. Delete the user by using Aws::IAM::Client#delete_user .
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
Example
require 'aws-sdk' iam = Aws::IAM::Client.new(region: 'us-east-1') user_name = "my-user" changed_user_name = "my-changed-user"
# Get information about available AWS IAM users.
def list_user_names(iam)
list_users_response = iam.list_users
list_users_response.users.each do |user|
puts user.user_name
54
AWS SDK for Ruby Developer Guide
Working with IAM Policies
end end puts "User names before creating user..." list_user_names(iam)
# Create a user.
puts "\nCreating user..." iam.create_user({ user_name: user_name }) puts "\nUser names after creating user..." list_user_names(iam)
# Update the user's name.
puts "\nChanging user's name..." begin
iam.update_user({
user_name: user_name,
new_user_name: changed_user_name
})
puts "\nUser names after updating user's name..."
list_user_names(iam) rescue Aws::IAM::Errors::EntityAlreadyExists
puts "User '#{user_name}' already exists." end
# Delete the user.
puts "\nDeleting user..." iam.delete_user({ user_name: changed_user_name }) puts "\nUser names after deleting user..." list_user_names(iam)
Working with IAM Policies
An IAM policy is a document that specifies one or more permissions. For more information about IAM policies, see Overview of IAM Policies .
In this example, you use the AWS SDK for Ruby with IAM to:
1. Create a policy, using Aws::IAM::Client#create_policy .
2. Get information about the policy, using Aws::IAM::Client#get_policy .
3. Attach the policy to a role, using Aws::IAM::Client#attach_role_policy .
4. List policies attached to the role, using Aws::IAM::Client#list_attached_role_policies .
5. Detach the policy from the role, using Aws::IAM::Client#detach_role_policy .
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
You will also need to create the role (my-role) specified in the script. You can do this in the IAM console.
55
AWS SDK for Ruby Developer Guide
Managing IAM Access Keys
Example
require 'aws-sdk' iam = Aws::IAM::Client.new(region: 'us-east-1') role_name = "my-role" policy_name = "my-policy" policy_document = {
"Version" => "2012-10-17",
"Statement" => [
{
"Effect" => "Allow",
"Action" => "s3:ListAllMyBuckets",
"Resource" => "arn:aws:s3:::*"
}
]
}.to_json
# Create a policy.
puts "Creating policy..." create_policy_response = iam.create_policy({
policy_name: policy_name,
policy_document: policy_document
}) policy_arn = create_policy_response.policy.arn
# Get information about the policy.
get_policy_response = iam.get_policy({ policy_arn: policy_arn }) puts "\nCreated policy, ID = #{get_policy_response.policy.policy_id}"
# Attach the policy to a role.
puts "\nAttaching policy to role..." iam.attach_role_policy({
role_name: role_name,
policy_arn: policy_arn
})
# List policies attached to the role.
puts "\nAttached role policy ARNs..." iam.list_attached_role_policies({ role_name: role_name }).attached_policies.each do | attached_policy|
puts " #{attached_policy.policy_arn}" end
# Detach the policy from the role.
puts "\nDetaching role policy..." iam.detach_role_policy({
role_name: role_name,
policy_arn: policy_arn
})
Managing IAM Access Keys
Users need their own access keys to make programmatic calls to AWS from the SDK for Ruby. To fill this need, you can create, modify, view, or rotate access keys (access key IDs and secret access keys) for IAM
56
AWS SDK for Ruby Developer Guide
Managing IAM Access Keys users. By default, when you create an access key, its status is Active, which means the user can use the access key for API calls. For more information about access keys, see Managing Access Keys for IAM Users .
In this example, you use the AWS SDK for Ruby with IAM to:
1. List AWS IAM user access keys, using Aws::IAM::Client#list_access_keys .
2. Create an access key, using Aws::IAM::Client#create_access_key .
3. Determine when access keys were last used, using Aws::IAM::Client#get_access_key_last_used .
4. Deactivate access keys, using Aws::IAM::Client#update_access_key .
5. Delete the access key, using Aws::IAM::Client#delete_access_key .
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
You will also need to create the user (my-user) specified in the script. You can create a new IAM user in the IAM console or programmatically, as shown at
Example
require 'aws-sdk' iam = Aws::IAM::Client.new(region: 'us-east-1') user_name = "my-user"
# List user access keys.
def list_keys(iam, user_name)
begin
list_access_keys_response = iam.list_access_keys({ user_name: user_name })
if list_access_keys_response.access_key_metadata.count == 0
puts "No access keys."
else
puts "Access keys:"
list_access_keys_response.access_key_metadata.each do |key_metadata|
puts " Access key ID: #{key_metadata.access_key_id}"
end
end
rescue Aws::IAM::Errors::NoSuchEntity
puts "Cannot find user '#{user_name}'."
exit(false)
end end puts "Before creating access key..." list_keys(iam, user_name)
# Create an access key.
puts "\nCreating access key..." begin
iam.create_access_key({ user_name: user_name })
puts "\nAfter creating access key..."
57
AWS SDK for Ruby Developer Guide
Working with IAM Server Certificates
list_keys(iam, user_name) rescue Aws::IAM::Errors::LimitExceeded
puts "Too many access keys. Can't create any more." end
# Determine when access keys were last used.
puts "\nKey(s) were last used..." list_access_keys_response = iam.list_access_keys({ user_name: user_name }) list_access_keys_response.access_key_metadata.each do |key_metadata|
resp = iam.get_access_key_last_used({ access_key_id: key_metadata.access_key_id })
puts " Key '#{key_metadata.access_key_id}' last used on
#{resp.access_key_last_used.last_used_date}"
# Deactivate access keys.
puts " Trying to deactivate this key..."
iam.update_access_key({
user_name: user_name,
access_key_id: key_metadata.access_key_id,
status: "Inactive"
}) end puts "\nAfter deactivating access key(s)..." list_keys(iam, user_name)
# Delete the access key.
puts "\nDeleting access key..." iam.delete_access_key({
user_name: user_name,
access_key_id: list_access_keys_response.access_key_metadata[0].access_key_id
}) puts "\nAfter deleting access key..." list_keys(iam, user_name)
Working with IAM Server Certificates
To enable HTTPS connections to your website or application on AWS, you need an SSL/TLS server certificate. To use a certificate that you obtained from an external provider with your website or application on AWS, you must upload the certificate to IAM or import it into AWS Certificate Manager.
For more information about server certificates, see Working with Server Certificates .
In this example, you use the AWS SDK for Ruby with IAM to:
1. Update a server certificate, using Aws::IAM::Client#update_server_certificate .
2. Delete the server certificate, using Aws::IAM::Client#delete_server_certificate .
3. List information about any remaining server certificates, using
Aws::IAM::Client#list_server_certificates .
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
58
AWS SDK for Ruby Developer Guide
Managing IAM Account Aliases
•
Configuring the AWS SDK for Ruby (p. 5)
Note also that the server certificate must already exist, or the script will throw an
Aws::IAM::Errors::NoSuchEntity error.
Example
require 'aws-sdk' iam = Aws::IAM::Client.new(region: 'us-east-1') server_certificate_name = "my-server-certificate" changed_server_certificate_name = "my-changed-server-certificate"
# Update a server certificate.
iam.update_server_certificate({
server_certificate_name: server_certificate_name,
new_server_certificate_name: changed_server_certificate_name
})
# Delete the server certificate.
iam.delete_server_certificate({
server_certificate_name: changed_server_certificate_name
})
# List information about any remaining server certificates.
list_server_certificates_response = iam.list_server_certificates
if list_server_certificates_response.server_certificate_metadata_list.count == 0
puts "No server certificates." else
list_server_certificates_response.server_certificate_metadata_list.each do | certificate_metadata|
puts "-" * certificate_metadata.server_certificate_name.length
puts "Name: #{certificate_metadata.server_certificate_name}"
get_server_certificate_response = iam.get_server_certificate({
server_certificate_name: "certificate_metadata.server_certificate_name"
})
puts "ID:
#{get_server_certificate_response.server_certificate.server_certificate_metadata.server_certificate_id}"
end end
Managing IAM Account Aliases
If you want the URL for your sign-in page to contain your company name or other friendly identifier instead of your AWS account ID, you can create an alias for your AWS account ID. If you create an AWS account alias, your sign-in page URL changes to incorporate the alias. For more information about IAM account aliases, see Your AWS Account ID and Its Alias .
In this example, you use the AWS SDK for Ruby with IAM to:
1. List AWS account aliases, using Aws::IAM::Client#list_account_aliases .
2. Create an account alias, using Aws::IAM::Client#create_account_alias .
3. Delete the account alias, using Aws::IAM::Client#delete_account_alias .
59
AWS SDK for Ruby Developer Guide
Lambda Examples
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
In the example code, change the my-account-alias string to something that will be unique across all
Amazon Web Services products.
Example
require 'aws-sdk' iam = Aws::IAM::Client.new(region: 'us-east-1') account_alias = "my-account-alias"
# List account aliases.
def list_aliases(iam)
list_account_aliases_response = iam.list_account_aliases
if list_account_aliases_response.account_aliases.count == 0
puts "No account aliases."
else
puts "Aliases:"
list_account_aliases_response.account_aliases.each do |account_alias|
puts account_alias
end
end end puts "Before creating account alias..." list_aliases(iam)
# Create an account alias.
puts "\nCreating account alias..." iam.create_account_alias({ account_alias: account_alias }) puts "\nAfter creating account alias..." list_aliases(iam)
# Delete the account alias.
puts "\nDeleting account alias..." iam.delete_account_alias({ account_alias: account_alias }) puts "\nAfter deleting account alias..." list_aliases(iam)
Lambda Examples
You can use the following examples to access AWS Lambda (Lambda) using the AWS SDK for Ruby. For more information about Lambda, see the Lambda documentation .
Examples
60
AWS SDK for Ruby Developer Guide
Displaying Information about All Lambda Functions
Topics
•
Displaying Information about All Lambda Functions (p. 61)
•
Creating a Lambda Function (p. 61)
•
Running a Lambda Function (p. 62)
•
Configuring a Lambda Function to Receive Notifications (p. 63)
Displaying Information about All Lambda Functions
The following example displays the name, ARN, and role of all of your Lambda functions in the uswest-2
region.
require 'aws-sdk' client = Aws::Lambda::Client.new(region: 'us-west-2') client.list_functions.each do |function|
puts 'Name: ' + function.function_name
puts 'ARN: ' + function.function_arn
puts 'Role: ' + function.role
Creating a Lambda Function
The following example creates the Lambda function my-notification-function
in the us-west-2
region using these values:
• Role ARN: my-resource-arn
. In most cases, you need to attach only the
AWSLambdaExecute
managed policy to the policy for this role.
• Function entry point: my-package.my-class
• Runtime: java8
• Zip file: my-zip-file.zip
• Bucket: my-notification-bucket
• Key: my-zip-file require 'aws-sdk' client = Aws::Lambda::Client.new(region: 'us-west-2') args = {} args[:role] = 'my-resource-arn' args[:function_name] = 'my-notification-function' args[:handler] = 'my-package.my-class'
# Also accepts nodejs, nodejs4.3, and python2.7
args[:runtime] = 'java8' code = {} code[:zip_file] = 'my-zip-file.zip' code[:s3_bucket] = 'my-notification-bucket' code[:s3_key] = 'my-zip-file' args[:code] = code client.create_function(args)
61
AWS SDK for Ruby Developer Guide
Running a Lambda Function
Running a Lambda Function
The following example rus the Lambda function
MyGetitemsFunction
in the us-west-2
region. This function returns a list of items from a database. The input JSON looks like:
{
"SortBy": "name|time",
"SortOrder": "ascending|descending",
"Number": 50
} where:
•
SortBy
is the criteria for sorting the results. Our examples uses time
, which means the returned items are sorted in the order in which they were added to the database.
•
SortOrder
is the order of sorting. Our example uses descending
, which means the most-recent item is last in the list.
•
Number
is the maximum number of items to retrieve (the default is 50). Our example uses
10
, which means get the 10 most-recent items.
The output JSON looks like:
{
"statusCode": 200|...,
"body": {
"result": "'success' or 'failure'",
"error": "Error message if 'failure', '' otherwise"
"data": [{"item1"}, ..., {"itemN"}]
}
} where:
• statusCode
is an HTTP status code,
200
means the call was successful.
• body
is the body of the returned JSON.
• result
is the result of the call, either success
or failure
.
• error
is an error message if result
is failure
, otherwise an empty string
• data
is the returned results if result
is success
, otherwise nil.
The first step is to load the modules we use:
• aws-sdk
loads the AWS SDK for Ruby module we use to invoke the Lambda function.
• json
loads the JSON module we use to marshall and unmarshall the request and response payloads.
• os
loads the OS module we use to ensure we can run our Ruby application on Microsoft Windows. If you are on a different operating system, you can remove those lines.
require 'aws-sdk' require 'json'
# To run on Windows: require 'os' if OS.windows?
Aws.use_bundled_cert!
62
AWS SDK for Ruby Developer Guide
Configuring a Lambda Function to Receive Notifications end
We then create the Lambda client we use to invoke the Lambda function.
client = Aws::Lambda::Client.new(region: 'us-west-2')
Next we create the hash for the request arguments and call
MyGetItemsFunction
.
req_payload = {:SortBy => 'time', :SortOrder => 'descending', :NumberToGet => 10} payload = JSON.generate(req_payload) resp = client.invoke({
function_name: 'MyGetItemsFunction',
invocation_type: 'RequestResponse',
log_type: 'None',
payload: payload
})
Finally we parse the response, and if are successful, we print out the items.
resp_payload = JSON.parse(resp.payload.string) # , symbolize_names: true)
# If the status code is 200, the call succeeded if resp_payload["statusCode"] == 200
# If the result is success, we got our items
if resp_payload["body"]["result"] == "success"
# Print out items
resp_payload["body"]["data"].each do |item|
puts item
end
end end
See the complete example on GitHub.
Configuring a Lambda Function to Receive
Notifications
The following example configures the Lambda function my-notification-function
in the us-west-2 region to accept notifications from the resource with the ARN my-resource-arn
.
require 'aws-sdk' client = Aws::Lambda::Client.new(region: 'us-west-2') args = {} args[:function_name] = 'my-notification-function' args[:statement_id] = 'lambda_s3_notification' args[:action] = 'lambda:InvokeFunction' args[:principal] = 's3.amazonaws.com' args[:source_arn] = 'my-resource-arn' client.add_permission{args]
63
AWS SDK for Ruby Developer Guide
Amazon Relational Database Service Examples
Amazon Relational Database Service Examples
You can use the following examples to access Amazon Relational Database Service (Amazon RDS) using the AWS SDK for Ruby. For more information about Amazon RDS, see the Amazon Relational Datbase
Service User Guide .
Note
Some of the following examples use methods that were introduced in the
2.2.18
version of the
Aws::RDS::Resource
class. To run those examples, you must use that version or a later version of the aws-sdk
gem.
Examples
Topics
•
Getting Information about All Instances (p. 64)
•
Getting Information about All Snapshots (p. 64)
•
Getting Information about All Clusters and Their Snapshots (p. 65)
•
Getting Information about All Security Groups (p. 65)
•
Getting Information about All Subnet Groups (p. 65)
•
Getting Information about All Parameter Groups (p. 66)
•
Creating a Snapshot of an Instance (p. 66)
•
Creating a Snapshot of a Cluster (p. 66)
Getting Information about All Instances
The following example lists the name (ID) and status of all of your Amazon RDS instances in the uswest-2
region.
require 'aws-sdk' rds = Aws::RDS::Resource.new(region: 'us-west-2') rds.db_instances.each do |i|
puts "Name (ID): #{i.id}"
puts "Status : #{i.db_instance_status}"
puts end
Getting Information about All Snapshots
The following example lists the names (IDs) and status of all of your Amazon RDS (instance) snapshots in the us-west-2
region.
require 'aws-sdk' rds = Aws::RDS::Resource.new(region: 'us-west-2') rds.db_snapshots.each do |s|
puts "Name (ID): #{s.snapshot_id}"
puts "Status: #{s.status}" end
64
AWS SDK for Ruby Developer Guide
Getting Information about All Clusters and Their Snapshots
Getting Information about All Clusters and Their
Snapshots
The following example lists the name (ID) and status of all of your Amazon RDS clusters and the name
(ID) and status of their snapshots in the us-west-2
region.
require 'aws-sdk' rds = Aws::RDS::Resource.new(region: 'us-west-2') rds.db_clusters.each do |c|
puts "Name (ID): #{c.id}"
puts "Status: #{c.status}"
c.snapshots.each do |s|
puts " Snapshot: #{s.snapshot_id}"
puts " Status: #{s.status}"
end end
Getting Information about All Security Groups
The following example lists the names of all of your Amazon RDS security groups in the us-west-2 region.
Note
Amazon RDS security groups are only applicable when you are using the Amazon EC2 classic platform. If you are using Amazon EC2 VPC, use VPC security groups. Both are shown in the example.
require 'aws-sdk' rds = Aws::RDS::Resource.new(region: 'us-west-2') rds.db_instances.each do |i|
# Show any security group IDs and descriptions
puts 'Security Groups:'
i.db_security_groups.each do |sg|
puts sg.db_security_group_name
puts ' ' + sg.db_security_group_description
puts
end
# Show any VPC security group IDs and their status
puts 'VPC Security Groups:'
i.vpc_security_groups.each do |vsg|
puts vsg.vpc_security_group_id
puts ' ' + vsg.status
puts
end end
Getting Information about All Subnet Groups
The following example lists the name and status of all of your Amazon RDS subnet groups in the uswest-2
region.
65
AWS SDK for Ruby Developer Guide
Getting Information about All Parameter Groups require 'aws-sdk' rds = Aws::RDS::Resource.new(region: 'us-west-2') rds.db_subnet_groups.each do |s|
puts s.name
puts ' ' + s.subnet_group_status
end
Getting Information about All Parameter Groups
The following example lists the names and descriptions of all of your Amazon RDS parameter groups in the us-west-2
region.
require 'aws-sdk' rds = Aws::RDS::Resource.new(region: 'us-west-2') rds.db_parameter_groups.each do |p|
puts p.db_parameter_group_name
puts ' ' + p.description
end
Creating a Snapshot of an Instance
The following example creates a snapshot for the Amazon RDS instance represented by instance_name in the us-west-2
region.
Note
If your instance is a member of a cluster, you can't create a snapshot of the instance, but instead must create a snapshot of the cluster (see
Creating a Snapshot of a Cluster (p. 66) ).
require 'aws-sdk' rds = Aws::RDS::Resource.new(region: 'us-west-2') instance = rds.db_instance(instance_name) date = Time.new
date_time = date.year.to_s + '-' + date.month.to_s + '-' + date.day.to_s + '-' +
date.hour.to_s + '-' + date.min.to_s
id = instance_name + '-' + date_time instance.create_snapshot({db_snapshot_identifier: id}) puts "Created snapshot #{id}"
Creating a Snapshot of a Cluster
The following example creates a snapshot for the Amazon RDS cluster represented by cluster_name in the us-west-2
region.
require 'aws-sdk' rds = Aws::RDS::Resource.new(region: 'us-west-2')
66
AWS SDK for Ruby Developer Guide
Amazon S3 Examples cluster = rds.db_cluster(cluster_name) date = Time.new
date_time = date.year.to_s + '-' + date.month.to_s + '-' + date.day.to_s + '-' +
date.hour.to_s + '-' + date.min.to_s
id = cluster_name + '-' + date_time cluster.create_snapshot({db_cluster_snapshot_identifier: id}) puts "Created cluster snapshot #{id}"
Amazon S3 Examples
You can use the following examples to access Amazon Simple Storage Service (Amazon S3) using the
AWS SDK for Ruby. For more information about Amazon S3, see the Amazon S3 documentation .
Examples
Topics
•
Getting Information about All Buckets (p. 67)
•
Getting Information about All Buckets in a Region (p. 68)
•
Creating and Using an Amazon S3 Bucket (p. 68)
•
Determining Whether a Bucket Exists (p. 72)
•
Getting Information about Bucket Items (p. 72)
•
Uploading an Item to a Bucket (p. 73)
•
Uploading an Item with Metadata to a Bucket (p. 73)
•
Downloading an Object from a Bucket into a File (p. 73)
•
Changing the Properties for a Bucket Item (p. 74)
•
Triggering a Notification When an Item is Added to a Bucket (p. 74)
•
Creating a Bucket LifeCycle Rule Configuration Template (p. 76)
•
Creating a Bucket Policy with Ruby (p. 78)
•
Configuring a Bucket for Cross-Origin Resource Sharing (CORS) (p. 81)
•
Managing Amazon S3 Bucket and Object Access Permissions (p. 84)
•
Using a Amazon S3 Bucket to Host a Website (p. 86)
Getting Information about All Buckets
The following example lists the names of up to 50 of your Amazon S3 buckets. Copy the code and save it as buckets.rb
. Notice that although the
Resource
object is created in the us-west-2
region, Amazon S3 returns buckets to which you have access, regardless of the region they are in.
require 'aws-sdk' region = 'us-west-2' s3 = Aws::S3::Resource.new(region: region) s3.buckets.limit(50).each do |b|
puts "#{b.name}" end
67
AWS SDK for Ruby Developer Guide
Getting Information about All Buckets in a Region
Note
When you specify a region, the buckets
method calls the
Client#list_buckets
method, which returns a list of all buckets owned by the authenticated sender of the request. See
Information about All Buckets in a Region (p. 68) to learn how to filter this list to get the
buckets only in a specific region.
Getting Information about All Buckets in a Region
The following example lists the names of the first 50 buckets for the us-west-2
region. If you don't specify a limit, Amazon S3 lists all buckets in us-west-2
.
require 'aws-sdk' region = 'us-west-2' s3 = Aws::S3::Resource.new(region: region) s3.buckets.limit(50).each do |b|
if s3.client.get_bucket_location(bucket: b.name).location_constraint == region
puts "#{b.name}"
end end
Note
If a bucket is not in the region in which you instantiated your
Resource
object, the SDK emits a warning message when you call get_bucket_location
. You can suppress this message by redirecting STDERR.
On Windows, append
2> nul
to the command.
On Linux or iOS, append
2> /dev/null
to the command.
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
.
Prerequisite Tasks
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 (p. 4)
.
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 (p. 5)
.
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
.
68
AWS SDK for Ruby Developer Guide
Creating and Using an Amazon S3 Bucket
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' 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)
69
AWS SDK for Ruby Developer Guide
Creating and Using an Amazon S3 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' require 'json'
70
AWS SDK for Ruby Developer Guide
Creating and Using an Amazon S3 Bucket 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'
71
AWS SDK for Ruby Developer Guide
Determining Whether a Bucket Exists s3 = Aws::S3::Resource.new(region: 'us-west-2') s3.create_bucket(bucket: 'my-bucket')
Determining Whether a Bucket Exists
There are two cases in which you would want to determine whether a bucket already exists. You perform these tests in lieu of receiving an exception if the condition fails:
• You want to determine whether a bucket with a specific name already exists among all buckets, even ones to which you do not have access. This test helps prevent you from trying to create a bucket with the name of an existing bucket, which causes an exception.
• You want to perform an operation, such as add an item to a bucket, only on a bucket to which you have access.
The following example sets bucket_exists
to true
if a bucket with the name my-bucket
already exists.
The region:
parameter to
Resource
has no effect on the result.
require 'aws-sdk' s3 = Aws::S3::Resource.new(region: 'us-west-2') bucket_exists = s3.bucket('my-bucket').exists?
The following example sets bucket_exists
to true
if the bucket with the name my-bucket
exists and you have access to the bucket. Again, the region
parameter to
Client
has no effect on the result.
require 'aws-sdk' bucket_exists = false client = Aws::S3::Client.new(region: 'us-west-2') begin
resp = client.head_bucket({bucket: bucket_name, use_accelerate_endpoint: false})
bucket_exists = true rescue end
Getting Information about Bucket Items
A presigned URL gives you access to the object identified in the URL, if the creator of the presigned URL has permissions to access that object. You can use a presigned URL to allow a user to click a link and see an item without having to make the item public.
The following example lists the names and presigned URLs of the first 50 items of the bucket my-bucket in the us-west-2
region. If a limit is not specified, Amazon S3 lists up to 1000 items.
require 'aws-sdk' s3 = Aws::S3::Resource.new(region: 'us-west-2') bucket = s3.bucket('my-bucket')
# Show only the first 50 items bucket.objects.limit(50).each do |item|
puts "Name: #{item.key}"
puts "URL: #{item.presigned_url(:get)}" end
72
AWS SDK for Ruby Developer Guide
Uploading an Item to a Bucket
Uploading an Item to a Bucket
The following example uploads the item (file)
C:file.txt
to the bucket my-bucket
in the us-west-2 region. Because
C:file.txt
is the fully qualified name of the file, the name of the item is set to the name of the file.
require 'aws-sdk' s3 = Aws::S3::Resource.new(region: 'us-west-2') file = 'C:\file.txt' bucket = 'my-bucket'
# Get just the file name name = File.basename(file)
# Create the object to upload obj = s3.bucket(bucket).object(name)
# Upload it obj.upload_file(file)
Uploading an Item with Metadata to a Bucket
The following example uploads the item (file)
C:file.txt
with the metadata key-value pair answer
and
42
to the bucket my-bucket
in the us-west-2
region. Because
C:file.txt
is the fully qualified name of the file, the name of the item is set to the file name.
require 'aws-sdk' s3 = Aws::S3::Resource.new(region: 'us-west-2') file = 'C:\file.txt' bucket = 'my-bucket'
# Get just the file name name = File.basename(file)
# Create the object to upload obj = s3.bucket(bucket).object(name)
# Metadata to add metadata = {"answer" => "42"}
# Upload it obj.upload_file(file, metadata: metadata)
Downloading an Object from a Bucket into a File
The following example gets the contents of the item my-item
from the bucket my-bucket
in the uswest-2
region, and saves it to the my-item.txt
file in the
./my-code
directory.
require 'aws-sdk' s3 = Aws::S3::Resource.new(region: 'us-west-2')
# Create the object to retrieve obj = s3.bucket('my-bucket').object('my-item')
73
AWS SDK for Ruby Developer Guide
Changing the Properties for a Bucket Item
# Get the item's content and save it to a file obj.get(response_target: './my-code/my-item.txt')
Changing the Properties for a Bucket Item
The following example adds public read-only access, sets server-side encryption to AES-256, and sets the storage class to Reduced Redundancy for the item my-item
in the bucket my-bucket
in the us-west-2 region.
require 'aws-sdk' args_list = {} args_list[:bucket] = 'my-bucket' args_list[:key] = 'my-item'
# Where we are getting the source to copy from args_list[:copy_source] = 'my-bucket/my-item'
# The acl can be any of:
# private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-ownerread, bucket-owner-full-control args_list[:acl] = 'public-read'
# The encryption can be any of:
# AES256, aws:kms args_list[:server_side_encryption] = 'AES256'
# The storage_class can be any of:
# STANDARD, REDUCED_REDUNDANCY, STANDARD_IA args_list[:storage_class] = 'REDUCED_REDUNDANCY' client = Aws::S3::Client.new(region: 'us-west-2') client.copy_object(args_list)
Triggering a Notification When an Item is Added to a
Bucket
You can trigger a notification when there is a change in the objects in a bucket. These changes include:
• When an object is added to the bucket
• When an object is removed from the bucket
• When an object stored with Reduced Redundancy is lost
You can configure the service to send a notification to:
• An Amazon SNS topic
• An Amazon SQS queue
• A Lambda function
To create a bucket notification
1.
2.
Set the bucket's Notification Configuration to point to the queue, topic, or function (p. 75)
.
74
AWS SDK for Ruby Developer Guide
Triggering a Notification When an Item is Added to a Bucket
After you do these steps, your application can respond to the information. For example, the Lambda topic Programming Model describes how to use the various programming languages that Lambda supports.
Enabling Amazon S3 to Send a Notification
Learn how to configure an Amazon Simple Notification Service topic or Amazon Simple Queue Service queue, or create a Lambda function so that Amazon S3 can send a notification to them.
•
Enabling a Resource to Publish to a Topic (p. 92)
•
Enabling a Resource to Publish to a Queue in Amazon SQS (p. 101)
•
Configuring a Lambda Function to Receive Notifications (p. 63)
Creating an Amazon S3 Bucket Notification
The following example enables the Amazon S3 bucket my-bucket
to send a notification to the following when an item is added to the bucket:
• The Amazon SNS topic with the ARN my-topic-arn
• The Amazon SQS queue with the ARN my-queue-arn
• The Lambda function with the ARN my-function-arn require 'aws-sdk' req = {} req[:bucket] = bucket_name events = ['s3:ObjectCreated:*'] notification_configuration = {}
# Add function lc = {} lc[:lambda_function_arn] = 'my-function-arn' lc[:events] = events lambda_configurations = [] lambda_configurations << lc notification_configuration[:lambda_function_configurations] = lambda_configurations
# Add queue qc = {} qc[:queue_arn] = 'my-topic-arn' qc[:events] = events queue_configurations = [] queue_configurations << qc notification_configuration[:queue_configurations] = queue_configurations
# Add topic tc = {} tc[:topic_arn] = 'my-topic-arn' tc[:events] = events topic_configurations = [] topic_configurations << tc
75
AWS SDK for Ruby Developer Guide
Creating a Bucket LifeCycle Rule Configuration Template notification_configuration[:topic_configurations] = topic_configurations req[:notification_configuration] = notification_configuration req[:use_accelerate_endpoint] = false s3 = Aws::S3::Client.new(region: 'us-west-2') s3.put_bucket_notification_configuration(req)
Creating a Bucket LifeCycle Rule Configuration
Template
If you have (or plan to create) a non-trivial number of objects and want to specify when to move them to long-term storage or delete them, you can save a lot of time by creating a template for the lifecycle rules and applying that template to all of your buckets.
The process includes these steps:
1. Manually modify the lifecycle settings on an existing bucket.
2. Save the rules.
3. Apply the rules to your other buckets.
Start with the following rule:
Run the following code to produce a JSON representation of that rule. Save the output as default.json
.
require 'aws-sdk'
76
AWS SDK for Ruby Developer Guide
Creating a Bucket LifeCycle Rule Configuration Template s3 = Aws::S3::Client.new(region: 'us-west-2') resp = s3.get_bucket_lifecycle_configuration(bucket: 'default') resp.rules.each do |rule|
rule.to_hash.to_json
end
The output should look like the following:
[{"expiration":
{"date":null,"days":425},"id":"default","prefix":"","status":"Enabled","transitions":
[{"date":null,"days":30,"storage_class":"STANDARD_IA"},
{"date":null,"days":60,"storage_class":"GLACIER"}],"noncurrent_version_transitions":
[],"noncurrent_version_expiration":null}]
Now that you have the JSON for a lifecycle rule, you can apply it to any other bucket using the following example, which takes the rule from default.json
and applies it to the bucket other_bucket
: require 'aws-sdk' require 'json' class Aws::S3::Types::LifecycleExpiration
def to_map
map = Hash.new
self.members.each { |m| map[m] = self[m] }
map
end
def to_json(*a)
to_map.to_json(*a)
end end class Aws::S3::Types::Transition
def to_map
map = Hash.new
self.members.each { |m| map[m] = self[m] }
map
end
def to_json(*a)
to_map.to_json(*a)
end end class Aws::S3::Types::LifecycleRule
def to_map
map = Hash.new
self.members.each { |m| map[m] = self[m] }
map
end
def to_json(*a)
to_map.to_json(*a)
end end
# Pull in contents as a string value = File.open('default.json', "rb").read
json_data = JSON.parse(value, opts={symbolize_names: true}) s3 = Aws::S3::Client.new(region: 'us-west-2')
77
AWS SDK for Ruby Developer Guide
Creating a Bucket Policy with Ruby s3.put_bucket_lifecycle_configuration(:bucket => 'other_bucket', :lifecycle_configuration
=> {:rules => json_data})
<admonition>
<title>Best Practice</title>
We recommend that you enable the AbortIncompleteMultipartUpload lifecycle rule on your Amazon S3 buckets.
This rule directs Amazon S3 to abort multipart uploads that don't complete within a specified number of days after being initiated. When the set time limit is exceeded, Amazon S3 aborts the upload and then deletes the incomplete upload data.
For more information, see Lifecycle Configuration for a Bucket with Versioning in the Amazon S3 User
Guide.
</admonition>
Creating a Bucket Policy with Ruby
This example demonstrates how to use the AWS SDK for Ruby to:
1. Create a bucket in Amazon Simple Storage Service (Amazon S3).
2. Define a bucket policy.
3. Add the policy to the bucket.
4. Change the policy.
5. Remove the policy from the bucket.
6. Delete the bucket.
For the complete code for this example, see
.
Prerequisite Tasks
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 (p. 4)
.
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 (p. 5)
.
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 or in the
AWS_ACCESS_KEY_ID
and
AWS_SECRET_ACCESS_KEY
environment variables on your local system.
Configure the SDK
To configure the SDK for this example, add a require
statement so you can use the classes and methods provided by the AWS SDK for Ruby for Amazon S3. Then create an Aws::S3::Client object in the AWS
Region where you want to create the bucket. This code creates the
Aws::S3::Client
object in the uswest-2
region.
require 'aws-sdk' s3 = Aws::S3::Client.new(region: "us-west-2")
78
AWS SDK for Ruby Developer Guide
Creating a Bucket Policy with Ruby
Create a Bucket
Call the create_bucket method, specifying the bucket's name. This code uses a variable named bucket
to represent the bucket's name. Substitute example-bucket-name
for your bucket's name.
Note
Bucket names must be unique across Amazon S3—not just unique to your AWS account.
If you already have a bucket you want to use, you don't have to call create_bucket
.
bucket = "example-bucket-name" s3.create_bucket(bucket: bucket)
Define a Bucket Policy
Declare a Ruby hash that represents the policy. Then call the to_json
method on the hash to convert it to a JSON object. This code uses a variable named policy
that contains the policy definition. This policy allows the specified user to have full control over the example-bucket-name
(represented by
#{bucket}
).
Substitute arn:aws:iam::111122223333:user/Alice
with the Amazon Resource Name (ARN) of the AWS
Identity and Access Management (IAM) user you want to use.
policy = {
"Version" => "2012-10-17",
"Statement" => [
{
"Effect" => "Allow",
"Principal" => {
"AWS" => [
"arn:aws:iam::111122223333:user/Alice"
]
},
"Action" => "s3:*",
"Resource" => [
"arn:aws:s3:::#{bucket}"
]
}
]
}.to_json
For examples of the types of policies you can define, see Bucket Policy Examples in the Amazon S3
Developer Guide.
Add the Policy to the Bucket
Call the put_bucket_policy method, specifying the name of the bucket and the policy definition.
s3.put_bucket_policy(
bucket: bucket,
policy: policy
)
Change the Policy
You can call the put_bucket_policy
method again with a complete replacement policy. However, you can also make incremental updates to an existing policy, which can reduce the amount of code you need to write. To do this, retrieve the current policy by calling the get_bucket_policy method. Next, parse the JSON object that is returned into a Ruby hash. Then make your incremental changes to the
79
AWS SDK for Ruby Developer Guide
Creating a Bucket Policy with Ruby policy. For example, this code changes the ARN of the IAM entity. After you make your changes, call the put_bucket_policy
method again. Be sure to call the to_json
method on the hash to convert it back to a
JSON object before applying the changed policy to the bucket.
policy_string = s3.get_bucket_policy(bucket: bucket).policy.read
policy_json = JSON.parse(policy_string) policy_json["Statement"][0]["Principal"]["AWS"] = "arn:aws:iam::111122223333:root" s3.put_bucket_policy(
bucket: bucket,
policy: policy_json.to_json
)
Clean Up
To remove the policy from the bucket, call the delete_bucket_policy method, specifying the name of the bucket.
To delete the bucket, call the delete_bucket method, specifying the name of the bucket.
s3.delete_bucket_policy(bucket: bucket) s3.delete_bucket(bucket: bucket)
Complete Example
Here is the complete code for this example.
require 'aws-sdk' s3 = Aws::S3::Client.new(region: "us-west-2") bucket = "example-bucket-name" s3.create_bucket(bucket: bucket) policy = {
"Version" => "2012-10-17",
"Statement" => [
{
"Effect" => "Allow",
"Principal" => {
"AWS" => [
"arn:aws:iam::111122223333:user/Alice"
]
},
"Action" => "s3:*",
"Resource" => [
"arn:aws:s3:::#{bucket}"
]
}
]
}.to_json
s3.put_bucket_policy(
bucket: bucket,
policy: policy
) policy_string = s3.get_bucket_policy(bucket: bucket).policy.read
policy_json = JSON.parse(policy_string)
80
AWS SDK for Ruby Developer Guide
Configuring a Bucket for Cross-
Origin Resource Sharing (CORS) policy_json["Statement"][0]["Principal"]["AWS"] = "arn:aws:iam::111122223333:root" s3.put_bucket_policy(
bucket: bucket,
policy: policy_json.to_json
) s3.delete_bucket_policy(bucket: bucket) s3.delete_bucket(bucket: bucket)
Configuring a Bucket for Cross-Origin Resource
Sharing (CORS)
This example demonstrates how to use the AWS SDK for Ruby to:
1. Configure CORS settings for an Amazon S3 bucket.
2. Get the CORS settings for a bucket.
For more information about CORS support in Amazon S3, see Cross-Origin Resource Sharing (CORS) in the Amazon S3 Developer Guide.
For the complete code for this example, see
.
Prerequisite Tasks
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 (p. 4)
.
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 (p. 5)
.
3. Create an Amazon S3 bucket or identify an existing bucket in your AWS account.
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 the profile is named david
.
• Your bucket is named doc-sample-bucket
.
Configure the SDK
For this example, add a require
statement so that you can use the classes and methods provided by the
AWS SDK for Ruby for Amazon S3. 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. An additional variable is also declared for the bucket used in this example.
require 'aws-sdk' profile_name = 'david' region = 'us-east-1' bucket = 'doc-sample-bucket'
81
AWS SDK for Ruby Developer Guide
Configuring a Bucket for Cross-
Origin Resource Sharing (CORS)
# S3 - Configuring an S3 Bucket
# Create a S3 client s3 = Aws::S3::Client.new(profile: profile_name, region:region)
Configure CORS for a Bucket
Call the put_bucket_cors method, providing the name of the bucket and the CORS configuration settings.
s3.put_bucket_cors(
bucket: bucket,
cors_configuration: cors_configuration
)
For the CORS configuration settings, declare an Aws::S3::Types::CORSConfiguration hash. Specify things such as the HTTP methods that the specified origins are allowed to execute ( allowed_methods
), the origins you want customers to be able to access the bucket from ( allowed_origins
), and the headers in the response you want customers to be able to access from their applications (for example, from a
JavaScript
XMLHttpRequest
object, shown here in expose_headers
).
cors_configuration = {
cors_rules: [
{
allowed_methods: allowed_methods,
allowed_origins: ["*"],
expose_headers: ["ExposeHeader"],
},
]
}
For the HTTP methods that the specified origins are allowed to execute, you could specify them inline or, as shown here, you could get them from the user at the command line.
allowed_methods = []
ARGV.each do |arg|
case arg.upcase
when "POST"
allowed_methods << "POST"
when "GET"
allowed_methods << "GET"
when "PUT"
allowed_methods << "PUT"
when "PATCH"
allowed_methods << "PATCH"
when "DELETE"
allowed_methods << "DELETE"
when "HEAD"
allowed_methods << "HEAD"
else
puts "#{arg} is not a valid HTTP method"
end end
For example, assuming the code file is named doc_sample_code_s3_bucket_cors.rb
, and you want to allow the specified origins to execute only GET and POST methods, here is how the user could run the code from the command line.
ruby doc_sample_code_s3_bucket_cors.rb get post
82
AWS SDK for Ruby Developer Guide
Configuring a Bucket for Cross-
Origin Resource Sharing (CORS)
Get the CORS Settings for a Bucket
Call the get_bucket_cors method, providing the name of the bucket. The get_bucket_cors
method returns an Aws::S3::Types::GetBucketCorsOutput object. This object's cors_rules
attribute returns an array of Aws::S3::Types::CORSRule objects, which represent the bucket's CORS settings.
resp = s3.get_bucket_cors(bucket: bucket) puts resp.cors_rules
Complete Example
Here is the complete code for this example.
require 'aws-sdk' profile_name = 'david' region = 'us-east-1' bucket = 'doc-sample-bucket'
# S3 - Configuring an S3 Bucket
# Create a S3 client s3 = Aws::S3::Client.new(profile: profile_name, region:region)
# Setting a Bucket CORS Configuration
# Create array of allowed methods parameter based on command line parameters allowed_methods = []
ARGV.each do |arg|
case arg.upcase
when "POST"
allowed_methods << "POST"
when "GET"
allowed_methods << "GET"
when "PUT"
allowed_methods << "PUT"
when "PATCH"
allowed_methods << "PATCH"
when "DELETE"
allowed_methods << "DELETE"
when "HEAD"
allowed_methods << "HEAD"
else
puts "#{arg} is not a valid HTTP method"
end end
# Create CORS configuration hash cors_configuration = {
cors_rules: [
{
allowed_methods: allowed_methods,
allowed_origins: ["*"],
expose_headers: ["ExposeHeader"],
},
]
}
# Set the new CORS configuration on the selected bucket s3.put_bucket_cors(
bucket: bucket,
cors_configuration: cors_configuration
83
AWS SDK for Ruby Developer Guide
Managing Amazon S3 Bucket and Object Access Permissions
)
# Retrieving a Bucket CORS Configuration resp = s3.get_bucket_cors(bucket: bucket) puts resp.cors_rules
# To run the example, type the following at the command line including one or more HTTP
methods as shown
# ruby doc_sample_code_s3_bucket_cors.rb get post
Managing Amazon S3 Bucket and Object Access
Permissions
This example demonstrates how to use the AWS SDK for Ruby to:
1. Set a predefined grant (also known as a canned ACL) for a bucket in Amazon S3.
2. Add an object to the bucket.
3. Set a canned ACL for an object in the bucket.
4. Get the bucket's current ACL.
For the complete code for this example, see
.
Prerequisite Tasks
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 (p. 4)
.
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 (p. 5)
.
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 or in the
AWS_ACCESS_KEY_ID
and
AWS_SECRET_ACCESS_KEY
environment variables on your local system.
Configure the SDK
For this example, add a require
statement so that you can use the classes and methods provided by the
AWS SDK for Ruby for Amazon S3. Then create an Aws::S3::Client object in the AWS Region where you want to create the bucket. This code creates the
Aws::S3::Client
object in the us-west-2
region. This code also declares a variable representing the bucket.
require 'aws-sdk'
# Create a S3 client client = Aws::S3::Client.new(region: 'us-west-2')
Set a Canned ACL for a Bucket
Call the put_bucket_acl method, specifying the names of the canned ACL and the bucket. This code sets the public-read
canned ACL on the bucket, which enables full control for the bucket's owner and readonly access for everyone else.
84
AWS SDK for Ruby Developer Guide
Managing Amazon S3 Bucket and Object Access Permissions client.put_bucket_acl({
acl: "public-read",
bucket: bucket,
})
For more information about canned ACLs, see Canned ACL in Access Control List (ACL) Overview in the
Amazon S3 Developer Guide.
To confirm this setting, call the Ruby
Net::HTTP.get
method to attempt to get the bucket's content.
bucket_path = "http://#{bucket}.s3-us-west-2.amazonaws.com/" resp = Net::HTTP.get(URI(bucket_path)) puts "Content of unsigned request to #{bucket_path}:\n\n#{resp}\n\n"
Upload an Object to a Bucket
Call the put_object method, specifying the names of the bucket and object and the object's content. This code declares a variable representing the object.
object_key = "my-key"
# Put an object in the public bucket client.put_object({
bucket: bucket,
key: object_key,
body: 'Hello World',
})
Set a Canned ACL for an Object
By default, you can't get the contents of the object in the bucket. To confirm this behavior, call the Ruby
Net::HTTP.get
method to attempt to get the object's content.
object_path = "http://#{bucket}.s3-us-west-2.amazonaws.com/#{object_key}" resp = Net::HTTP.get(URI(object_path)) puts "Content of unsigned request to #{object_path}:\n\n#{resp}\n\n"
To change this behavior, call the put_object_acl method, specifying the names of the canned ACL, bucket, and object. This code sets the public-read
canned ACL on the object, which enables full control for the object's owner and read-only access for everyone else. After the call, try to get the object's content again.
client.put_object_acl({
acl: "public-read",
bucket: bucket,
key: object_key,
}) object_path = "http://#{bucket}.s3-us-west-2.amazonaws.com/#{object_key}" puts "Now I can access object (#{object_key}) :\n#{Net::HTTP.get(URI(object_path))}\n\n"
Get a Bucket's Current ACL
Call the get_bucket_acl method, specifying the name of the bucket. The get_bucket_acl
method returns an instance of the Aws::S3::Types::GetBucketAclOutput class. Use the grants
attribute of the
GetBucketAclOutput
class to list the bucket's current ACL.
85
AWS SDK for Ruby Developer Guide
Using a Amazon S3 Bucket to Host a Website resp = client.get_bucket_acl(bucket: bucket) puts resp.grants
Complete Example
Here is the complete code for this example.
require 'aws-sdk'
# Create a S3 client client = Aws::S3::Client.new(region: 'us-west-2') bucket = 'my-bucket'
# Sets a bucket to public-read client.put_bucket_acl({
acl: "public-read",
bucket: bucket,
}) object_key = "my-key"
# Put an object in the public bucket client.put_object({
bucket: bucket,
key: object_key,
body: 'Hello World',
})
# Accessing an object in the bucket with unauthorize request bucket_path = "http://#{bucket}.s3-us-west-2.amazonaws.com/" resp = Net::HTTP.get(URI(bucket_path)) puts "Content of unsigned request to #{bucket_path}:\n\n#{resp}\n\n"
# However, accessing the object is denied since object Acl is not public-read object_path = "http://#{bucket}.s3-us-west-2.amazonaws.com/#{object_key}" resp = Net::HTTP.get(URI(object_path)) puts "Content of unsigned request to #{object_path}:\n\n#{resp}\n\n"
# Setting the object to public-read client.put_object_acl({
acl: "public-read",
bucket: bucket,
key: object_key,
}) object_path = "http://#{bucket}.s3-us-west-2.amazonaws.com/#{object_key}" puts "Now I can access object (#{object_key}) :\n#{Net::HTTP.get(URI(object_path))}\n\n"
# Setting bucket to private again client.put_bucket_acl({
bucket: bucket,
acl: 'private',
})
# Get current bucket Acl resp = client.get_bucket_acl(bucket: bucket) puts resp.grants
resp = Net::HTTP.get(URI(bucket_path)) puts "Content of unsigned request to #{bucket_path}:\n\n#{resp}\n\n"
Using a Amazon S3 Bucket to Host a Website
This example demonstrates how to use the AWS SDK for Ruby to:
86
AWS SDK for Ruby Developer Guide
Using a Amazon S3 Bucket to Host a Website
1. Create an Amazon S3 bucket.
2. Get the bucket website's configuration.
3. Add objects to the bucket.
4. Set the bucket website's configuration.
5. Access the bucket website's documents.
6. Delete the bucket website.
7. Delete the bucket.
For information about bucket website hosting, see Configure a Bucket for Website Hosting in the Amazon
S3 Developer Guide.
For the complete code for this example, see
.
Prerequisite Tasks
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 (p. 4)
.
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 (p. 5)
.
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 or in the
AWS_ACCESS_KEY_ID
and
AWS_SECRET_ACCESS_KEY
environment variables on your local system.
Configure the SDK
For this example, add a require
statement so that you can use the classes and methods provided by the
AWS SDK for Ruby for Amazon S3. 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-2
region.
An additional variable is also declared for the bucket used in this example. To help ensure the bucket name is unique across all AWS accounts, an additional require
statement is added, and the
SecureRandom
module's uuid
method is called to generate a unique identifier. This identifier is inserted into the name of the bucket to be created later in this sample.
require 'aws-sdk'
# Using Random UUIDs to Avoid Collisions when Testing require 'securerandom' bucket = "example-test-bucket-#{SecureRandom.uuid}"
# Setup s3 = Aws::S3::Client.new(region: "us-west-2")
Create a Bucket
Call the create_bucket method, supplying the name of the bucket to create.
s3.create_bucket(bucket: bucket)
87
AWS SDK for Ruby Developer Guide
Using a Amazon S3 Bucket to Host a Website
Get a Bucket Website's Configuration
Call the get_bucket_website method, supplying the name of the bucket. By default, a bucket is not configured as a website. To confirm this behavior, call the get_bucket_website
method. This returns an error, because there is no website configuration for the bucket.
begin
s3.get_bucket_website(bucket: bucket) rescue Aws::S3::Errors::NoSuchWebsiteConfiguration
puts "No bucket website configuration present." end
Add an Object to a Bucket
Call the put_object method, supplying the name of the bucket and object, the object's contents, and the object's access permissions set. This example adds two webpages to the bucket.
s3.put_object(
bucket: bucket,
key: "index.html",
body: "Hello, Amazon S3!",
acl: "public-read"
) s3.put_object(
bucket: bucket,
key: "error.html",
body: "Page not found!",
acl: "public-read"
)
Set a Bucket Website's Configuration
Call the put_bucket_website method, supplying the name of the bucket and the website configuration.
For the website configuration, use an Aws::S3::Types::WebsiteConfiguration hash, supplying the website's index and error webpages.
s3.put_bucket_website(
bucket: bucket,
website_configuration: {
index_document: {
suffix: "index.html"
},
error_document: {
key: "error.html"
}
}
)
Access a Bucket Website's Documents
Call the Ruby
Net::HTTP.get
method, supplying the address to the document in the bucket website.
index_path = "http://#{bucket}.s3-website-us-west-2.amazonaws.com/" error_path = "http://#{bucket}.s3-website-us-west-2.amazonaws.com/nonexistant.html" puts "Index Page Contents:\n#{Net::HTTP.get(URI(index_path))}\n\n"
88
AWS SDK for Ruby Developer Guide
Using a Amazon S3 Bucket to Host a Website puts "Error Page Contents:\n#{Net::HTTP.get(URI(error_path))}\n\n"
Delete a Bucket Website
Call the delete_bucket_website method, supplying the name of the bucket.
s3.delete_bucket_website(bucket: bucket)
Delete a Bucket
Call the bucket method of an Aws::S3::Resource object, supplying the name of the bucket. This returns an
Aws::S3::Bucket object. Then call the
Aws::S3::Bucket
object's delete method.
b = Aws::S3::Resource.new(region: "us-west-2").bucket(bucket) b.delete! # Recursively deletes objects as well.
Complete Example
Here is the complete code for this example.
require 'aws-sdk'
# Using Random UUIDs to Avoid Collisions when Testing require 'securerandom' bucket = "example-test-bucket-#{SecureRandom.uuid}"
# Setup s3 = Aws::S3::Client.new(region: "us-west-2") s3.create_bucket(bucket: bucket)
# When Bucket Has No Website Configuration begin
s3.get_bucket_website(bucket: bucket) rescue Aws::S3::Errors::NoSuchWebsiteConfiguration
puts "No bucket website configuration present." end
# Adding Simple Pages & Website Configuration s3.put_object(
bucket: bucket,
key: "index.html",
body: "Hello, Amazon S3!",
acl: "public-read"
) s3.put_object(
bucket: bucket,
key: "error.html",
body: "Page not found!",
acl: "public-read"
) s3.put_bucket_website(
bucket: bucket,
website_configuration: {
index_document: {
suffix: "index.html"
},
error_document: {
key: "error.html"
89
AWS SDK for Ruby Developer Guide
Amazon SNS Examples
}
}
)
# Accessing as a Website index_path = "http://#{bucket}.s3-website-us-west-2.amazonaws.com/" error_path = "http://#{bucket}.s3-website-us-west-2.amazonaws.com/nonexistant.html" puts "Index Page Contents:\n#{Net::HTTP.get(URI(index_path))}\n\n" puts "Error Page Contents:\n#{Net::HTTP.get(URI(error_path))}\n\n"
# Removing Website Configuration s3.delete_bucket_website(bucket: bucket)
# Cleanup b = Aws::S3::Resource.new(region: "us-west-2").bucket(bucket) b.delete! # Recursively deletes objects as well.
Amazon SNS Examples
You can use the following examples to access Amazon Simple Notification Service (Amazon SNS) using the AWS SDK for Ruby. For more information about Amazon SNS, see the Amazon SNS documentation .
Examples
Topics
•
Getting Information about All Topics (p. 90)
•
•
Getting Information about All Subscriptions in a Topic (p. 91)
•
Creating a Subscription in a Topic (p. 91)
•
Sending a Message to All Topic Subscribers (p. 91)
•
Enabling a Resource to Publish to a Topic (p. 92)
Getting Information about All Topics
The following example lists the ARNs of your SNS topics in the us-west-2
region.
require 'aws-sdk' sns = Aws::SNS::Resource.new(region: 'us-west-2') sns.topics.each do |topic|
puts topic.arn
end
Creating a Topic
The following example creates the topic
MyGroovyTopic
in the us-west-2
region and displays the resulting topic ARN.
require 'aws-sdk'
90
AWS SDK for Ruby Developer Guide
Getting Information about All Subscriptions in a Topic sns = Aws::SNS::Resource.new(region: 'us-west-2') topic = sns.create_topic(name: 'MyGroovyTopic') puts topic.arn
Getting Information about All Subscriptions in a
Topic
The following example lists the email addresses of the SNS subscriptions for the topic with the ARN arn:aws:sns:us-west-2:123456789:MyGroovyTopic
in the us-west-2
region.
require 'aws-sdk' sns = Aws::SNS::Resource.new(region: 'us-west-2') topic = sns.topic('arn:aws:sns:us-west-2:123456789:MyGroovyTopic') topic.subscriptions.each do |s|
puts s.attributes['Endpoint'] end
Creating a Subscription in a Topic
The following example creates a subscription for the topic with the ARN arn:aws:sns:uswest-2:123456789:MyGroovyTopic
for a user who has the email address
in the us-west-2
region, and displays the resulting ARN. Initially the ARN value is pending confirmation.
When the user confirms their email address, this value becomes a true ARN.
require 'aws-sdk' sns = Aws::SNS::Resource.new(region: 'us-west-2') topic = sns.topic('arn:aws:sns:us-west-2:123456789:MyGroovyTopic') sub = topic.subscribe({
protocol: 'email',
endpoint: '[email protected]'
}) puts sub.arn
Sending a Message to All Topic Subscribers
The following example sends the message "Hello!" to all subscribers to the topic with the ARN arn:aws:sns:us-west-2:123456789:MyGroovyTopic
.
require 'aws-sdk' sns = Aws::SNS::Resource.new(region: 'us-west-2') topic = sns.topic('arn:aws:sns:us-west-2:123456789:MyGroovyTopic') topic.publish({
message: 'Hello!'
})
91
AWS SDK for Ruby Developer Guide
Enabling a Resource to Publish to a Topic
Enabling a Resource to Publish to a Topic
The following example enables the resource with the ARN my-resource-arn
to publish to the topic with the
ARN my-topic-arn
in the us-west-2
region.
require 'aws-sdk' sns = Aws::SNS::Resource.new(region: 'us-west-2') policy = '{
"Version":"2008-10-17",
"Id":"__default_policy_ID",
"Statement":[{
"Sid":"__default_statement_ID",
"Effect":"Allow",
"Principal":{
"AWS":"*"
},
"Action":["SNS:Publish"],
"Resource":"' + my-topic-arn + '",
"Condition":{
"ArnEquals":{
"AWS:SourceArn":"' + my-resource-arn + '"}
}
}]
}' topic.set_attributes({
attribute_name: "Policy",
attribute_value: policy
})
Amazon SQS Examples
You can use the following examples to access Amazon Simple Queue Service (Amazon SQS) using the
AWS SDK for Ruby. For more information about Amazon SQS, see the Amazon SQS documentation .
Examples
Topics
•
Getting Information about All Queues in Amazon SQS (p. 93)
•
Creating a Queue in Amazon SQS (p. 93)
•
Working with Queues in Amazon SQS (p. 93)
•
Sending Messages in Amazon SQS (p. 94)
•
Sending and Receiving Messages in Amazon SQS (p. 95)
•
Receiving Messages in Amazon SQS (p. 96)
•
Receiving Messages Using Long Polling in Amazon SQS (p. 97)
•
Enabling Long Polling in Amazon SQS (p. 97)
•
Receiving Messages Using the QueuePoller Class in Amazon SQS (p. 99)
•
Redirecting Dead Letters in Amazon SQS (p. 100)
•
Deleting a Queue in Amazon SQS (p. 100)
•
Enabling a Resource to Publish to a Queue in Amazon SQS (p. 101)
•
Working with a Dead Letter Queue in Amazon SQS (p. 101)
•
Specifying the Message Visibility Timeout in Amazon SQS (p. 103)
92
AWS SDK for Ruby Developer Guide
Getting Information about All Queues in Amazon SQS
Getting Information about All Queues in Amazon
SQS
The following example lists the URLs, ARNs, messages available, and messages in flight of your Amazon
SQS queues in the us-west-2
region.
require 'aws-sdk' sqs = Aws::SQS::Client.new(region: 'us-west-2') queues = sqs.list_queues
queues.queue_urls.each do |url|
puts 'URL: ' + url
# Get ARN, messages available, and messages in flight for queue
req = sqs.get_queue_attributes(
{
queue_url: url, attribute_names:
[
'QueueArn',
'ApproximateNumberOfMessages',
'ApproximateNumberOfMessagesNotVisible'
]
}
)
arn = req.attributes['QueueArn']
msgs_available = req.attributes['ApproximateNumberOfMessages']
msgs_in_flight = req.attributes['ApproximateNumberOfMessagesNotVisible']
puts 'ARN: ' + arn
puts 'Messages available: ' + msgs_available
puts 'Messages in flight: ' + msgs_in_flight
puts end
Creating a Queue in Amazon SQS
The following example creates the Amazon SQS queue
MyGroovyQueue
in the us-west-2
region and displays its URL.
require 'aws-sdk' sqs = Aws::SQS::Client.new(region: 'us-west-2') queue = sqs.create_queue(queue_name: 'MyGroovyQueue') puts queue.queue_url
Working with Queues in Amazon SQS
Amazon SQS provides highly scalable hosted queues for storing messages as they travel between applications or microservices. To learn more about queues, see How Amazon SQS Queues Work .
In this example, you use the AWS SDK for Ruby with Amazon SQS to:
1. Get a list of your queues by using Aws::SQS::Client#list_queues .
93
AWS SDK for Ruby Developer Guide
Sending Messages in Amazon SQS
2. Create a queue by using Aws::SQS::Client#create_queue .
3. Get the queue's URL by using Aws::SQS::Client#get_queue_url .
4. Delete the queue by using Aws::SQS::Client#delete_queue .
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
Example
require 'aws-sdk' sqs = Aws::SQS::Client.new(region: 'us-east-1')
# Get a list of your queues.
sqs.list_queues.queue_urls.each do |queue_url|
puts queue_url end
# Create a queue.
queue_name = "my-queue" begin
sqs.create_queue({
queue_name: queue_name,
attributes: {
"DelaySeconds" => "60", # Delay message delivery for 1 minute (60 seconds).
"MessageRetentionPeriod" => "86400" # Delete message after 1 day (24 hours * 60
minutes * 60 seconds).
}
}) rescue Aws::SQS::Errors::QueueDeletedRecently
puts "A queue with the name '#{queue_name}' was recently deleted. Wait at least 60
seconds and try again."
exit(false) end
# Get the queue's URL.
queue_url = sqs.get_queue_url(queue_name: queue_name).queue_url
puts queue_url
# Delete the queue.
sqs.delete_queue(queue_url: queue_url)
Sending Messages in Amazon SQS
The following example sends the message "Hello world" through the Amazon SQS queue with the URL
URL
in the us-west-2
region.
require 'aws-sdk' sqs = Aws::SQS::Client.new(region: 'us-west-2')
94
AWS SDK for Ruby Developer Guide
Sending and Receiving Messages in Amazon SQS sqs.send_message(queue_url: URL, message_body: 'Hello world')
The following example sends the messages "Hello world" and "How is the weather?" through the Amazon
SQS queue with the URL
URL
in the us-west-2
region.
require 'aws-sdk' sqs = Aws::SQS::Client.new(region: 'us-west-2') resp = sqs.send_message_batch({
queue_url: URL,
entries: [
{
id: 'msg1',
message_body: 'Hello world'
},
{
id: 'msg2',
message_body: 'How is the weather?'
}
],
})
Sending and Receiving Messages in Amazon SQS
After you create a queue in Amazon SQS, you can send a message to it and then consume it. To learn more, see Tutorial: Sending a Message to an Amazon SQS Queue and Tutorial: Receiving and Deleting a
Message from an Amazon SQS Queue .
In this example, you use the AWS SDK for Ruby with Amazon SQS to:
1. Send a message to a queue by using Aws::SQS::Client#send_message .
2. Receive the message in the queue by using Aws::SQS::Client#receive_message .
3. Display information about the message.
4. Delete the message from the queue by using Aws::SQS::Client#delete_message .
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
You also need to create the queue my-queue, which you can do in the Amazon SQS console.
Example
require 'aws-sdk' sqs = Aws::SQS::Client.new(region: 'us-east-1')
# Send a message to a queue.
queue_name = "my-queue" begin
queue_url = sqs.get_queue_url(queue_name: queue_name).queue_url
95
AWS SDK for Ruby Developer Guide
Receiving Messages in Amazon SQS
# Create a message with three custom attributes: Title, Author, and WeeksOn.
send_message_result = sqs.send_message({
queue_url: queue_url,
message_body: "Information about current NY Times fiction bestseller for week of
2016-12-11.",
message_attributes: {
"Title" => {
string_value: "The Whistler",
data_type: "String"
},
"Author" => {
string_value: "John Grisham",
data_type: "String"
},
"WeeksOn" => {
string_value: "6",
data_type: "Number"
}
}
}) rescue Aws::SQS::Errors::NonExistentQueue
puts "A queue named '#{queue_name}' does not exist."
exit(false) end puts send_message_result.message_id
# Receive the message in the queue.
receive_message_result = sqs.receive_message({
queue_url: queue_url,
message_attribute_names: ["All"], # Receive all custom attributes.
max_number_of_messages: 1, # Receive at most one message.
wait_time_seconds: 0 # Do not wait to check for the message.
})
# Display information about the message.
# Display the message's body and each custom attribute value.
receive_message_result.messages.each do |message|
puts message.body
puts "Title: #{message.message_attributes["Title"]["string_value"]}"
puts "Author: #{message.message_attributes["Author"]["string_value"]}"
puts "WeeksOn: #{message.message_attributes["WeeksOn"]["string_value"]}"
# Delete the message from the queue.
sqs.delete_message({
queue_url: queue_url,
receipt_handle: message.receipt_handle
}) end
Receiving Messages in Amazon SQS
The following example displays the body of up to 10 messages in the Amazon SQS queue with the URL
URL
in the us-west-2
region.
Note
receive_message
does not guarantee to get all messages (see Properties of Distributed Queues ), and by default does not delete the message.
require 'aws-sdk' sqs = Aws::SQS::Client.new(region: 'us-west-2')
96
AWS SDK for Ruby Developer Guide
Receiving Messages Using Long Polling in Amazon SQS resp = sqs.receive_message(queue_url: URL, max_number_of_messages: 10) resp.messages.each do |m|
puts m.body
end
Receiving Messages Using Long Polling in Amazon
SQS
The following example waits up to 10 seconds to display the bodies of up to 10 messages in the Amazon
SQS queue with the URL
URL
in the us-west-2
region.
If you do not specify a wait time, the default value is 0 (Amazon SQS does not wait).
require 'aws-sdk' sqs = Aws::SQS::Client.new(region: 'us-west-2') resp = sqs.receive_message(queue_url: URL, max_number_of_messages: 10, wait_time_seconds:
10) resp.messages.each do |m|
puts m.body
end
Enabling Long Polling in Amazon SQS
Long polling helps lower your cost of using Amazon SQS by reducing the number of empty responses and eliminating false empty responses. For more information about long polling, see Amazon SQS Long
Polling .
In this example, you use the AWS SDK for Ruby with Amazon SQS to:
1. Create a queue and set it for long polling by using Aws::SQS::Client#create_queue .
2. Set long polling for an existing queue by using Aws::SQS::Client#set_queue_attributes .
3. Set long polling when receiving messages for a queue by using Aws::SQS::Client#receive_message .
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
You also need to create the queues existing-queue and receive-queue, which you can do in the Amazon
SQS console.
Example
require 'aws-sdk' sqs = Aws::SQS::Client.new(region: 'us-east-1')
97
AWS SDK for Ruby Developer Guide
Enabling Long Polling in Amazon SQS
# Create a queue and set it for long polling.
new_queue_name = "new-queue" create_queue_result = sqs.create_queue({
queue_name: new_queue_name,
attributes: {
"ReceiveMessageWaitTimeSeconds" => "20" # Wait 20 seconds to receive messages.
},
}) puts create_queue_result.queue_url
# Set long polling for an existing queue.
begin
existing_queue_name = "existing-queue"
existing_queue_url = sqs.get_queue_url(queue_name: existing_queue_name).queue_url
sqs.set_queue_attributes({
queue_url: existing_queue_url,
attributes: {
"ReceiveMessageWaitTimeSeconds" => "20" # Wait 20 seconds to receive messages.
},
}) rescue Aws::SQS::Errors::NonExistentQueue
puts "Cannot set long polling for a queue named '#{existing_queue_name}', as it does not
exist." end
# Set long polling when receiving messages for a queue.
# 1. Using receive_message.
begin
receive_queue_name = "receive-queue"
receive_queue_url = sqs.get_queue_url(queue_name: receive_queue_name).queue_url
puts "Begin receipt of any messages using receive_message..."
receive_message_result = sqs.receive_message({
queue_url: receive_queue_url,
attribute_names: ["All"], # Receive all available built-in message attributes.
message_attribute_names: ["All"], # Receive any custom message attributes.
max_number_of_messages: 10 # Receive up to 10 messages, if there are that many.
})
puts "Received #{receive_message_result.messages.count} message(s)." rescue Aws::SQS::Errors::NonExistentQueue
puts "Cannot receive messages using receive_message for a queue named
'#{receive_queue_name}', as it does not exist." end
# 2. Using Aws::SQS::QueuePoller.
begin
puts "Begin receipt of any messages using Aws::SQS::QueuePoller..."
puts "(Will keep polling until no more messages available for at least 60 seconds.)"
poller = Aws::SQS::QueuePoller.new(receive_queue_url)
poller_stats = poller.poll({
max_number_of_messages: 10,
idle_timeout: 60 # Stop polling after 60 seconds of no more messages available (polls
indefinitely by default).
}) do |messages|
messages.each do |message|
puts "Message body: #{message.body}"
end
end
# Note: If poller.poll is successful, all received messages are automatically deleted
from the queue.
98
AWS SDK for Ruby Developer Guide
Receiving Messages Using the
QueuePoller Class in Amazon SQS
puts "Poller stats:"
puts " Polling started at: #{poller_stats.polling_started_at}"
puts " Polling stopped at: #{poller_stats.polling_stopped_at}"
puts " Last message received at: #{poller_stats.last_message_received_at}"
puts " Number of polling requests: #{poller_stats.request_count}"
puts " Number of received messages: #{poller_stats.received_message_count}" rescue Aws::SQS::Errors::NonExistentQueue
puts "Cannot receive messages using Aws::SQS::QueuePoller for a queue named
'#{receive_queue_name}', as it does not exist." end
Receiving Messages Using the QueuePoller Class in
Amazon SQS
The following example uses the
QueuePoller
utility class to display the body of all messages in the
SQS queue with the URL
URL
in the us-west-2
region, and deletes the message. After approximately 15 seconds of inactivity, the script times out.
require 'aws-sdk'
Aws.config.update({region: 'us-west-2'}) poller = Aws::SQS::QueuePoller.new(URL) poller.poll(idle_timeout: 15) do |msg|
puts msg.body
end
The following example loops through the Amazon SQS queue with the URL
URL
, and waits up to duration seconds.
You can get the correct URL by executing the Amazon SQS example in Getting Information about All
.
require 'aws-sdk'
Aws.config.update({region: 'us-west-2'}) poller = Aws::SQS::QueuePoller.new(URL) poller.poll(wait_time_seconds: duration, idle_timeout: duration + 1) do |msg|
puts msg.body
end
The following example loops through the Amazon SQS queue with the URL
URL
, and gives you up to the visibility timeout seconds to process the message, represented by the method do_something
.
require 'aws-sdk'
# Process the message def do_something(msg)
puts msg.body
end
Aws.config.update({region: 'us-west-2'}) poller = Aws::SQS::QueuePoller.new(URL)
99
AWS SDK for Ruby Developer Guide
Redirecting Dead Letters in Amazon SQS poller.poll(timeout_visibility: timeout, idle_timeout: timeout + 1) do |msg|
do_something(msg) end
The following example loops through the Amazon SQS queue with the URL
URL
, and changes the visibility timeout seconds, for any message that needs additional processing by the method do_something2
.
require 'aws-sdk'
# Process the message def do_something(msg)
true end
# Do additional processing def do_something2(msg)
puts msg.body
end
Aws.config.update({region: 'us-west-2'}) poller = Aws::SQS::QueuePoller.new(URL) poller.poll(idle_timeout: timeout + 1) do |msg|
if do_something(msg)
# need more time for processing
poller.change_message_visibility_timeout(msg, timeout)
do_something2(msg)
end end
Redirecting Dead Letters in Amazon SQS
The following example redirects any dead letters from the queue with the URL
URL
to the queue with the
ARN
ARN
.
require 'aws-sdk' sqs = Aws::SQS::Client.new(region: 'us-west-2') sqs.set_queue_attributes({
queue_url: URL,
attributes:
{
'RedrivePolicy' => "{\"maxReceiveCount\":\"5\", \"deadLetterTargetArn\":\"#{ARN}\"}"
}
})
Deleting a Queue in Amazon SQS
The following example deletes the Amazon SQS queue with the URL
URL
in the us-west-2
region.
require 'aws-sdk' sqs = Aws::SQS::Client.new(region: 'us-west-2') sqs.delete_queue(queue_url: URL)
100
AWS SDK for Ruby Developer Guide
Enabling a Resource to Publish to a Queue in Amazon SQS
Enabling a Resource to Publish to a Queue in Amazon
SQS
The following example enables the resource with the ARN my-resource-arn
to publish to the queue with the ARN my-queue-arn
and URL my-queue-url
in the us-west-2
region.
require 'aws-sdk' sqs = Aws::SQS::Client.new(region: 'us-west-2') policy = '{
"Version":"2008-10-17",
"Id":' + my-queue-arn + '/SQSDefaultPolicy",
"Statement":[{
"Sid":"__default_statement_ID",
"Effect":"Allow",
"Principal":{
"AWS":"*"
},
"Action":["SQS:SendMessage"],
"Resource":"' + my-queue-arn + '",
"Condition":{
"ArnEquals":{
"AWS:SourceArn":"' + my-resource-arn + '"}
}
}]
}' sqs.set_queue_attributes({
queue_url: my-queue-url,
attributes: {
Policy: policy
}
})
Working with a Dead Letter Queue in Amazon SQS
Amazon SQS provides support for dead letter queues. A dead letter queue is a queue that other (source) queues can target for messages that can't be processed successfully. You can set aside and isolate these messages in the dead letter queue to determine why their processing didn't succeed. For more information about dead letter queues, see Using Amazon SQS Dead Letter Queues .
In this example, you use the AWS SDK for Ruby with Amazon SQS to:
1. Create a queue that represents a dead letter queue by using Aws::SQS::Client#create_queue .
2. Associate the dead letter queue with an existing queue by using
Aws::SQS::Client#set_queue_attributes .
3. Send a message to the existing queue by using Aws::SQS::Client#send_message .
4. Poll the queue by using Aws::SQS::QueuePoller .
5. Receive messages in the dead letter queue by using Aws::SQS::Client#receive_message .
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
101
AWS SDK for Ruby Developer Guide
Working with a Dead Letter Queue in Amazon SQS
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
You also need to use the AWS Management Console to create the existing queue, my-queue.
Note: For the sake of simplicity, the example code below does not demonstrate
Aws::SQS::Client#add_permission . In a real-world scenario, you should always restrict access to actions such as SendMessage, ReceiveMessage, DeleteMessage, and DeleteQueue. Not doing so could cause information disclosure, denial of service, or injection of messages into your queues.
Example
require 'aws-sdk'
# Uncomment for Windows.
# Aws.use_bundled_cert!
sqs = Aws::SQS::Client.new(region: 'us-east-1')
# Create a queue representing a dead letter queue.
dead_letter_queue_name = "dead-letter-queue" sqs.create_queue({
queue_name: dead_letter_queue_name
})
# Get the dead letter queue's URL and ARN, so that you can associate it with an existing
queue.
dead_letter_queue_url = sqs.get_queue_url(queue_name: dead_letter_queue_name).queue_url
dead_letter_queue_arn = sqs.get_queue_attributes({
queue_url: dead_letter_queue_url,
attribute_names: ["QueueArn"]
}).attributes["QueueArn"]
# Associate the dead letter queue with an existing queue.
begin
queue_name = "my-queue"
queue_url = sqs.get_queue_url(queue_name: queue_name).queue_url
# Use a redrive policy to specify the dead letter queue and its behavior.
redrive_policy = {
"maxReceiveCount" => "5", # After the queue receives the same message 5 times, send
that message to the dead letter queue.
"deadLetterTargetArn" => dead_letter_queue_arn
}.to_json
sqs.set_queue_attributes({
queue_url: queue_url,
attributes: {
"RedrivePolicy" => redrive_policy
}
}) rescue Aws::SQS::Errors::NonExistentQueue
puts "A queue named '#{queue_name}' does not exist."
exit(false) end
# Send a message to the queue.
puts "Sending a message..."
102
AWS SDK for Ruby Developer Guide
Specifying the Message Visibility Timeout in Amazon SQS sqs.send_message({
queue_url: queue_url,
message_body: "I hope I get moved to the dead letter queue."
})
30.downto(0) do |i|
print "\rWaiting #{i} second(s) for sent message to be receivable..."
sleep(1) end puts "\n" poller = Aws::SQS::QueuePoller.new(queue_url)
# Receive 5 messages max and stop polling after 20 seconds of no received messages.
poller.poll(max_number_of_messages:5, idle_timeout: 20) do |messages|
messages.each do |msg|
puts "Received message ID: #{msg.message_id}"
end end
# Check to see if Amazon SQS moved the message to the dead letter queue.
receive_message_result = sqs.receive_message({
queue_url: dead_letter_queue_url,
max_number_of_messages: 1
}) if receive_message_result.messages.count > 0
puts "\n#{receive_message_result.messages[0].body}" else
puts "\nNo messages received." end
Specifying the Message Visibility Timeout in Amazon
SQS
In Amazon SQS, immediately after a message is received, it remains in the queue. To prevent other consumers from processing the message again, Amazon SQS sets a visibility timeout. This is a period of time during which Amazon SQS prevents other consuming components from receiving and processing the message. To learn more, see Visibility Timeout .
In this example, you use the AWS SDK for Ruby with Amazon SQS to:
1. Get the URL of an existing queue by using Aws::SQS::Client#get_queue_url .
2. Receive up to 10 messages by using Aws::SQS::Client#receive_message .
3. Specify the time interval during which messages are not visible after they are received, by using
Aws::SQS::Client#change_message_visibility .
Prerequisites
Before running the example code, you need to install and configure the AWS SDK for Ruby, as described in:
•
Installing the AWS SDK for Ruby (p. 4)
•
Configuring the AWS SDK for Ruby (p. 5)
You also need to create the queue my-queue, which you can do in the Amazon SQS console.
103
AWS SDK for Ruby Developer Guide
Specifying the Message Visibility Timeout in Amazon SQS
Example
require 'aws-sdk' sqs = Aws::SQS::Client.new(region: 'us-east-1') begin
queue_name = "my-queue"
queue_url = sqs.get_queue_url(queue_name: queue_name).queue_url
receive_message_result_before = sqs.receive_message({
queue_url: queue_url,
max_number_of_messages: 10 # Receive up to 10 messages, if there are that many.
})
puts "Before attempting to change message visibility timeout: received
#{receive_message_result_before.messages.count} message(s)."
receive_message_result_before.messages.each do |message|
sqs.change_message_visibility({
queue_url: queue_url,
receipt_handle: message.receipt_handle,
visibility_timeout: 36000 # This message will not be visible for 10 hours (10 hours *
60 minutes * 60 seconds) after first receipt.
})
end
# Try to retrieve the original messages after setting their visibility timeout.
receive_message_result_after = sqs.receive_message({
queue_url: queue_url,
max_number_of_messages: 10
})
puts "\nAfter attempting to change message visibility timeout: received
#{receive_message_result_after.messages.count} message(s)." rescue Aws::SQS::Errors::NonExistentQueue
puts "Cannot receive messages for a queue named '#{receive_queue_name}', as it does not
exist." end
104
AWS SDK for Ruby Developer Guide
Amazon EC2 Tips and Tricks
AWS SDK for Ruby Tips and Tricks
This section provides tips and tricks on using the AWS SDK for Ruby with AWS services.
Topics
•
Amazon EC2 Tips and Tricks (p. 105)
Amazon EC2 Tips and Tricks
This section provides some tips to help you the AWS SDK for Ruby with Amazon Elastic Compute Cloud
(Amazon EC2) services. For more information about Amazon EC2, see the Amazon EC2 Getting Started
Guide .
Switching Elastic IPs
The following example associates the Elastic IP address with the instance represented by i-12345678
.
ec2 = Aws::EC2::Client.new
resp = ec2.allocate_address
ec2.associate_address(instance_id:"i-12345678", allocation_id: resp.allocation_id)
105
AWS SDK for Ruby Developer Guide
Document History
To view the list of changes to the AWS SDK for Ruby and its documentation, see the CHANGELOG.md
file in the aws/aws-sdk-ruby
repository in GitHub.
106
advertisement
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project