Repository files navigation

• API Documentation
• Developer Guide
• V3 Upgrading Guide
• AWS Developer Blog
• Github Discussions

The AWS SDK for Ruby is available from RubyGems. With V3 modularization, youshould pick the specific AWS service gems to install.

gem'aws-sdk-s3','~> 1'gem'aws-sdk-ec2','~> 1'

Alternatively, theaws-sdk gem contains every available AWS service gem. Thisgem is very large; it is recommended to use it only as a quick way to migratefrom V2 or if you depend on many AWS services.

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

Please use a pessimistic version constraint on the major version whendepending on service gems.

You will need to configure credentials and a region, either inconfiguration filesor environment variables, to make API calls. It is recommended that youprovide these via your environment. This makes it easier to rotate credentialsand 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. The location used can be changed with theAWS_CREDENTIALS_FILE ENV variable.
  • Credential options supported in this file are:
    • Static Credentials (aws_access_key_id,aws_secret_access_key,aws_session_token)
    • Assume Role Web Identity Credentials (web_identity_token_file,role_arn,source_profile)
    • Assume Role Credentials (role_arn,source_profile)
    • Process Credentials (credential_process)
    • SSO Credentials (sso_session,sso_account_id,sso_role_name,sso_region)
  • UnlessENV['AWS_SDK_CONFIG_OPT_OUT'] is set, the shared configuration ini file at~/.aws/config will also be parsed for credentials.
• From an instance profile when running on EC2 or from the ECS credential provider when running in an ECS container with that feature enabled.

Shared configuration is loaded only a single time, and credentials are provided statically at client creation time. Shared credentials do not refresh.

The SDK searches the following locations for a region:

• ENV['AWS_REGION']
• ENV['AMAZON_REGION']
• ENV['AWS_DEFAULT_REGION']
• UnlessENV['AWS_SDK_CONFIG_OPT_OUT'] is set, the shared configuration files (~/.aws/credentials and~/.aws/config) will also be checked for a region selection.

The region is used to construct an SSL endpoint. If you need to connect to a non-standard endpoint, you may specify the:endpoint option.

You can also configure default credentials and the region via theAws.confighash. TheAws.config hash takes precedence over environment variables.

require'aws-sdk-core'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 page for a list of supported regions by service.
• :credentials - An instance of one of the following classes:
  • Aws::Credentials
  • Aws::AssumeRoleWebIdentityCredentials
  • Aws::AssumeRoleCredentials
  • Aws::SharedCredentials
  • Aws::ProcessCredentials
  • Aws::InstanceProfileCredentials
  • Aws::ECSCredentials
  • Aws::CognitoIdentityCredentials

You may also pass configuration options directly to Client and Resourceconstructors. These options take precedence over the environment andAws.config defaults. A:profile Client option can also be used to choose aspecific profile defined in your configuration file.

# using a credentials objectec2=Aws::EC2::Client.new(region:'us-west-2',credentials:credentials)# using a profile nameec2=Aws::EC2::Client.new(profile:'my_profile')

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

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

For more information on how to configure credentials, see the developer guideforconfiguring AWS SDK for Ruby.

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',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 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.

Only a few services implement a resource interface. They are defined by handin JSON and have limitations. Please use the Client API instead.

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 gem ships with a REPL that provides a simple way to testthe Ruby SDK. You can access the REPL by runningaws-v3.rb from the command line.

$aws-v3.rb[1]pry(Aws)>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-v3.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:

• s3 =>#<Aws::S3::Client>
• ec2 =>#<Aws::EC2::Client>
• etc

The AWS SDK for Ruby has optional functionality that requires theAWS Common Runtime (CRT)bindings to be included as a dependency with your application. This functionality includes:

• CRC-32c support forS3 Additional Checksums

AWS CRT bindings are in developer preview and are available in thetheaws-crt gem. You can install them by adding theaws-crt gem to your Gemfile.

Please use any of these resources for getting help:

• Ask a question onGithub Discussions.
• Ask a question on StackOverflow andtag it withaws-sdk-ruby.
• Open a support ticket withAWS Support.

For information about maintenance and support for SDK major versions and their underlying dependencies, see the following in theAWS SDKs and Tools Shared Configuration and Credentials Reference Guide:

• AWS SDKs and Tools Maintenance Policy
• AWS SDKs and Tools Version Support Matrix

If you encounter a bug or have a feature request, we would like to hear aboutit. Search the existing issues and try to make sure your problem doesn’t alreadyexist before opening a new issue.

The GitHub issues are intended for bug reports and feature requests. For helpand questions with usingaws-sdk-ruby please make use of the resources listedin the Getting Help section.

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

A CHANGELOG can be found at each gem's root path (i.e.aws-sdk-s3 can be foundatgems/aws-sdk-s3/CHANGELOG.md). The CHANGELOG is also accessible via theRubyGems.org page under "LINKS" section.

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.