AWS SDK for Ruby Developer Guide AWS SDK for Ruby: Developer Guide Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved. AWS SDK for Ruby Developer Guide Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon. AWS SDK for Ruby Developer Guide Table of Contents AWS SDK for Ruby Developer Guide .................................................................................................... 1 Using the AWS SDK for Ruby with AWS Cloud9 ............................................................................. 1 About This Guide ....................................................................................................................... 1 Additional Documentation and Resources ...................................................................................... 1 Deploying to the AWS Cloud ............................................................................................... 2 Maintenance and support for SDK major versions .......................................................................... 2 Getting Started .................................................................................................................................. 3 Quick Start Guide ...................................................................................................................... 3 Write the Code .................................................................................................................. 3 Run the Code .................................................................................................................... 3 Note for Windows Users ..................................................................................................... 3 Installing the SDK ...................................................................................................................... 4 Prerequisites ...................................................................................................................... 4 Installing the SDK .............................................................................................................. 4 Hello World Tutorial ................................................................................................................... 4 Using the AWS SDK for Ruby in Your Program ....................................................................... 5 Creating an Amazon S3 Resource ......................................................................................... 5 Creating a Bucket ............................................................................................................... 5 Adding a File to the Bucket ................................................................................................. 5 Listing the Contents of a Bucket .......................................................................................... 5 Complete Program ............................................................................................................. 5 Running the Program ......................................................................................................... 7 Next Steps ........................................................................................................................ 7 Configuring the SDK ........................................................................................................................... 8 Get your AWS access keys ........................................................................................................... 8 To get your access key ID and secret access key ..................................................................... 8 Setting AWS Credentials ............................................................................................................. 8 Setting Shared Credentials .................................................................................................. 9 Setting Credentials Using Environment Variables .................................................................... 9 Setting Credentials Using Aws.config ............................................................................... 10 Changing your Credentials Location .................................................................................... 10 Setting Credentials in a Client Object ................................................................................. 10 Setting Credentials Using IAM ............................................................................................ 10 Creating an AWS STS Access Token ............................................................................................ 10 Setting a Region ...................................................................................................................... 11 Setting the Region Using Environment Variables .................................................................. 11 Setting the Region Using Aws.config ............................................................................... 11 Setting the Region in a Client or Resource Object ................................................................. 11 Setting a Nonstandard Endpoint ................................................................................................ 11 SDK Metrics ............................................................................................................................. 12 Authorize SDK Metrics ...................................................................................................... 12 Set Up SDK Metrics .......................................................................................................... 14 SDK Metric Definitions ...................................................................................................... 16 Using AWS Cloud9 with the SDK ........................................................................................................ 18 Step 1: Set up Your AWS Account to Use AWS Cloud9 ................................................................... 18 Step 2: Set up Your AWS Cloud9 Development Environment .......................................................... 18 Step 3: Set up the AWS SDK for Ruby ......................................................................................... 18 Step 4: Download Example Code ................................................................................................ 19 Step 5: Run Example Code ........................................................................................................ 19 Using the SDK ................................................................................................................................. 20 Using the AWS SDK for Ruby REPL Tool ..................................................................................... 20 Using the SDK with Ruby on Rails ............................................................................................. 20 Migrating from Version 1 or 2 to Version 3 of the AWS SDK for Ruby ............................................. 21 Side-by-Side Usage ........................................................................................................... 21 iii AWS SDK for Ruby Developer Guide General Differences .......................................................................................................... 21 Client Differences ............................................................................................................. 21 Resource Differences ......................................................................................................... 22 Debugging Tip: Getting Wire Trace Information from a Client ........................................................ 23 Stubbing Client Responses and Errors ........................................................................................ 24 Stubbing Client Responses ................................................................................................ 24 Stubbing Client Errors ....................................................................................................... 25 Paging Response Data ............................................................................................................. 25 Paged Responses Are Enumerable ...................................................................................... 25 Handling Paged Responses Manually .................................................................................. 25 Paged Data Classes ........................................................................................................... 26 Using Waiters ......................................................................................................................... 26 Invoking a Waiter ............................................................................................................. 26 Wait Failures .................................................................................................................... 26 Configuring a Waiter ......................................................................................................... 27 Extending a Waiter