aws.sdk.s3 documentation
Functions to access the Amazon S3 storage service.
Each function takes a map of credentials as its first argument. The
credentials map should contain an :access-key key and a :secret-key key,
and optionally an :endpoint key to denote an AWS endpoint.
bucket-exists?
(bucket-exists? cred name)
Returns true if the supplied bucket name already exists in S3.
copy-object
(copy-object cred bucket src-key dest-key)(copy-object cred src-bucket src-key dest-bucket dest-key)
Copy an existing S3 object to another key. Returns a map containing
the data returned from S3
create-bucket
(create-bucket cred name)
Create a new S3 bucket with the supplied name.
delete-bucket
(delete-bucket cred name)
Delete the S3 bucket with the supplied name.
delete-object
(delete-object cred bucket key)
Delete an object from an S3 bucket.
delete-version
(delete-version cred bucket key version-id)
Deletes a specific version of the specified object in the specified bucket.
generate-presigned-url
(generate-presigned-url cred bucket key & [options])
Return a presigned URL for an S3 object. Accepts the following options:
:expires - the date at which the URL will expire (defaults to 1 day from now)
:http-method - the HTTP method for the URL (defaults to :get)
get-bucket-acl
(get-bucket-acl cred bucket)
Get the access control list (ACL) for the supplied bucket. The ACL is a map
containing two keys:
:owner - the owner of the ACL
:grants - a set of access permissions granted
The grants themselves are maps with keys:
:grantee - the individual or group being granted access
:permission - the type of permission (:read, :write, :read-acp, :write-acp or
:full-control).get-object
(get-object cred bucket key)
Get an object from an S3 bucket. The object is returned as a map with the
following keys:
:content - an InputStream to the content
:metadata - a map of the object's metadata
:bucket - the name of the bucket
:key - the object's key
get-object-acl
(get-object-acl cred bucket key)
Get the access control list (ACL) for the supplied object. See get-bucket-acl
for a detailed description of the return value.
grant
(grant grantee permission)
Returns a function that adds a new grant map to a set of grants.
See update-bucket-acl.
list-buckets
(list-buckets cred)
List all the S3 buckets for the supplied credentials. The buckets will be
returned as a seq of maps with the following keys:
:name - the bucket name
:creation-date - the date when the bucket was created
:owner - the owner of the bucket
list-objects
(list-objects cred bucket & [options])
List the objects in an S3 bucket. A optional map of options may be supplied.
Available options are:
:delimiter - read only keys up to the next delimiter (such as a '/')
:marker - read objects after this key
:max-keys - read only this many objects
:prefix - read only objects with this prefix
The object listing will be returned as a map containing the following keys:
:bucket - the name of the bucket
:prefix - the supplied prefix (or nil if none supplied)
:objects - a list of objects
:common-prefixes - the common prefixes of keys omitted by the delimiter
:max-keys - the maximum number of objects to be returned
:truncated? - true if the list of objects was truncated
:marker - the marker of the listing
:next-marker - the next marker of the listing
list-versions
(list-versions cred bucket & [options])
List the versions in an S3 bucket. A optional map of options may be supplied.
Available options are:
:delimiter - the delimiter used in prefix (such as a '/')
:key-marker - read versions from the sorted list of all versions starting
at this marker.
:max-results - read only this many versions
:prefix - read only versions with keys having this prefix
The version listing will be returned as a map containing the following versions:
:bucket - the name of the bucket
:prefix - the supplied prefix (or nil if none supplied)
:versions - a sorted list of versions, newest first, each
version has:
:version-id - the unique version id
:latest? - is this the latest version for that key?
:delete-marker? - is this a delete-marker?
:common-prefixes - the common prefixes of keys omitted by the delimiter
:max-results - the maximum number of results to be returned
:truncated? - true if the results were truncated
:key-marker - the key marker of the listing
:next-version-id-marker - the version ID marker to use in the next listVersions
request in order to obtain the next page of results.
:version-id-marker - the version id marker of the listingobject-exists?
(object-exists? cred bucket key)
Returns true if an object exists in the supplied bucket and key.
put-multipart-object
(put-multipart-object cred bucket key file & [{:keys [part-size threads], :or {part-size (* 5 1024 1024), threads 16}}])
Do a multipart upload of a file into a S3 bucket at the specified key.
The value must be a java.io.File object. The entire file is uploaded
or not at all. If an exception happens at any time the upload is aborted
and the exception is rethrown. The size of the parts and the number of
threads uploading the parts can be configured in the last argument as a
map with the following keys:
:part-size - the size in bytes of each part of the file. Must be 5mb
or larger. Defaults to 5mb
:threads - the number of threads that will upload parts concurrently.
Defaults to 16.put-object
(put-object cred bucket key value & [metadata & permissions])
Put a value into an S3 bucket at the specified key. The value can be
a String, InputStream or File (or anything that implements the ToPutRequest
protocol).
An optional map of metadata may also be supplied that can include any of the
following keys:
:cache-control - the cache-control header (see RFC 2616)
:content-disposition - how the content should be downloaded by browsers
:content-encoding - the encoding of the content (e.g. gzip)
:content-length - the length of the content in bytes
:content-md5 - the MD5 sum of the content
:content-type - the mime type of the content
:server-side-encryption - set to AES256 if SSE is required
An optional list of grant functions can be provided after metadata.
These functions will be applied to a clear ACL and the result will be
the ACL for the newly created object.
revoke
(revoke grantee permission)
Returns a function that removes a grant map from a set of grants.
See update-bucket-acl.
update-bucket-acl
(update-bucket-acl cred bucket & funcs)
Update the access control list (ACL) for the named bucket using functions
that update a set of grants (see get-bucket-acl).
This function is often used with the grant and revoke functions, e.g.
(update-bucket-acl cred bucket
(grant :all-users :read)
(grant {:email "foo@example.com"} :full-control)
(revoke {:email "bar@example.com"} :write))update-object-acl
(update-object-acl cred bucket key & funcs)
Updates the access control list (ACL) for the supplied object using functions
that update a set of grants (see update-bucket-acl for more details).