Skip to content

Repository files navigation

AWS SDK for Ruby - Version 3

GitterBuild StatusCode ClimateCoverage StatusDependency Status

This is version 3 of the aws-sdk gem. Version 2 can be found at branch:

Links of Interest

Change Log

Change Log now can be found at each gem root path, e.g. change log for aws-sdk-s3 gem can be found at /gems/aws-sdk-s3/CHANGELOG.mdhere. The change log is also accessible via RubyGems.org page under "LINKS" section for changelog.

Installation

The AWS SDK for Ruby is available from RubyGems. aws-sdk gem contains every available AWS service gem support. Please use a major version when expressing a dependency on aws-sdk.

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

With version 3 modularization, you can also pick the specific AWS service gem to install. Please use a major version when expressing a dependency on service gems.

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

Upgrading Guide

Version 3 modularizes the monolithic SDK into service specific gems. Aside from gem packaging differences, version 3 interfaces are backwards compatible with version 2. Following guide contains instructions for both version 1 and version 2 SDK.

Upgrade from version 2

  1. If you depend on aws-sdk or aws-sdk-resources, you don't need to change anything. Meanwhile we recommend you to revisit following options to explore modularization benefits.

  2. If you depend on aws-sdk-core, you must replace this dependency with one of following options. This is because aws-sdk-core now only contains shared utilities.

Options

  1. If you want to keep every AWS service gems in your project, simply keep/switch to aws-sdk
# Gemfilegem'aws-sdk','~> 3'# or in coderequire'aws-sdk'
  1. If you want to choose several AWS service gems in your project specifically, try following:
# Gemfilegem'aws-sdk-s3','~> 1'gem'aws-sdk-ec2','~> 1'
...
# or in coderequire'aws-sdk-s3'require'aws-sdk-ec2'
...

Upgrade from version 1

If you are using SDK version 1 and version 2 together in your application guided by our official blog post, then you might have either aws-sdk ~> 2 or aws-sdk-resources ~> 2 exists in your project, you can simply update it to ~> 3 or using separate service gems as described in version 2 upgrade options.

For addtional information of migrating from Version 1 to Version 2, please follow V1 to V2 migration guide.

Addtional Information

Getting Help

Please use these community resources for getting help. We use the GitHub issues for tracking bugs and feature requests and have limited bandwidth to address them.

  • Ask a question on StackOverflow and tag it with aws-sdk-ruby
  • Come join the AWS SDK for Ruby Gitter Channel
  • Open a support ticket with AWS Support, if it turns out that you may have found a bug, please open an issue
  • If in doubt as to whether your issue is a question about how to use AWS or a potential SDK issue, feel free to open a GitHub issue on this repo.

Opening Issues

If you encounter a bug with aws-sdk-ruby we would like to hear about it. Search the existing issues and try to make sure your problem doesn’t already exist before opening a new issue. It’s helpful if you include the version of aws-sdk-ruby, ruby version and OS you’re using. Please include a stack trace and reduced repro case when appropriate, too.

The GitHub issues are intended for bug reports and feature requests. For help and questions with using aws-sdk-ruby please make use of the resources listed in the Getting Help section.

FEATURE_REQUEST.md in particular is a good way to signal your interest in a feature or issue. There are limited resources available for handling issues and by keeping the list of open issues lean we can respond in a timely manner.

Configuration

