Merge pull request #1342 from awsdocs/pccornel-ruby-s3

Added new Amazon S3 code examples and units test for Ruby to upload an item to a folder and to upload multiple items. Also fixed several minor reported RuboCop issues

Author: brmur

ruby/example_code/s3/auth_federation_token_request_test.rb

@@ -2,14 +2,17 @@
 # SPDX - License - Identifier: Apache - 2.0
 
 # This code example allows a federated user with a limited set of
-# permissions to list the objects in the specified Amazon S3 bucket.
+# permissions to list the objects in an Amazon S3 bucket.
+
+# Prerequisites:
+# - An existing Amazon S3 bucket.
 
 # snippet-start:[s3.ruby.auth_federation_token_request_test.rb]
 require 'aws-sdk-s3'
 require 'aws-sdk-iam'
 require 'json'
 
-# Checks to see whether the specified user exists in IAM; otherwise,
+# Checks to see whether a user exists in IAM; otherwise,
 # creates the user.
 #
 # @param iam [Aws::IAM::Client] An initialized IAM client.
@@ -18,9 +21,7 @@
 # @example
 # iam = Aws::IAM::Client.new(region: 'us-east-1')
 # user = get_user(iam, 'my-user')
-# unless user.user_name
-# exit 1
-# end
+# exit 1 unless user.user_name
 # puts "User's name: #{user.user_name}"
 def get_user(iam, user_name)
  puts "Checking for a user with the name '#{user_name}'..."
@@ -38,7 +39,7 @@ def get_user(iam, user_name)
  puts "Error while accessing or creating the user named '#{user_name}': #{e.message}"
 end
 
-# Gets temporary AWS credentials for the specified IAM user and permissions.
+# Gets temporary AWS credentials for an IAM user with the specified permissions.
 #
 # @param sts [Aws::STS::Client] An initialized AWS STS client.
 # @param duration_seconds [Integer] The number of seconds for valid credentials.
@@ -58,9 +59,7 @@ def get_user(iam, user_name)
 # ]
 # }
 # )
-# unless credentials.access_key_id
-# exit 1
-# end
+# exit 1 unless credentials.access_key_id
 # puts "Access key ID: #{credentials.access_key_id}"
 def get_temporary_credentials(sts, duration_seconds, user_name, policy)
  response = sts.get_federation_token(
@@ -73,19 +72,17 @@ def get_temporary_credentials(sts, duration_seconds, user_name, policy)
  puts "Error while getting federation token: #{e.message}"
 end
 
-# Lists the keys and ETags for the objects in the specified Amazon S3 bucket.
+# Lists the keys and ETags for the objects in an Amazon S3 bucket.
 #
-# @param s3 [Aws::S3::Client] An initialized Amazon S3 client.
+# @param s3_client [Aws::S3::Client] An initialized Amazon S3 client.
 # @param bucket_name [String] The bucket's name.
 # @return [Boolean] true if the objects were listed; otherwise, false.
 # @example
-# s3 = Aws::S3::Client.new(region: 'us-east-1')
-# unless can_list_objects_in_bucket?(s3, 'my-bucket')
-# exit 1
-# end
-def can_list_objects_in_bucket?(s3, bucket_name)
+# s3_client = Aws::S3::Client.new(region: 'us-east-1')
+# exit 1 unless list_objects_in_bucket?(s3_client, 'my-bucket')
+def list_objects_in_bucket?(s3_client, bucket_name)
  puts "Accessing the contents of the bucket named '#{bucket_name}'..."
- response = s3.list_objects_v2(
+ response = s3_client.list_objects_v2(
  bucket: bucket_name,
  max_keys: 50
  )
@@ -102,7 +99,6 @@ def can_list_objects_in_bucket?(s3, bucket_name)
  return true
 rescue StandardError => e
  puts "Error while accessing the bucket named '#{bucket_name}': #{e.message}"
- return false
 end
 # snippet-end:[s3.ruby.auth_federation_token_request_test.rb]
 
@@ -115,9 +111,7 @@ def can_list_objects_in_bucket?(s3, bucket_name)
 iam = Aws::IAM::Client.new(region: region)
 user = get_user(iam, user_name)
 
-unless user.user_name
- exit 1
-end
+exit 1 unless user.user_name
 
 puts "User's name: #{user.user_name}"
 sts = Aws::STS::Client.new(region: region)
@@ -133,14 +127,10 @@ def can_list_objects_in_bucket?(s3, bucket_name)
  }
 )
 
-unless credentials.access_key_id
- exit 1
-end
+exit 1 unless credentials.access_key_id
 
 puts "Access key ID: #{credentials.access_key_id}"
-s3 = Aws::S3::Client.new(region: region, credentials: credentials)
+s3_client = Aws::S3::Client.new(region: region, credentials: credentials)
 
-unless can_list_objects_in_bucket?(s3, bucket_name)
- exit 1
-end
+exit 1 unless list_objects_in_bucket?(s3_client, bucket_name)
 =end

ruby/example_code/s3/auth_request_object_keys.rb

@@ -1,22 +1,23 @@
 # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 # SPDX - License - Identifier: Apache - 2.0
 
+# Prerequisites:
+# - An Amazon S3 bucket.
+
 # snippet-start:[s3.ruby.auth_request_object_keys.rb]
 require 'aws-sdk-s3'
 
-# Prints the list of objects in the specified Amazon S3 bucket.
+# Prints the list of objects in an Amazon S3 bucket.
 #
-# @param s3 [Aws::S3::Client] An initialized Amazon S3 client.
+# @param s3_client [Aws::S3::Client] An initialized Amazon S3 client.
 # @param bucket_name [String] The bucket's name.
 # @return [Boolean] true if all operations succeed; otherwise, false.
 # @example
-# s3 = Aws::S3::Client.new(region: 'us-east-1')
-# unless can_list_bucket_objects?(s3, 'my-bucket')
-# exit 1
-# end
-def can_list_bucket_objects?(s3, bucket_name)
+# s3_client = Aws::S3::Client.new(region: 'us-east-1')
+# exit 1 unless list_bucket_objects?(s3_client, 'my-bucket')
+def list_bucket_objects?(s3_client, bucket_name)
  puts "Accessing the bucket named '#{bucket_name}'..."
- objects = s3.list_objects_v2(
+ objects = s3_client.list_objects_v2(
  bucket: bucket_name,
  max_keys: 50
  )
@@ -37,13 +38,11 @@ def can_list_bucket_objects?(s3, bucket_name)
 end
 # snippet-end:[s3.ruby.auth_request_object_keys.rb]
 
-# Full example:
+# Full example call:
 =begin
 region = 'us-east-1'
 bucket_name = 'my-bucket'
-s3 = Aws::S3::Client.new(region: region)
+s3_client = Aws::S3::Client.new(region: region)
 
-unless can_list_bucket_objects?(s3, bucket_name)
- exit 1
-end
+exit 1 unless list_bucket_objects?(s3_client, bucket_name)
 =end

ruby/example_code/s3/auth_request_test.rb

@@ -1,74 +1,64 @@
-#**
- #* Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
- #*
- #* This file is licensed under the Apache License, Version 2.0 (the "License").
- #* You may not use this file except in compliance with the License. A copy of
- #* the License is located at
- #*
- #* http://aws.amazon.com/apache2.0/
- #*
- #* This file 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.
-#**
-# snippet-sourcedescription:[auth_request_test.rb uses the credentials in a shared AWS credentials file on a local computer to authenticate a request to get all of the object key names in a specific bucket.] 
-# snippet-service:[s3]
-# snippet-keyword:[Ruby]
-# snippet-sourcesyntax:[ruby]
-# snippet-keyword:[Amazon S3]
-# snippet-keyword:[Code Sample]
-# snippet-keyword:[GET Bucket]
-# snippet-sourcetype:[full-example]
-# snippet-sourcedate:[2019-02-11]
-# snippet-sourceauthor:[AWS]
-# snippet-start:[s3.ruby.auth_request_test.rb]
-# This snippet example does the following:
-# Creates an instance of the Aws::S3::Resource class. 
-# Makes a request to Amazon S3 by enumerating objects in a bucket using the bucket method of Aws::S3::Resource. 
-# The client generates the necessary signature value from the credentials in the AWS credentials file on your computer, 
-# and includes it in the request it sends to Amazon S3.
-# Prints the array of object key names to the terminal.
-# The credentials that are used for this example come from a local AWS credentials file on the computer that is running this application. 
-# The credentials are for an IAM user who can list objects in the bucket that the user specifies when they run the application.
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX - License - Identifier: Apache - 2.0
 
-# Use the Amazon S3 modularized gem for version 3 of the AWS Ruby SDK.
-require 'aws-sdk-s3'
+# Prints a list of objects in an Amazon S3 bucket.
 
-# Usage: ruby auth_request_test.rb OPERATION BUCKET
-# Currently only the list operation is supported
+# Prerequisites:
+#  - An Amazon S3 bucket.
 
-# The operation to perform on the bucket.
-operation = 'list' # default
-operation = ARGV[0] if (ARGV.length > 0)
+# snippet-start:[s3.ruby.auth_request_test.rb]
+require 'aws-sdk-s3'
 
-if ARGV.length > 1
- bucket_name = ARGV[1]
-else
- exit 1
+# Prints command line usage information.
+def print_usage()
+ puts 'Incorrect command line arguments provided or -h or --help specified.'
+ puts 'Usage: auth_request_test.rb <bucket>'
+ puts ' <bucket> The name of the bucket containing the objects to list.'
+ puts 'Example: auth_request_test.rb my-bucket'
 end
 
-# Get an Amazon S3 resource.
-s3 = Aws::S3::Resource.new(region: 'us-west-2')
-
-# Get the bucket by name.
-bucket = s3.bucket(bucket_name)
-
-case operation
+# Checks whether the correct command line arguments were provided.
+# On failure, prints command line usage information and then exits.
+def check_inputs()
+ if ARGV.length != 1 || ARGV[0] == '-h' || ARGV[0] == '--help'
+ print_usage
+ exit 1
+ end
+end
 
-when 'list'
- if bucket.exists?
- # Enumerate the bucket contents and object etags.
- puts "Contents of '%s':" % bucket_name
- puts ' Name => GUID'
+# Prints the list of objects in the specified Amazon S3 bucket.
+#
+# @param s3_client [Aws::S3::Client] An initialized Amazon S3 client.
+# @param bucket_name [String] The bucket's name.
+# @return [Boolean] true if all operations succeed; otherwise, false.
+# @example
+# s3_client = Aws::S3::Client.new(region: 'us-east-1')
+# exit 1 unless can_list_bucket_objects?(s3_client, 'my-bucket')
+def list_bucket_objects?(s3_client, bucket_name)
+ puts "Accessing the bucket named '#{bucket_name}'..."
+ objects = s3_client.list_objects_v2(
+ bucket: bucket_name,
+ max_keys: 50
+ )
 
- bucket.objects.limit(50).each do |obj|
- puts " #{obj.key} => #{obj.etag}"
+ if objects.count.positive?
+ puts 'The object keys in this bucket are (first 50 objects):'
+ objects.contents.each do |object|
+ puts object.key
  end
  else
- puts "The bucket '%s' does not exist!" % bucket_name
+ puts 'No objects found in this bucket.'
  end
 
-else
- puts "Unknown operation: '%s'! Only list is supported." % operation
+ return true
+rescue StandardError => e
+ puts "Error while accessing the bucket named '#{bucket_name}': #{e.message}"
 end
 # snippet-end:[s3.ruby.auth_request_test.rb]
+
+# Full example call:
+=begin
+check_inputs
+s3_client = Aws::S3::Client.new(region: 'us-east-1')
+exit 1 unless list_bucket_objects?(s3_client, ARGV[0])
+=end

ruby/example_code/s3/metadata.yaml

@@ -15,4 +15,22 @@ files:
  - path: tests/test_auth_request_object_keys.rb
  services:
  - s3
+ - path: auth_request_test.rb
+ services:
+ - s3
+ - path: tests/test_auth_request_test.rb
+ services:
+ - s3
+ - path: s3-ruby-example-upload-item-to-folder.rb
+ services:
+ - s3
+ - path: tests/test_s3-ruby-example-upload-item-to-folder.rb
+ services:
+ - s3
+ - path: s3-ruby-examples-upload-multiple-items.rb
+ services:
+ - s3
+ - path: tests/test_s3-ruby-examples-upload-multiple-items.rb
+ services:
+ - s3
 ...