Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
AWS SDK for Ruby Developer Guide May 08, 2017 Contents AWS SDK for Ruby Developer Guide AWS SDK for Ruby Developer Guide 1 2 About This Guide 2 Additional Documentation and Resources 2 Deploying to the AWS Cloud Getting Started with the AWS SDK for Ruby QuickStart Guide to Using the AWS SDK for Ruby 3 4 4 Write the Code 4 Run the Code 4 Note for Windows users 4 Installing the AWS SDK for Ruby 5 Prerequisites To sign up for AWS Installing the AWS SDK for Ruby Configuring the AWS SDK for Ruby Setting AWS Credentials 5 5 5 5 5 Setting Shared Credentials 6 Setting Credentials Using Environment Variables 6 Setting Credentials Using Aws.config 6 Setting Credentials in a Client Object 7 Setting Credentials Using IAM 7 Creating an AWS STS Access Token 7 Setting a Region 7 Setting the Region Using Environment Variables 7 Setting the Region Using Aws.config 8 Setting the Region in a Client or Resource Object 8 Setting a Nonstandard Endpoint 8 Using the AWS SDK for Ruby REPL 8 Using the SDK with Ruby on Rails 9 Integrating the AWS SDK for Ruby with Rails 9 Amazon SES Support for ActionMailer 9 Logging 9 Migrating from version 1 to version 2 of the AWS SDK for Ruby 10 Side-by-Side Usage 10 General Differences 10 Client Differences 10 Resource Differences 11 Hello World Tutorial 13 Using the AWS SDK for Ruby in Your Program 13 Creating an Amazon S3 Resource 13 Creating a Bucket 13 Adding a File to the Bucket 13 Listing the Contents of a Bucket 13 Complete Program 14 Running the Program 16 Next Steps 16 Programming with the AWS SDK for Ruby 17 Debugging Tip: Getting Wire Trace Information from a Client 17 Stubbing Client Responses and Errors 18 Stubbing Client Responses 18 Stubbing Client Errors 19 Paging Response Data 19 Paged Responses Are Enumerable 19 Handling Paged Responses Manually 20 Paged Data Classes 20 Using Waiters 20 Invoking a Waiter 20 Wait Failures 21 Configuring a Waiter 21 Extending a Waiter 22 Specifying a Client Timeout Duration 22 AWS SDK for Ruby Code Examples 23 Amazon CloudWatch Examples 23 Getting Information about All Alarms 23 Creating an Alarm 23 Enabling and Disabling Alarm Actions 24 Prerequisites 25 Example 25 Getting Info about Custom Metrics 26 Prerequisites 26 Example 26 Sending Events to Amazon CloudWatch Events 27 Prerequisites 28 Example 28 Amazon DynamoDB Examples 31 Getting Information about All Tables 31 Creating a Simple Table with a Single Primary Key 31 Adding an Item to a Table 32 Getting Information about the Items in a Table 33 Getting Information about a Specific Item in a Table 33 Updating a Table 33 Creating an Index 34 Amazon EC2 Examples 35 Creating a VPC 35 Creating an Internet Gateway and Attaching It to a VPC 35 Creating a Public Subnet 36 Creating a Route Table and Associating It with a Subnet 36 Using Elastic IP Addresses in Amazon EC2 37 Prerequisites 37 Example Script 38 Creating a Security Group 39 Working with Security Groups in Amazon EC2 39 Prerequisites 40 Configure the SDK 40 Create a Security Group 40 Get Info about a Security Group 41 Delete a Security Group 43 Working with Key Pairs 43 Create a Key Pair 43 Get Information about Key Pairs 44 Delete a Key Pair 44 Complete Example 45 Getting Information about All Instances 46 Getting Information about All Instances with a Specific Tag Value 46 Getting Information about a Specific Instance 47 Creating an Instance 47 Stopping an Instance 48 Starting an Instance 48 Rebooting an Instance 49 Managing Amazon EC2 Instances in Amazon EC2 49 Prerequisites 49 Example 50 Terminating an Instance 51 Getting Information about Regions and Availability Zones 52 Get Information about Regions and Endpoints 52 Get Information about Availability Zones 52 Complete Example 53 AWS Elastic Beanstalk Examples 54 Getting Information about All Applications 54 Getting Information about a Specific Application 54 Updating a Ruby on Rails Application 54 AWS Identity and Access Management Examples 56 Getting Information about All Users 56 Adding a New User 57 Create a User's Access Keys 57 Adding a Managed Policy 58 Creating a Role 58 Managing IAM Users 59 Prerequisites 59 Example 59 Working with IAM Policies 60 Prerequisites 61 Example 61 Managing IAM Access Keys 62 Prerequisites 62 Example 62 Working with IAM Server Certificates Prerequisites 64 64 Example Managing IAM Account Aliases 64 65 Prerequisites 65 Example 65 Lambda Examples 66 Displaying Information about All Lambda Functions 66 Creating a Lambda Function 67 Configuring a Lambda Function to Receive Notifications 67 Amazon Relational Database Service Examples 68 Getting Information about All Instances 68 Getting Information about All Snapshots 68 Getting Information about All Clusters and Their Snapshots 69 Getting Information about All Security Groups 69 Getting Information about All Subnet Groups 70 Getting Information about All Parameter Groups 70 Creating a Snapshot of an Instance 70 Creating a Snapshot of a Cluster 71 Amazon S3 Examples 71 Getting Information about All Buckets 72 Getting Information about All Buckets in a Region 72 Creating and Using an Amazon S3 Bucket 73 Prerequisite Tasks 73 Configure the SDK 73 Get a List of Buckets 74 Create a Bucket 74 Upload an Object (a File) to a Bucket 74 Copy Files between Buckets 74 Delete Files from a Bucket 75 Complete Example 75 Alternative Approaches 77 Determining Whether a Bucket Exists 77 Getting Information about Bucket Items 78 Uploading an Item to a Bucket 78 Uploading an Item with Metadata to a Bucket 78 Downloading an Object from a Bucket into a File 79 Changing the Properties for a Bucket Item 79 Triggering a Notification When an Item is Added to a Bucket 80 Enabling Amazon S3 to Send a Notification 80 Creating an Amazon S3 Bucket Notification 81 Creating a Bucket LifeCycle Rule Configuration Template 82 Creating a Bucket Policy with Ruby 84 Prerequisite Tasks 84 Configure the SDK 84 Create a Bucket 85 Define a Bucket Policy 85 Add the Policy to the Bucket 86 Change the Policy 86 Clean Up 86 Complete Example 86 Configuring a Bucket for Cross-Origin Resource Sharing (CORS) 87 Prerequisite Tasks 88 Configure the SDK 88 Configure CORS for a Bucket 88 Get the CORS Settings for a Bucket 89 Complete Example 90 Managing Amazon S3 Bucket and Object Access Permissions 91 Prerequisite Tasks 91 Configure the SDK 91 Set a Canned ACL for a Bucket 92 Upload an Object to a Bucket 92 Set a Canned ACL for an Object 92 Get a Bucket's Current ACL 93 Complete Example 93 Using a Amazon S3 Bucket to Host a Website 94 Prerequisite Tasks 94 Configure the SDK 95 Create a Bucket 95 Get a Bucket Website's Configuration 95 Add an Object to a Bucket 95 Set a Bucket Website's Configuration 96 Access a Bucket Website's Documents 96 Delete a Bucket Website 96 Delete a Bucket 96 Complete Example 97 Amazon SNS Examples 98 Getting Information about All Topics 98 Creating a Topic 98 Getting Information about All Subscriptions in a Topic 98 Creating a Subscription in a Topic 99 Sending a Message to All Topic Subscribers 99 Enabling a Resource to Publish to a Topic 99 Amazon SQS Examples 100 Getting Information about All Queues in Amazon SQS 100 Creating a Queue in Amazon SQS 101 Working with Queues in Amazon SQS 101 Prerequisites 101 Example 102 Sending Messages in Amazon SQS 102 Sending and Receiving Messages in Amazon SQS 103 Prerequisites 103 Example 103 Receiving Messages in Amazon SQS 105 Receiving Messages Using Long Polling in Amazon SQS 105 Enabling Long Polling in Amazon SQS 105 Prerequisites 106 Example 106 Receiving Messages Using the QueuePoller Class in Amazon SQS 107 Redirecting Dead Letters in Amazon SQS 109 Deleting a Queue in Amazon SQS 109 Enabling a Resource to Publish to a Queue in Amazon SQS 110 Working with a Dead Letter Queue in Amazon SQS 110 Prerequisites 111 Example 111 Specifying the Message Visibility Timeout in Amazon SQS Prerequisites 112 113 Example 113 AWS SDK for Ruby Tips and Tricks 115 Amazon EC2 Tips and Tricks 115 Switching Elastic IPs 115 Document History 116 About Amazon Web Services 117 AWS SDK for Ruby Developer Guide AWS SDK for Ruby Developer Guide 1 AWS SDK for Ruby Developer 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 Describes how to set up and use the AWS SDK for Ruby. Hello World Tutorial Steps you through creating an application using the AWS SDK for Ruby. Programming with the AWS SDK for Ruby Provides general information about developing software with the AWS SDK for Ruby. AWS SDK for Ruby Code Examples Provides code examples that developers can use to program AWS services with the AWS SDK for Ruby. Document History Describes the history of this document. Additional Documentation and Resources For more resources for AWS SDK for Ruby developers, see the following: • 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 2 AWS SDK for Ruby Developer Guide 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. 3 Getting Started with 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. 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. • If you haven't configured the SDK, see Configuring the AWS SDK for Ruby. 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 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 from C:/Ruby200-x64/lib/ruby/2.0.0/net/http.rb:921:in `block in connect' from from from from C:/Ruby200-x64/lib/ruby/2.0.0/timeout.rb:66:in `timeout' C:/Ruby200-x64/lib/ruby/2.0.0/net/http.rb:921:in `connect' C:/Ruby200-x64/lib/ruby/2.0.0/net/http.rb:862:in `do_start' 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. 4 Getting Started with the AWS SDK for Ruby 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. 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 2. Setting Credentials Using Aws.config 3. Setting Credentials Using Environment Variables 5 Getting Started with the AWS SDK for Ruby 4. Setting Shared Credentials 5. Setting Credentials Using IAM 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. 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. 6 Getting Started with the AWS SDK for Ruby 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" ) 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 • Setting the Region Using Aws.config • Setting the Region Using Environment Variables The rest of this section describes how to set a region, starting with the most flexible approach. Setting the Region Using Environment Variables 7 Getting Started with the AWS SDK for Ruby 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 us-west-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) 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. 8 Getting Started with the AWS SDK for Ruby 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. 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}) 9 Getting Started with the AWS SDK for Ruby 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) # => 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 10 Getting Started with the AWS SDK for Ruby 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 • Referencing resources - The version 2 SDK separates collections and individual resource getters into two different methods: 11 Getting Started with the AWS SDK for Ruby # 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. 12 Hello World Tutorial 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. 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 13 Hello World Tutorial 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 create - creates a upload - uploads a list - (default) perform on the bucket: new bucket file to the bucket lists up to 50 bucket items file_name is the name of the file to upload, required when operation is 'upload' DOC # Set the name of the bucket on which the operations are performed # This argument is required bucket_name = nil if ARGV.length > 0 bucket_name = ARGV[0] else puts USAGE exit 1 end # The operation to perform on the bucket operation = 'list' # default operation = ARGV[1] if (ARGV.length > 1) # The file name to use with 'upload' file = nil file = ARGV[2] if (ARGV.length > 2) # Get an Amazon S3 resource s3 = Aws::S3::Resource.new(region: 'us-west-2') # Get the bucket by name bucket = s3.bucket(bucket_name) 14 Hello World Tutorial 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 15 Hello World Tutorial 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 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 to confirm the item exists in the bucket, and then update that bucket item. 16 Programming with the AWS SDK for Ruby 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. 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 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 Authorization: AWS4-HMAC-SHA256 Credential=ACCESS_KEY/20160121/us-west-1/s3/aws4_request SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=2ca8301c5e829700940d3cc3bca2a3e8d79d177f2c046c34a1a285770db6382 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" 17 Programming with the AWS SDK for Ruby -> "x-amz-id-2: N6BzRLx8b68NmF50g1IxLzT+E4uWPuAIRe7Pl4XKl5STT4tfNO7gBsO8qrrAnG4CbVpU0iIRXmk -> "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' s3 = Aws::S3::Client.new(stub_responses: true) bucket_data = s3.stub_data(:list_buckets, :buckets => [{name:'aws-sdk'}, {name:'aws-sdk2'}] 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 18 Programming with the AWS SDK for Ruby 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. 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| 19 Programming with the AWS SDK for Ruby 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. 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. 20 Programming with the AWS SDK for Ruby ec2 = Aws::EC2::Client.new 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 21 Programming with the AWS SDK for Ruby w.delay = 5 end To disable wait failures, set the value of either of these parameters to nil. 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) 22 AWS SDK for Ruby Code 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. 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 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 puts 'Name: puts 'State: puts ' reason: puts 'Metric: puts 'Namespace: puts 'Statistic: puts 'Dimensions (' + do |alarm| ' + alarm.alarm_name ' + alarm.state_value ' + alarm.state_reason ' + alarm.metric_name ' + alarm.namespace ' + alarm.statistic alarm.dimensions.length.to_s + '):' alarm.dimensions.each do |d| puts ' Name: ' + d.name puts ' Value: ' + d.value end puts puts puts puts puts puts end 'Period: 'Unit: 'Eval periods: 'Threshold: 'Comp operator: ' ' ' ' ' + + + + + alarm.period.to_s alarm.unit.to_s alarm.evaluation_periods.to_s alarm.threshold.to_s alarm.comparison_operator 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. 23 AWS SDK for Ruby Code Examples 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 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. 24 AWS SDK for Ruby Code Examples 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 • Configuring the AWS SDK for Ruby 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({ alarm_name: alarm_name, alarm_description: "Alarm whenever an average of more than one object exists in the speci 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 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. 25 AWS SDK for Ruby Code Examples }) # 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 • Configuring the AWS SDK for Ruby Example require 'aws-sdk' # Uncomment for Windows. # Aws.use_bundled_cert! cw = Aws::CloudWatch::Client.new(region: 'us-east-1') # 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" } 26 AWS SDK for Ruby Code Examples ], 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: 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. 27 AWS SDK for Ruby Code Examples 3. Send an event to CloudWatch Events so that it can be matched to the rule. #. 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 • Configuring the AWS SDK for Ruby 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 lambda_basic_execution. an Existing Role. For the existing role, select 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:LogEC2InstanceStateChan # 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" 28 AWS SDK for Ruby Code Examples # 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 = { "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 ]) 29 AWS SDK for Ruby Code Examples 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, }, ], start_time: Time.now - 600, # Look back over the past 10 minutes to see if the rule was triggered (10 minutes * 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 be 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 lates }) 30 AWS SDK for Ruby Code Examples 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 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' } 31 AWS SDK for Ruby Code Examples ] 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: key_schema: projection: provisioned_throughput: }] 'LastNameFirstNameIndex', index_schema, { projection_type: 'ALL' }, { read_capacity_units: 5, write_capacity_units: 10 } request = { attribute_definitions: table_name: key_schema: global_secondary_indexes: provisioned_throughput: } attribute_defs, 'Users', key_schema, global_indexes, { 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' }}) 32 AWS SDK for Ruby Code Examples 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' 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. 33 AWS SDK for Ruby Code Examples 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: [ { create: { index_name: 'air-mileage-index', key_schema: [ { attribute_name: 'airmiles', key_type: 'HASH', }, ], projection: { 34 AWS SDK for Ruby Code Examples 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 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 35 AWS SDK for Ruby Code Examples 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') 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 }) 36 AWS SDK for Ruby Code Examples 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 Aws::EC2::Client#describe_addresses method. with the instance by using the 4. Release the address by using the Aws::EC2::Client#release_address method. 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 • Configuring the AWS SDK for Ruby You also need to launch an EC2 instance and note the instance ID. 37 AWS SDK for Ruby Code Examples 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 t display_addresses(ec2, instance_id) 38 AWS SDK for Ruby Code Examples puts "\nAssociating the address with the instance..." associate_address_result = ec2.associate_address({ allocation_id: allocate_address_result.allocation_id, instance_id: instance_id, }) puts "\nAfter associating the address with the instance, but before releasing the address fr 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 39 AWS SDK for Ruby Code Examples 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. 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 • Configuring the AWS SDK for Ruby 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). 40 AWS SDK for Ruby Code Examples # 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, 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 41 AWS SDK for Ruby Code Examples 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}" 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) 42 AWS SDK for Ruby Code Examples 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. 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: 43 AWS SDK for Ruby Code Examples • 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 Complete Example. 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 puts puts puts puts "Created key pair '#{key_pair.key_name}'." "\nSHA-1 digest of the DER encoded private key:" "#{key_pair.key_fingerprint}" "\nUnencrypted PEM encoded RSA private key:" "#{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 Complete Example. Delete a Key Pair Call the delete_key_pair method, specifying the name of the key pair to delete. 44 AWS SDK for Ruby Code Examples 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. 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 }) 45 AWS SDK for Ruby Code Examples To run this code, you must: 1. Install the AWS SDK for Ruby. For more information, see Installing the AWS SDK for Ruby. 2. Set the AWS access credentials that the AWS SDK for Ruby will use to verify your access to AWS services and resources. For more information, see Configuring the AWS SDK for Ruby. Be sure the AWS credentials map to an AWS Identity and Access Management (IAM) entity with access to the AWS actions and resources described in this example. This example assumes you have set the credentials in the AWS credentials profile file 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 46 AWS SDK for Ruby Code Examples 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 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 public DNS and 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' 47 AWS SDK for Ruby Code Examples }, subnet_id: 'SUBNET_ID', network_interfaces: [{ device_index: 0, associate_public_ip_address: true }], 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', v puts instance.id 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" 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') 48 AWS SDK for Ruby Code Examples 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. 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: 49 AWS SDK for Ruby Code Examples • Installing the AWS SDK for Ruby • Configuring the AWS SDK for Ruby 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. rescue Aws::EC2::Errors::InvalidState puts "Instance '#{instance_id}' is not in a monitorable state. Continuing on..." end # Get information about available instances. 50 AWS SDK for Ruby Code Examples puts "\nAvailable instances:" describe_instances_result = ec2.describe_instances 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 51 AWS SDK for Ruby Code Examples 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. For additional code that you can use to run these examples, see Complete Example. Get Information about Regions and Endpoints 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 Complete Example. 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 Aws::EC2::Types::Region objects representing the regions. attribute to get an array of 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 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 Complete Example. Use the AvailabilityZone object's zone_name and state attributes. 52 AWS SDK for Ruby Code Examples 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 1. Use the AvailabilityZone object's Aws::EC2::Types::AvailabilityZoneMessage array. messages attribute, which returns an 2. If there is at least one message in the array, use each AvailabilityZoneMessage object's message attribute to get the message. 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 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 1. Install the AWS SDK for Ruby. For more information, see Installing the AWS SDK for Ruby. 2. Set the AWS access credentials that the AWS SDK for Ruby will use to verify your access to AWS services and resources. For more information, see Configuring the AWS SDK for Ruby. Be sure the AWS credentials map to an AWS Identity and Access Management (IAM) entity with access to the AWS actions and resources described in this example. This example assumes you have set the credentials in the AWS credentials profile file or in the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables on your local system. 53 AWS SDK for Ruby Code Examples 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 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. 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 |e 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 us-west-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: puts "Description: #{app.application_name}" #{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. 54 AWS SDK for Ruby Code Examples 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] 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 55 AWS SDK for Ruby Code Examples 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 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 56 AWS SDK for Ruby Code Examples 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 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 57 AWS SDK for Ruby Code Examples 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:[ { Effect:"Allow", Principal:{ Service:"ec2.amazonaws.com" }, Action:"sts:AssumeRole" }] } 58 AWS SDK for Ruby Code Examples 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 • Configuring the AWS SDK for Ruby 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 59 AWS SDK for Ruby Code Examples 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. 60 AWS SDK for Ruby Code 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 • Configuring the AWS SDK for Ruby You will also need to create the role (my-role) specified in the script. You can do this in the IAM console. 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 }) 61 AWS SDK for Ruby Code Examples # List policies attached to the role. puts "\nAttached role policy ARNs..." iam.list_attached_role_policies({ role_name: role_name }).attached_policies.each do |attach 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 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 • Configuring the AWS SDK for Ruby 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 Adding a New User. Example require 'aws-sdk' iam = Aws::IAM::Client.new(region: 'us-east-1') user_name = "my-user" # List user access keys. 62 AWS SDK for Ruby Code Examples 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..." 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_ # 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" 63 AWS SDK for Ruby Code Examples }) 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 • Configuring the AWS SDK for Ruby Note also that the server certificate Aws::IAM::Errors::NoSuchEntity error. must already exist, or the script 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. 64 will throw an AWS SDK for Ruby Code Examples 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_m 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_metad 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. 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 • Configuring the AWS SDK for Ruby In the example code, change the my-account-alias string to something that will be unique across all Amazon Web Services products. Example 65 AWS SDK for Ruby Code Examples 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 Displaying Information about All Lambda Functions The following example displays the name, ARN, and role of all of your Lambda functions in the us-west-2 region. 66 AWS SDK for Ruby Code Examples 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) 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. 67 AWS SDK for Ruby Code Examples 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] 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 Getting Information about All Instances The following example lists the name (ID) and status of all of your Amazon RDS instances in the us-west-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. 68 AWS SDK for Ruby Code Examples 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 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:' 69 AWS SDK for Ruby Code Examples 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 us-west-2 region. 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. 70 AWS SDK for Ruby Code Examples 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). 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 + '-' + dat '-' + dat 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') cluster = rds.db_cluster(cluster_name) date = Time.new date_time = date.year.to_s + '-' + date.month.to_s + '-' + date.day.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 71 AWS SDK for Ruby Code Examples 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 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 Getting Information about All Buckets in a Region 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. 72 AWS SDK for Ruby Code Examples 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 Complete Example. 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. 2. Set the AWS access credentials that the AWS SDK for Ruby will use to verify your access to AWS services and resources. For more information, see Configuring the AWS SDK for Ruby. Be sure the AWS credentials map to an AWS Identity and Access Management (IAM) entity with access to the AWS actions and resources described in this example. This example assumes you have set the credentials in the AWS credentials profile file and named the file david. Configure the SDK For this example, add require statements so that you can use the classes and methods provided by the AWS SDK for Ruby for Amazon S3 and work with JSON-formatted data. Then create an Aws::S3::Client object in the AWS Region where you want to create the bucket and the specified AWS profile. This code creates the Aws::S3::Client object in the us-east-1 region. Additional variables are also declared for the two buckets used in this example. require 'aws-sdk' require 'json' profile_name = 'david' region = "us-east-1" bucket = 'doc-sample-bucket' my_bucket = 'david-cloud' # S3 73 AWS SDK for Ruby Code Examples # Configure SDK s3 = Aws::S3::Client.new(profile: profile_name, region: region) Get a List of Buckets Call the list_buckets method. This returns an instance of the Aws::S3::Types::ListBucketsOutput class, which represents the list of buckets. Then use the buckets attribute of the ListBucketsOutput class to access the buckets' properties, such as name for each bucket's name. resp = s3.list_buckets resp.buckets.each do |bucket| puts bucket.name end Create a Bucket Call the create_bucket method, specifying the bucket's name. Note Bucket names must be unique across Amazon S3—not just unique to your AWS account. s3.create_bucket(bucket: bucket) Upload an Object (a File) to a Bucket Call the put_object method, specifying settings such as the bucket's name and the name of the file to create. For the file's contents, you can specify an instance of a Ruby File class or, in this example, a string representing the file's data. To confirm whether the file was uploaded successfully, call the list_objects_v2 method. This returns an instance of the Aws::S3::Types::ListObjectsV2Output class, which represents the bucket's objects. Then use the contents method of the ListObjectsV2Output class to access the objects' properties, such as key for each object's name. s3.put_object(bucket: bucket, key: "file1", body: "My first s3 object") # Check the file exists resp = s3.list_objects_v2(bucket: bucket) resp.contents.each do |obj| puts obj.key end Copy Files between Buckets 74 AWS SDK for Ruby Code Examples 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. 75 AWS SDK for Ruby Code Examples require 'aws-sdk' require 'json' profile_name = 'david' region = "us-east-1" bucket = 'doc-sample-bucket' my_bucket = 'david-cloud' # S3 # Configure SDK s3 = Aws::S3::Client.new(profile: profile_name, region: region) # Display a List of Amazon S3 Buckets resp = s3.list_buckets resp.buckets.each do |bucket| puts bucket.name end # Create a S3 bucket from S3::client s3.create_bucket(bucket: bucket) # Upload a file to s3 bucket, directly putting string data s3.put_object(bucket: bucket, key: "file1", body: "My first s3 object") # Check the file exists resp = s3.list_objects_v2(bucket: bucket) resp.contents.each do |obj| puts obj.key end # Copy files from bucket to bucket s3.copy_object(bucket: bucket, copy_source: "#{my_bucket}/test_file", key: 'file2') s3.copy_object(bucket: bucket, copy_source: "#{my_bucket}/test_file1", key: 'file3') # Delete multiple objects in a single HTTP request s3.delete_objects( bucket: 'doc-sample-bucket', delete: { objects: [ { key: 'file2' }, { key: 'file3' } 76 AWS SDK for Ruby Code Examples ] } ) # Verify objects now have been deleted resp = s3.list_objects_v2(bucket: bucket) resp.contents.each do |obj| puts obj.key end Alternative Approaches The following example creates a bucket named my-bucket in the us-west-2 region. This example uses an instance of the Aws::S3::Resource class instead of the Aws::S3::Client class. require 'aws-sdk' s3 = 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}) 77 AWS SDK for Ruby Code Examples 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 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 78 AWS SDK for Ruby Code Examples 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 us-west-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') # 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' 79 AWS SDK for Ruby Code Examples # 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-owner-read, 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. Grant Amazon S3 permission to publish an item to a queue or topic, or invoke a Lambda function. 2. Set the bucket's Notification Configuration to point to the queue, topic, or function. 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 • Enabling a Resource to Publish to a Queue in Amazon SQS • Configuring a Lambda Function to Receive Notifications 80 AWS SDK for Ruby Code Examples 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 notification_configuration[:topic_configurations] = topic_configurations req[:notification_configuration] = notification_configuration 81 AWS SDK for Ruby Code Examples 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' s3 = Aws::S3::Client.new(region: 'us-west-2') resp = s3.get_bucket_lifecycle_configuration(bucket: 'default') resp.rules.each do |rule| 82 AWS SDK for Ruby Code Examples 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":nu 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 83 AWS SDK for Ruby Code Examples # 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') s3.put_bucket_lifecycle_configuration(:bucket => 'other_bucket', :lifecycle_configuration = Best Practice 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. 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 Complete Example. 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. 2. Set the AWS access credentials that the AWS SDK for Ruby will use to verify your access to AWS services and resources. For more information, see Configuring the AWS SDK for Ruby. Be sure the AWS credentials map to an AWS Identity and Access Management (IAM) entity with access to the AWS actions and resources described in this example. This example assumes you have set the credentials in the AWS credentials profile file or in the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables on your local system. Configure the SDK 84 AWS SDK for Ruby Code Examples 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 us-west-2 region. require 'aws-sdk' s3 = Aws::S3::Client.new(region: "us-west-2") 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}" ] 85 AWS SDK for Ruby Code Examples } ] }.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 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. 86 AWS SDK for Ruby Code Examples 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) 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. 87 AWS SDK for Ruby Code Examples 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 Complete Example. 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. 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. 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' # 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 88 AWS SDK for Ruby Code Examples 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 << when "GET" allowed_methods << when "PUT" allowed_methods << when "PATCH" allowed_methods << when "DELETE" allowed_methods << when "HEAD" allowed_methods << else puts "#{arg} is not end end "POST" "GET" "PUT" "PATCH" "DELETE" "HEAD" a valid HTTP method" 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 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. 89 AWS SDK for Ruby Code Examples 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"], }, 90 AWS SDK for Ruby Code Examples ] } # Set the new CORS configuration on the selected bucket s3.put_bucket_cors( bucket: bucket, cors_configuration: cors_configuration ) # 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 Complete Example. 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. 2. Set the AWS access credentials that the AWS SDK for Ruby will use to verify your access to AWS services and resources. For more information, see Configuring the AWS SDK for Ruby. Be sure the AWS credentials map to an AWS Identity and Access Management (IAM) entity with access to the AWS actions and resources described in this example. This example assumes you have set the credentials in the AWS credentials profile file 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' 91 AWS SDK for Ruby Code Examples # 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 read-only access for everyone else. 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. 92 AWS SDK for Ruby Code Examples 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. 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)) 93 AWS SDK for Ruby Code Examples 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: 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 Complete Example. 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. 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. 94 AWS SDK for Ruby Code Examples 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) 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. 95 AWS SDK for Ruby Code Examples 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" 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 96 AWS SDK for Ruby Code Examples 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" } } 97 AWS SDK for Ruby Code 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 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' 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 98 AWS SDK for Ruby Code Examples 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:us-west-2:123456789:MyGroovyTopic for a user who has the email address [email protected] 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!' }) Enabling a Resource to Publish to a Topic 99 AWS SDK for Ruby Code Examples 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 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 100 AWS SDK for Ruby Code Examples # 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. 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 101 AWS SDK for Ruby Code Examples 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 • Configuring the AWS SDK for Ruby 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 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') sqs.send_message(queue_url: URL, message_body: 'Hello world') 102 AWS SDK for Ruby Code Examples 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 • Configuring the AWS SDK for Ruby 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. 103 AWS SDK for Ruby Code Examples queue_name = "my-queue" begin queue_url = sqs.get_queue_url(queue_name: queue_name).queue_url # 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-1 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, 104 AWS SDK for Ruby Code Examples 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') 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: 1 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. 105 AWS SDK for Ruby Code Examples 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 • Configuring the AWS SDK for Ruby 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') # 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 e end # Set long polling when receiving messages for a queue. 106 AWS SDK for Ruby Code Examples # 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_na 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. 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_qu 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. 107 AWS SDK for Ruby Code Examples 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 Queues in Amazon SQS. 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) 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' 108 AWS SDK for Ruby Code Examples # 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) 109 AWS SDK for Ruby Code Examples 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. 110 AWS SDK for Ruby Code 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 • Configuring the AWS SDK for Ruby 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 d "deadLetterTargetArn" => dead_letter_queue_arn }.to_json sqs.set_queue_attributes({ queue_url: queue_url, 111 AWS SDK for Ruby Code Examples 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..." 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 112 AWS SDK for Ruby Code Examples 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 • Configuring the AWS SDK for Ruby 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') 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_ 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 seco }) 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_ 113 AWS SDK for Ruby Code Examples rescue Aws::SQS::Errors::NonExistentQueue puts "Cannot receive messages for a queue named '#{receive_queue_name}', as it does not ex end 114 AWS SDK for Ruby 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. 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) 115 Document History 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. 116 About Amazon Web Services About Amazon Web Services Amazon Web Services (AWS) is a collection of digital infrastructure services that developers can leverage when developing their applications. The services include computing, storage, database, and application synchronization (messaging and queuing). AWS uses a pay-as-you-go service model: you are charged only for the services that you—or your applications—use. For new AWS users, a free usage tier is available. On this tier, services are free below a certain level of usage. For more information about AWS costs and the Free Tier, see Use the AWS Free Tier. To obtain an AWS account, visit the AWS home page and click Create a Free Account. 117