class

Awscr::S3::Client

An S3 client for interacting with S3.

Creating an S3 Client

client = Client.new("region", "key", "secret")

Client with custom endpoint

client = Client.new("region", "key", "secret", endpoint: "http://test.com")

Client with custom signer algorithm

client = Client.new("region", "key", "secret", signer: :v2)

Creating an S3 Client with a session key, to use temporary credentials

client = Client.new("region", "key", "secret", "session_key")

Constructors

new(region : String, aws_access_key : String, aws_secret_key : String, aws_session_key : String | Nil = nil, endpoint : String | Nil = nil, signer : Symbol = :v4, client_factory : HttpClientFactory = DefaultHttpClientFactory.new)

Source

Instance methods

abort_multipart_upload(bucket : String, object : String, upload_id : String)

Aborts a multi part upload. Returns true if the abort was a success, false otherwise.

client = Client.new("region", "key", "secret")
resp = client.abort_multipart_upload("bucket1", "obj", "123")
p resp # => true

Source

batch_delete(bucket, keys : Array(String))

Batch deletes a list of object keys in a single request.

client = Client.new("region", "key", "secret")
resp = client.batch_delete("bucket1", ["obj", "obj2"])
p resp.success? # => true

Source

complete_multipart_upload(bucket : String, object : String, upload_id : String, parts : Array(Response::UploadPartOutput))

Complete a multipart upload

client = Client.new("region", "key", "secret")
resp = client.complete_multipart_upload("bucket1", "obj", "123", parts)
p resp.key # => obj

Source

copy_object(bucket, source : String, destination : String, headers : Hash(String, String) = {} of String => String)

Copy an object from source to destination in a bucket.

client = Client.new("region", "key", "secret")
client.copy_object("bucket1", "source_object", "destination_object")

Source

delete_bucket(bucket)

Delete a bucket, note: it must be empty

client = Client.new("region", "key", "secret")
resp = client.delete_bucket("test")
p resp # => true

Source

delete_object(bucket, object, headers : Hash(String, String) = Hash(String, String).new)

Delete an object from a bucket, returns true if successful, false otherwise.

client = Client.new("region", "key", "secret")
resp = client.delete_object("bucket1", "obj")
p resp # => true

Source

endpoint

Source

get_object(bucket, object : String, headers : Hash(String, String) = Hash(String, String).new)

Get the contents of an object in a bucket

client = Client.new("region", "key", "secret")
resp = client.get_object("bucket1", "obj")
p resp.body # => "MY DATA"

Source

get_object(bucket, object : String, headers : Hash(String, String) = Hash(String, String).new, &)

Get the contents of an object in a bucket as an IO object

client = Client.new("region", "key", "secret")
client.get_object("bucket1", "obj") do |resp|
  IO.copy(resp.body_io, STDOUT) # => "MY DATA"
end

Source

head_bucket(bucket)

Get information about a bucket, useful for determining if a bucket exists. Raises a Http::ServerError if the bucket does not exist.

client = Client.new("region", "key", "secret")
resp = client.head_bucket("bucket1")
p resp # => true

Source

head_object(bucket, object : String, headers : Hash(String, String) = Hash(String, String).new)

Get the metadata of an object in a bucket

client = Client.new("region", "key", "secret")
resp = client.head_object("bucket1", "obj")
p resp.size          # => 123
p resp.status        # => HTTP::Status::OK
p resp.last_modified # => "Wed, 19 Jun 2019 11:55:33 GMT"
p resp.etag          # => ""
p resp.meta          # => {"my_tag" => "my_value"}

Source

list_buckets

List s3 buckets

client = Client.new("region", "key", "secret")
resp = client.list_buckets
p resp.buckets.map(&.name) # => ["bucket1", "bucket2"]

Source

list_objects(bucket, max_keys = nil, prefix = nil)

List all the items in a bucket

client = Client.new("region", "key", "secret")
resp = client.list_objects("bucket1", prefix: "test")
p resp.map(&.key) # => ["obj"]

Source

put_bucket(bucket, region : String | Nil = nil, headers : Hash(String, String) = Hash(String, String).new)

Create a bucket, optionally place it in a region.

client = Client.new("region", "key", "secret")
resp = client.create_bucket("test")
p resp # => true

Source

put_object(bucket, object : String, body : IO | String | Bytes, headers : Hash(String, String) = Hash(String, String).new)

Add an object to a bucket.

client = Client.new("region", "key", "secret")
resp = client.put_object("bucket1", "obj", "MY DATA")
p resp.key # => "obj"

Source

region

Source

start_multipart_upload(bucket : String, object : String, headers : Hash(String, String) = Hash(String, String).new)

Start a multipart upload

client = Client.new("region", "key", "secret")
resp = client.start_multipart_upload("bucket1", "obj")
p resp.upload_id # => someid

Source

upload_part(bucket : String, object : String, upload_id : String, part_number : Int32, part : IO | String)

Upload a part, for use in multipart uploading

client = Client.new("region", "key", "secret")
resp = client.upload_part("bucket1", "obj", "someid", 123, "MY DATA")
p resp.upload_id # => someid

Source