Repository files navigation


This is version 2 of theaws-sdk gem.Version 1 can be found in theaws-sdk-v1 branch.

• Documentation
• Change Log
• Upgrading Notes
• Issues
• Feature Requests
• Gitter Channel
• License

If you receive this error, you likely have upgraded to version 2 of theaws-sdk gem unintentionally. Version 2 uses theAws namespace, notAWS.This allows version 1 and version 2 to be used in the same application.

Seethis blog post for more information.

The AWS SDK for Ruby is available as theaws-sdk gem from RubyGems. Pleaseuse a major version when expressing a dependency onaws-sdk.

gem'aws-sdk','~> 2'

You need to configure:credentials and a:region to make API calls. It is recommended that you provide these via your environment. This makes it easier to rotate credentials and it keeps your secrets out of source control.

The SDK searches the following locations for credentials:

• ENV['AWS_ACCESS_KEY_ID'] andENV['AWS_SECRET_ACCESS_KEY']
• The shared credentials ini file at~/.aws/credentials (more information)
• From an instance profile when running on EC2

The SDK searches the following locations for a region:

• ENV['AWS_REGION']

You can configure default credentials and region viaAws.config.In version 2,Aws.config is a vanilla Ruby hash, not a method like it was in version 1.

Aws.config.update({region:'us-west-2',credentials:Aws::Credentials.new('akid','secret'),})

Valid region and credentials options are:

• :region - A string likeus-west-2. Seethis document for a list of supported regions by service.
• :credentials - An instance of one of the following classes:
  • Aws::Credentials
  • Aws::SharedCredentials
  • Aws::InstanceProfileCredentials
  • Aws::AssumeRoleCredentials

You may also pass configuration options directly to resource and client constructors. These options take precedence over the environment andAws.config defaults.

# resource constructorsec2=Aws::EC2::Resource.new(region:'us-west-2',credentials:credentials)# client constructorsec2=Aws::EC2::Client.new(region:'us-west-2',credentials:credentials)

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

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

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

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

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

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

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

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

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

# make a request that returns a truncated responseresp=s3.list_objects(bucket:'aws-sdk')resp.last_page?#=> falseresp.next_page?#=> trueresp=resp.next_page# send a request for the next response pageresp=resp.next_pageuntilresp.last_page?

Waiters are a utility methods that poll for a particular state. To invoke awaiter, call#wait_until on a client:

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

Waiters have sensible default polling intervals and maximum attempts. You canconfigure these per call to#wait_until. You can also register callbacksthat are triggered before each polling attempt and before waiting.See the API documentation for more examples and for a list of supportedwaiters per service.

Resource interfaces are object oriented classes that represent actualresources in AWS. Resource interfaces built on top of API clients and provideadditional functionality.

s3=Aws::S3::Resource.new# reference an existing bucket by namebucket=s3.bucket('aws-sdk')# enumerate every object in a bucketbucket.objects.eachdo |obj|puts"#{obj.key} =>#{obj.etag}"end# batch operations, delete objects in batches of 1kbucket.objects(prefix:'/tmp-files/').delete# single object operationsobj=bucket.object('hello')obj.put(body:'Hello World!')obj.etagobj.delete

Theaws-sdk-core gem ships with a REPL that provides a simple way to testthe Ruby SDK. You can access the REPL by runningaws.rb from the command line.

$aws.rbAws>ec2.describe_instances.reservations.first.instances.first[Aws::EC2::Client2000.2166150retries]describe_instances()<structinstance_id="i-1234567",image_id="ami-7654321",state=<structcode=16,name="running">, ...>

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

$ aws.rb -v

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

• Aws::S3 =>s3
• Aws::EC2 =>ec2
• etc

This project usessemantic versioning. You can safelyexpress a dependency on a major version and expect all minor and patch versionsto be backwards compatible.

This library is distributed under theApache License, version 2.0

copyright 2013. amazon web services, inc. all rights reserved.licensed under the apache license, version 2.0 (the "license");you may not use this file except in compliance with the license.you may obtain a copy of the license at    http://www.apache.org/licenses/license-2.0unless required by applicable law or agreed to in writing, softwaredistributed under the license is distributed on an "as is" basis,without warranties or conditions of any kind, either express or implied.see the license for the specific language governing permissions andlimitations under the license.