You will need to configure credentials and a region, either in configuration files or environment variables, 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'] and ENV['AWS_SECRET_ACCESS_KEY']
  • Unless ENV['AWS_SDK_CONFIG_OPT_OUT'] is set, the shared configuration files (~/.aws/credentials and ~/.aws/config) will be checked for a role_arn and source_profile, which if present will be used to attempt to assume a role.
  • The shared credentials ini file at ~/.aws/credentials (more information)
    • Unless ENV['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.
  • If using ~/.aws/config or ~/.aws/credentials a :profile option can be used to choose the proper credentials.

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']
  • Unless ENV['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.

Configuration Options

You can also configure default credentials and region via Aws.config. In version 2, Aws.config is a vanilla Ruby hash, not a method like it was in version 1. The Aws.config hash takes precedence over environment variables.

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

Valid region and credentials options are:

You may also pass configuration options directly to resource and client constructors. These options take precedence over the environment and Aws.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 to never commit credentials to source control. We strongly recommended 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'])

API Clients

Construct a service client to make API calls. Each client provides a 1-to-1 mapping of methods to API operations. Refer to the API documentation for 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 return structured 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

Paging Responses

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 object is 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 methods that 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

Waiters are utility methods that poll for a particular state. To invoke a waiter, 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 can configure these per call to #wait_until. You can also register callbacks that are triggered before each polling attempt and before waiting. See the API documentation for more examples and for a list of supported waiters per service.

Resource Interfaces

Resource interfaces are object oriented classes that represent actual resources in AWS. Resource interfaces built on top of API clients and provide additional functionality. Each service gem contains its own resource interface.

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

REPL - AWS Interactive Console

The aws-sdk gem ships with a REPL that provides a simple way to test the Ruby SDK. You can access the REPL by running aws-v3.rb from the command line.

$ aws-v3.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-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:

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

Versioning

This project uses semantic versioning. You can safely express a dependency on a major version and expect all minor and patch versions to be backwards compatible.

Supported Services

Service NameService Modulegem_nameAPI Version
AWS AppSyncAws::AppSyncaws-sdk-appsync2017-07-25
AWS Application Discovery ServiceAws::ApplicationDiscoveryServiceaws-sdk-applicationdiscoveryservice2015-11-01
AWS Auto Scaling PlansAws::AutoScalingPlansaws-sdk-autoscalingplans2018-01-06
AWS BatchAws::Batchaws-sdk-batch2016-08-10
AWS BudgetsAws::Budgetsaws-sdk-budgets2016-10-20
AWS Certificate ManagerAws::ACMaws-sdk-acm2015-12-08
AWS Certificate Manager Private Certificate AuthorityAws::ACMPCAaws-sdk-acmpca2017-08-22
AWS Cloud9Aws::Cloud9aws-sdk-cloud92017-09-23
AWS CloudFormationAws::CloudFormationaws-sdk-cloudformation2010-05-15
AWS CloudHSM V2Aws::CloudHSMV2aws-sdk-cloudhsmv22017-04-28
AWS CloudTrailAws::CloudTrailaws-sdk-cloudtrail2013-11-01
AWS CodeBuildAws::CodeBuildaws-sdk-codebuild2016-10-06
AWS CodeCommitAws::CodeCommitaws-sdk-codecommit2015-04-13
AWS CodeDeployAws::CodeDeployaws-sdk-codedeploy2014-10-06
AWS CodePipelineAws::CodePipelineaws-sdk-codepipeline2015-07-09
AWS CodeStarAws::CodeStaraws-sdk-codestar2017-04-19
AWS ConfigAws::ConfigServiceaws-sdk-configservice2014-11-12
AWS Cost Explorer ServiceAws::CostExploreraws-sdk-costexplorer2017-10-25
AWS Cost and Usage Report ServiceAws::CostandUsageReportServiceaws-sdk-costandusagereportservice2017-01-06
AWS Data PipelineAws::DataPipelineaws-sdk-datapipeline2012-10-29
AWS Database Migration ServiceAws::DatabaseMigrationServiceaws-sdk-databasemigrationservice2016-01-01
AWS Device FarmAws::DeviceFarmaws-sdk-devicefarm2015-06-23
AWS Direct ConnectAws::DirectConnectaws-sdk-directconnect2012-10-25
AWS Directory ServiceAws::DirectoryServiceaws-sdk-directoryservice2015-04-16
AWS Elastic BeanstalkAws::ElasticBeanstalkaws-sdk-elasticbeanstalk2010-12-01
AWS Elemental MediaConvertAws::MediaConvertaws-sdk-mediaconvert2017-08-29
AWS Elemental MediaLiveAws::MediaLiveaws-sdk-medialive2017-10-14
AWS Elemental MediaPackageAws::MediaPackageaws-sdk-mediapackage2017-10-12
AWS Elemental MediaStoreAws::MediaStoreaws-sdk-mediastore2017-09-01
AWS Elemental MediaStore Data PlaneAws::MediaStoreDataaws-sdk-mediastoredata2017-09-01
AWS GlueAws::Glueaws-sdk-glue2017-03-31
AWS GreengrassAws::Greengrassaws-sdk-greengrass2017-06-07
AWS Health APIs and NotificationsAws::Healthaws-sdk-health2016-08-04
AWS Identity and Access ManagementAws::IAMaws-sdk-iam2010-05-08
AWS Import/ExportAws::ImportExportaws-sdk-importexport2010-06-01
AWS IoTAws::IoTaws-sdk-iot2015-05-28
AWS IoT 1-Click Devices ServiceAws::IoT1ClickDevicesServiceaws-sdk-iot1clickdevicesservice2018-05-14
AWS IoT 1-Click Projects ServiceAws::IoT1ClickProjectsaws-sdk-iot1clickprojects2018-05-14
AWS IoT AnalyticsAws::IoTAnalyticsaws-sdk-iotanalytics2017-11-27
AWS IoT Data PlaneAws::IoTDataPlaneaws-sdk-iotdataplane2015-05-28
AWS IoT Jobs Data PlaneAws::IoTJobsDataPlaneaws-sdk-iotjobsdataplane2017-09-29
AWS Key Management ServiceAws::KMSaws-sdk-kms2014-11-01
AWS LambdaAws::LambdaPreviewaws-sdk-lambdapreview2014-11-11
AWS LambdaAws::Lambdaaws-sdk-lambda2015-03-31
AWS Marketplace Commerce AnalyticsAws::MarketplaceCommerceAnalyticsaws-sdk-marketplacecommerceanalytics2015-07-01
AWS Marketplace Entitlement ServiceAws::MarketplaceEntitlementServiceaws-sdk-marketplaceentitlementservice2017-01-11
AWS MediaTailorAws::MediaTailoraws-sdk-mediatailor2018-04-23
AWS Migration HubAws::MigrationHubaws-sdk-migrationhub2017-05-31
AWS MobileAws::Mobileaws-sdk-mobile2017-07-01
AWS OpsWorksAws::OpsWorksaws-sdk-opsworks2013-02-18
AWS OpsWorks for Chef AutomateAws::OpsWorksCMaws-sdk-opsworkscm2016-11-01
AWS OrganizationsAws::Organizationsaws-sdk-organizations2016-11-28
AWS Performance InsightsAws::PIaws-sdk-pi2018-02-27
AWS Price List ServiceAws::Pricingaws-sdk-pricing2017-10-15
AWS Resource GroupsAws::ResourceGroupsaws-sdk-resourcegroups2017-11-27
AWS Resource Groups Tagging APIAws::ResourceGroupsTaggingAPIaws-sdk-resourcegroupstaggingapi2017-01-26
AWS Secrets ManagerAws::SecretsManageraws-sdk-secretsmanager2017-10-17
AWS Security Token ServiceAws::STSaws-sdk-core2011-06-15
AWS Server Migration ServiceAws::SMSaws-sdk-sms2016-10-24
AWS Service CatalogAws::ServiceCatalogaws-sdk-servicecatalog2015-12-10
AWS ShieldAws::Shieldaws-sdk-shield2016-06-02
AWS SignerAws::Signeraws-sdk-signer2017-08-25
AWS Step FunctionsAws::Statesaws-sdk-states2016-11-23
AWS Storage GatewayAws::StorageGatewayaws-sdk-storagegateway2013-06-30
AWS SupportAws::Supportaws-sdk-support2013-04-15
AWS WAFAws::WAFaws-sdk-waf2015-08-24
AWS WAF RegionalAws::WAFRegionalaws-sdk-wafregional2016-11-28
AWS X-RayAws::XRayaws-sdk-xray2016-04-12
AWSMarketplace MeteringAws::MarketplaceMeteringaws-sdk-marketplacemetering2016-01-14
AWSServerlessApplicationRepositoryAws::ServerlessApplicationRepositoryaws-sdk-serverlessapplicationrepository2017-09-08
Alexa For BusinessAws::AlexaForBusinessaws-sdk-alexaforbusiness2017-11-09
Amazon API GatewayAws::APIGatewayaws-sdk-apigateway2015-07-09
Amazon AppStreamAws::AppStreamaws-sdk-appstream2016-12-01
Amazon AthenaAws::Athenaaws-sdk-athena2017-05-18
Amazon CloudDirectoryAws::CloudDirectoryaws-sdk-clouddirectory2017-01-11
Amazon CloudFrontAws::CloudFrontaws-sdk-cloudfront2018-06-18
Amazon CloudHSMAws::CloudHSMaws-sdk-cloudhsm2014-05-30
Amazon CloudSearchAws::CloudSearchaws-sdk-cloudsearch2013-01-01
Amazon CloudSearch DomainAws::CloudSearchDomainaws-sdk-cloudsearchdomain2013-01-01
Amazon CloudWatchAws::CloudWatchaws-sdk-cloudwatch2010-08-01
Amazon CloudWatch EventsAws::CloudWatchEventsaws-sdk-cloudwatchevents2015-10-07
Amazon CloudWatch LogsAws::CloudWatchLogsaws-sdk-cloudwatchlogs2014-03-28
Amazon Cognito IdentityAws::CognitoIdentityaws-sdk-cognitoidentity2014-06-30
Amazon Cognito Identity ProviderAws::CognitoIdentityProvideraws-sdk-cognitoidentityprovider2016-04-18
Amazon Cognito SyncAws::CognitoSyncaws-sdk-cognitosync2014-06-30
Amazon ComprehendAws::Comprehendaws-sdk-comprehend2017-11-27
Amazon Connect ServiceAws::Connectaws-sdk-connect2017-08-08
Amazon Data Lifecycle ManagerAws::DLMaws-sdk-dlm2018-01-12
Amazon DynamoDBAws::DynamoDBaws-sdk-dynamodb2012-08-10
Amazon DynamoDB Accelerator (DAX)Aws::DAXaws-sdk-dax2017-04-19
Amazon DynamoDB StreamsAws::DynamoDBStreamsaws-sdk-dynamodbstreams2012-08-10
Amazon EC2 Container RegistryAws::ECRaws-sdk-ecr2015-09-21
Amazon EC2 Container ServiceAws::ECSaws-sdk-ecs2014-11-13
Amazon ElastiCacheAws::ElastiCacheaws-sdk-elasticache2015-02-02
Amazon Elastic Compute CloudAws::EC2aws-sdk-ec22016-11-15
Amazon Elastic Container Service for KubernetesAws::EKSaws-sdk-eks2017-11-01
Amazon Elastic File SystemAws::EFSaws-sdk-efs2015-02-01
Amazon Elastic MapReduceAws::EMRaws-sdk-emr2009-03-31
Amazon Elastic TranscoderAws::ElasticTranscoderaws-sdk-elastictranscoder2012-09-25
Amazon Elasticsearch ServiceAws::ElasticsearchServiceaws-sdk-elasticsearchservice2015-01-01
Amazon GameLiftAws::GameLiftaws-sdk-gamelift2015-10-01
Amazon GlacierAws::Glacieraws-sdk-glacier2012-06-01
Amazon GuardDutyAws::GuardDutyaws-sdk-guardduty2017-11-28
Amazon Import/Export SnowballAws::Snowballaws-sdk-snowball2016-06-30
Amazon InspectorAws::Inspectoraws-sdk-inspector2016-02-16
Amazon KinesisAws::Kinesisaws-sdk-kinesis2013-12-02
Amazon Kinesis AnalyticsAws::KinesisAnalyticsaws-sdk-kinesisanalytics2015-08-14
Amazon Kinesis FirehoseAws::Firehoseaws-sdk-firehose2015-08-04
Amazon Kinesis Video StreamsAws::KinesisVideoaws-sdk-kinesisvideo2017-09-30
Amazon Kinesis Video Streams Archived MediaAws::KinesisVideoArchivedMediaaws-sdk-kinesisvideoarchivedmedia2017-09-30
Amazon Kinesis Video Streams MediaAws::KinesisVideoMediaaws-sdk-kinesisvideomedia2017-09-30
Amazon Lex Model Building ServiceAws::LexModelBuildingServiceaws-sdk-lexmodelbuildingservice2017-04-19
Amazon Lex Runtime ServiceAws::Lexaws-sdk-lex2016-11-28
Amazon LightsailAws::Lightsailaws-sdk-lightsail2016-11-28
Amazon Machine LearningAws::MachineLearningaws-sdk-machinelearning2014-12-12
Amazon MacieAws::Macieaws-sdk-macie2017-12-19
Amazon Mechanical TurkAws::MTurkaws-sdk-mturk2017-01-17
Amazon NeptuneAws::Neptuneaws-sdk-neptune2014-10-31
Amazon PinpointAws::Pinpointaws-sdk-pinpoint2016-12-01
Amazon PollyAws::Pollyaws-sdk-polly2016-06-10
Amazon RedshiftAws::Redshiftaws-sdk-redshift2012-12-01
Amazon RekognitionAws::Rekognitionaws-sdk-rekognition2016-06-27
Amazon Relational Database ServiceAws::RDSaws-sdk-rds2014-10-31
Amazon Route 53Aws::Route53aws-sdk-route532013-04-01
Amazon Route 53 Auto NamingAws::ServiceDiscoveryaws-sdk-servicediscovery2017-03-14
Amazon Route 53 DomainsAws::Route53Domainsaws-sdk-route53domains2014-05-15
Amazon SageMaker RuntimeAws::SageMakerRuntimeaws-sdk-sagemakerruntime2017-05-13
Amazon SageMaker ServiceAws::SageMakeraws-sdk-sagemaker2017-07-24
Amazon Simple Email ServiceAws::SESaws-sdk-ses2010-12-01
Amazon Simple Notification ServiceAws::SNSaws-sdk-sns2010-03-31
Amazon Simple Queue ServiceAws::SQSaws-sdk-sqs2012-11-05
Amazon Simple Storage ServiceAws::S3aws-sdk-s32006-03-01
Amazon Simple Systems Manager (SSM)Aws::SSMaws-sdk-ssm2014-11-06
Amazon Simple Workflow ServiceAws::SWFaws-sdk-swf2012-01-25
Amazon SimpleDBAws::SimpleDBaws-sdk-simpledb2009-04-15
Amazon Transcribe ServiceAws::TranscribeServiceaws-sdk-transcribeservice2017-10-26
Amazon TranslateAws::Translateaws-sdk-translate2017-07-01
Amazon WorkDocsAws::WorkDocsaws-sdk-workdocs2016-05-01
Amazon WorkMailAws::WorkMailaws-sdk-workmail2017-10-01
Amazon WorkSpacesAws::WorkSpacesaws-sdk-workspaces2015-04-08
AmazonMQAws::MQaws-sdk-mq2017-11-27
Application Auto ScalingAws::ApplicationAutoScalingaws-sdk-applicationautoscaling2016-02-06
Auto ScalingAws::AutoScalingaws-sdk-autoscaling2011-01-01
Elastic Load BalancingAws::ElasticLoadBalancingaws-sdk-elasticloadbalancing2012-06-01
Elastic Load BalancingAws::ElasticLoadBalancingV2aws-sdk-elasticloadbalancingv22015-12-01
Firewall Management ServiceAws::FMSaws-sdk-fms2018-01-01

License

This library is distributed under the Apache 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.0
unless required by applicable law or agreed to in writing, software
distributed 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 and
limitations under the license.

About

The official AWS SDK for Ruby.

Resources

Code of conduct

Contributing

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages