Project

s3-client

0.0
No commit activity in last 3 years
No release in over 3 years
It is a simple AWS S3 library for Ruby
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.3
~> 10.0
~> 3.1.0

Runtime

~> 0.0.4
~> 2.8.0
~> 1.1.4
 Project Readme

S3::Client

It is a simple AWS S3 library for Ruby

Installation

$ gem install s3-client

Usage

Generate Client

Set access key ID and secret access key, and generate client.

S3::Client.new(<access_key_id>, <secret_access_key>, <Option>)

About Parameters

In addition to the access key ID and secret access key, the options shown in the table below can be set.

Name Required Type Default Overview
access_key_id yes String AccessKeyId
secret_access_key yes String SecretAccessKey
endpoint no String https://s3.ap-northeast-1.amazonaws.com Amazon S3 Resion
location no String ap-northeast-1 Amazon S3 Region
force_path_style no String false "true" generates and accesses URL in path format. "false" creates and accesses a virtual host type URL.
debug no Boolean false show verbose

Sample

require 's3/client'

access_key_id = ENV['AWS_ACCESS_KEY_ID']
secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
options = {
  debug: true
}

client = S3::Client.new(access_key_id, secret_access_key, options)

Error Response

In case of errors caused by API, an exception (S3::Client::APIFailure) occurs.
The following information is stored in S3::Client::APIFailure.

Name Overview
message API runtime information
api_code Error code
api_message Error message
api_status Error status
api_request_id Request ID on error
api_resource Path information on error

In addition, other error responses are as follows.

Name Overview
ParameterInvalid Invalid parameter was set
APIOptionInvalid Invalid API option set

Detail of Function

  • Get bucket list
  • Get bucket
  • Create bucket
  • Delete bucket
  • Get object list
  • Get object
  • Create object
  • Delete object
  • Generate signature

Get bucket list

client.buckets.each do |bucket|
  puts bucket.name
  #=> bucket1
  #=> bucket2
end

Get bucket

Gets the specified bucket.

# Select bucket
bucket = client.buckets['bucket']

puts bucket.name
#=> bucket

Create bucket

bucket = client.buckets.create('bucket')

puts bucket.name
#=> bucket

It can also be created by the following method.

bucket = client.create_bucket('bucket')

puts bucket.name
#=> bucket

Delete bucket

bucket = client.buckets['bucket']

bucket.delete

It can also be deleted by the following method.

client.delete_bucket('bucket')

Get object list

bucket = client.buckets['bucket']

bucket.objects.each do |object|
  puts object.name
  #=> object1/
  #=> object1/test1
  #=> object2/
end

# It is possible to search by specifying a prefix
bucket.objects.where(prefix: 'object1').each do |object|
  puts object.name
  #=> object1/
  #=> object1/test1
end

Example when delimiter is specified

# Data existing on S3
# /foo/photo/2009/index.html
# /foo/photo/2009/12/index.html
# /foo/photo/2010/index.html
# /foo/photo/2010/xmas.jpg
# /foo/photo/2010/01/index.html
# /foo/photo/2010/01/xmas.jpg
# /foo/photo/2010/02/index.html

bucket = client.buckets['bucket']

bucket.objects.where(prefix: '/foo/photo/2010/', delimiter: '/').each do |object|
  puts object.name
  #=> /foo/photo/2010/index.html
  #=> /foo/photo/2010/xmas.jpg
end

You can narrow down the objects by setting the following parameters of the where method.

Parameter Required Type Default Overview
prefix no String String for filtering with forward match
delimiter no String Object hierarchy delimiter

Get object

bucket = client.buckets['bucket']

object = bucket.objects['object1/test.gz']

puts object.name
#=> object1/test.gz

puts object.read
#=> "abcdefg"

# Read 3 bytes of data from object
puts object.read(0..2)
#=> "abc"

Create object

bucket = client.buckets['bucket']

object = bucket.objects['object1/test.json']

# String
object.write('testobject')

# Path
object.write(Pathname.new('./object_1.json'))

Multi-part upload is supported by passing options.

bucket = client.buckets['bucket']

object = bucket.objects['object1/test.json']

object.write(Pathname.new('./object_1.json'), multipart: true, jobs: 10, splitsz: 10_000_000)

When using multipart upload, you can specify the following options:

Parameter Required Type Default Overview
multipart no Boolean false Enable multipart upload
jobs no String 1 Number of parallel uploads
splitsz no Integer 104857600 Split size of the object. Please specify 5 MB or more.

Delete object

bucket = client.buckets['bucket']

object = bucket.objects['object1/test.json']

object.delete

It can also be deleted by the following method.

client.delete_object('bucket', 'object_1/test.json')

Generate signature

Create signed AWS S3 downloaded link.

expire_at = (Time.now + 60 * 60).to_i
bucket = 'bucket1'
object = 'object1/data'
signature = client.api.download_signature(expire_at, bucket, object)

url = File.join(client.endpoint, bucket, object)
puts "#{url}?AWSAccessKeyId=#{client.access_key_id}&Expires=#{expire_at}&Signature=#{signature}"
#=> https://s3.ap-northeast-1.amazonaws.com/bucket1/object1/data?AWSAccessKeyId=XXX&Expires=1522148801&Signature=XXX