Amazon S3 (Simple Storage Service) is an online storage web service offered by Amazon Web Services. Amazon S3 Connector provides storage through web services interfaces provided by AWS SDKs.
Additional Info
Requires Mule Enterprise License |
Yes |
Requires Entitlement |
No |
Mule Version |
3.5.0 or higher |
Configs
Configuration
<s3:config>
Connection Management
Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
name |
The name of this configuration. With this name can be later referenced. |
x |
||
accessKey |
The access key provided by Amazon, needed for non anonymous operations |
x |
||
secretKey |
The secrete key provided by Amazon, needed for non anonymous operations |
x |
||
tryDefaultAWSCredentialsProviderChain |
boolean |
Set it to true to try first to obtain credentials from AWS environment. See: http://docs.aws.amazon.com/java-sdk/latest/developer-guide/credentials.html#using-the-default-credential-provider-chain |
|
|
protocol |
Protocol |
The optional communication protocol to use when sending requests to AWS. Communication over HTTPS is the default |
HTTPS |
|
proxyHost |
The optional proxy port |
|
||
proxyPort |
The optional proxy port |
|
||
proxyUsername |
The optional proxy username |
|
||
proxyPassword |
The optional proxy password |
|
||
proxyDomain |
The optional proxy domain |
|
||
proxyWorkstation |
The optional proxy workstation |
|
||
socketTimeout |
The amount of time to wait (in milliseconds) for data to be transferred over an established, open connection before the connection is timed out. A value of 0 means infinity, and is not recommended. |
50000 |
|
|
connectionTimeout |
The amount of time to wait (in milliseconds) when initially establishing a connection before giving up and timing out. A value of 0 means infinity, and is not recommended. |
50000 |
|
|
maxConnections |
Sets the maximum number of allowed open HTTP connections. |
50 |
|
|
storageUrl |
The URL to connect to in case an S3 compatible storage is used. If blank, the default AWS S3 one will be used. |
|
||
roleARN |
The Role ARN allows you to cross account access without using security credentials. |
|
Processors
Create bucket
<s3:create-bucket>
Creates a new bucket; connector must not be configured as anonymous for this operation to succeed. Bucket names must be unique across all of Amazon S3, that is, among all their users. Bucket ownership is similar to the ownership of Internet domain names. Within Amazon S3, only a single user owns each bucket. Once a uniquely named bucket is created in Amazon S3, organize and name the objects within the bucket in any way. Ownership of the bucket is retained as long as the owner has an Amazon S3 account. To conform with DNS requirements, buckets names must: not contain underscores, be between 3 and 63 characters long, not end with a dash, not contain adjacent periods, not contain dashes next to periods and not contain uppercase characters. Do not make bucket create or delete calls in the high availability code path of an application. Create or delete buckets in a separate initialization or setup.
XML Sample
<s3:create-bucket bucketName="my-bucket" acl="PRIVATE" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
The bucket to create. It must not exist yet. |
x |
||
region |
the region where to create the new bucket |
US_STANDARD |
|
|
acl |
the access control list of the new bucket |
PRIVATE |
|
Delete bucket
<s3:delete-bucket>
Deletes the specified bucket. All objects (and all object versions, if versioning was ever enabled) in the bucket must be deleted before the bucket itself can be deleted; this restriction can be relaxed by specifying the attribute force="true".
XML Sample
<s3:delete-bucket bucketName="my-bucket" force="true" config-ref="Amazon_S3"/>Delete bucket cors configuration
<s3:delete-bucket-cors-configuration>
Deletes the Cross Origin Configuration information set for the bucket. To use this operation, you must have permission to perform the s3:PutCORSConfiguration action. The bucket owner has this permission by default and can grant this permission to others.
XML Sample
<s3:delete-bucket-cors-configuration bucketName="my-bucket" config-ref="Amazon_S3"/>Delete bucket lifecycle configuration
<s3:delete-bucket-lifecycle-configuration>
Deletes the lifecycle configuration from the specified bucket. Amazon S3 removes all the lifecycle configuration rules in the lifecycle subresource associated with the bucket. Your objects never expire, and Amazon S3 no longer automatically deletes any objects on the basis of rules contained in the deleted lifecycle configuration.
XML Sample
<s3:delete-bucket-lifecycle-configuration bucketName="my-bucket" config-ref="Amazon_S3"/>Delete bucket policy
<s3:delete-bucket-policy>
Deletes the bucket's policy. Only the owner of the bucket can delete the bucket policy. Bucket policies provide access control management at the bucket level for both the bucket resource and contained object resources.
XML Sample
<s3:delete-bucket-policy bucketName="my-bucket" config-ref="Amazon_S3"/>Delete bucket tagging configuration
<s3:delete-bucket-tagging-configuration>
Deletes the tagging configuration associated with the specified bucket. By default, the bucket owner has this permission and can grant this permission to others.
XML Sample
<s3:delete-bucket-tagging-configuration bucketName="my-bucket" config-ref="Amazon_S3"/>Delete bucket website configuration
<s3:delete-bucket-website-configuration>
Removes the website configuration for a bucket; this operation requires the DeleteBucketWebsite permission. By default, only the bucket owner can delete the website
configuration attached to a bucket. However, bucket owners can grant other users permission to delete the website configuration by writing a bucket policy granting them the
S3:DeleteBucketWebsite permission. Calling this operation on a bucket with no website configuration does not fail, but calling this operation a bucket that does
not exist does.
XML Sample
<s3:delete-bucket-website-configuration bucketName="my-bucket" config-ref="Amazon_S3"/>List buckets
<s3:list-buckets>
Answers a list of all Amazon S3 buckets that the authenticated sender of the request owns. Users must authenticate with a valid AWS Access Key ID that is registered with Amazon S3. Anonymous requests cannot list buckets, and users cannot list buckets that they did not create.
XML Sample
<s3:list-buckets config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
region |
the region from where to list the buckets. |
|
Get bucket acl
<s3:get-bucket-acl>
Answers the access control list of the specified bucket.
XML Sample
<s3:get-bucket-acl bucketName="my-bucket" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the bucket whose acl to retrieve. |
x |
Get bucket cors configuration
<s3:get-bucket-cors-configuration>
Answers the cors configuration information set for the bucket.
XML Sample
<s3:get-bucket-cors-configuration bucketName="my-bucket" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the bucket whose cors to retrieve. |
x |
Get bucket lifecycle configuration
<s3:get-bucket-lifecycle-configuration>
Returns the lifecycle configuration information set on the bucket.
XML Sample
<s3:get-bucket-lifecycle-configuration bucketName="my-bucket" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the bucket whose lifecycle configuration information to retrieve. |
x |
Get bucket policy
<s3:get-bucket-policy>
Answers the policy for the given bucket. Only the owner of the bucket can retrieve it. If no policy has been set for the bucket, then a null policy text field will be returned.
XML Sample
<s3:get-bucket-policy bucketName="my-bucket" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the bucket whose policy to retrieve |
x |
Get bucket location
<s3:get-bucket-location>
Gets the geographical region where Amazon S3 stores the specified bucket.
XML Sample
<s3:get-bucket-location bucketName="my-bucket" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
The target bucket name. |
x |
Get bucket logging configuration
<s3:get-bucket-logging-configuration>
Answers the logging status of a bucket and the permissions users have to view and modify that status.
XML Sample
<s3:get-bucket-logging-configuration bucketName="my-bucket" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the bucket whose logging status to retrieve. |
x |
Returns
| Return Java Type | Description |
|---|---|
the BucketLoggingConfiguration element. |
Get bucket notification configuration
<s3:get-bucket-notification-configuration>
Return the notification configuration of a bucket. Currently only topic configuration is supported.
XML Sample
<s3:get-bucket-notification-configuration bucketName="my-bucket" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the bucket whose notification configuration to retrieve. |
x |
Returns
| Return Java Type | Description |
|---|---|
the list of TopicConfigurations. |
Get bucket tagging configuration
<s3:get-bucket-tagging-configuration>
Return the tag set associated with the bucket.
XML Sample
<s3:get-bucket-tagging-configuration bucketName="my-bucket" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the bucket whose tagging configuration to retrieve. |
x |
Get bucket versioning configuration
<s3:get-bucket-versioning-configuration>
Returns the versioning configuration for the specified bucket.
XML Sample
<s3:get-bucket-versioning-configuration bucketName="my-bucket" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
The bucket whose versioning configuration will be retrieved. |
x |
Returns
| Return Java Type | Description |
|---|---|
The bucket versioning configuration for the specified bucket. |
Get bucket website configuration
<s3:get-bucket-website-configuration>
Answers the website of the given bucket. This operation requires the GetBucketWebsite permission. By default, only the bucket owner can read the bucket website configuration. However, bucket owners can allow other users to read the website configuration by writing a bucket policy granting them the GetBucketWebsite permission.
XML Sample
<s3:get-bucket-website-configuration bucketName="my-bucket" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the target bucket's name |
x |
Returns
| Return Java Type | Description |
|---|---|
the bucket website configuration for the specified bucket. |
Set bucket acl
<s3:set-bucket-acl>
Set the permissions on an existing bucket using access control lists (ACL)
XML Sample
<s3:set-bucket-acl bucketName="my-bucket" config-ref="Amazon_S3">
<s3:acl>
<s3:owner displayName="emailAddress" id="ID"/>
</s3:acl>
</s3:set-bucket-acl>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the bucket name |
x |
||
acl |
the ACL of a bucket. |
#[payload] |
|
Set bucket cors configuration
<s3:set-bucket-cors-configuration>
Sets the cors configuration for your bucket. If the configuration exists, Amazon S3 replaces it.
XML Sample
<s3:set-bucket-cors-configuration bucketName="my-bucket" config-ref="Amazon_S3">
<s3:cross-origin-configuration-rules>
<s3:cross-origin-configuration-rule>
<s3:allowed-headers>
<s3:allowed-header>*</s3:allowed-header>
</s3:allowed-headers>
</s3:cross-origin-configuration-rule>
</s3:cross-origin-configuration-rules>
</s3:set-bucket-cors-configuration>Set bucket lifecycle configuration
<s3:set-bucket-lifecycle-configuration>
Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration.
XML Sample
<s3:set-bucket-lifecycle-configuration bucketName="my-bucket" config-ref="Amazon_S3">
<s3:lifecycle-configuration-rules>
<s3:lifecycle-configuration-rule id="sample-rule" prefix="key-prefix" status="rule-status"/>
</s3:lifecycle-configuration-rules>
</s3:set-bucket-lifecycle-configuration>Set bucket policy
<s3:set-bucket-policy>
Sets the bucket's policy, overriding any previously set. Only the owner of the bucket can set a bucket policy. Bucket policies provide access control management at the bucket level for both the bucket resource and contained object resources. Only one policy can be specified per-bucket.
XML Sample
<s3:set-bucket-policy bucketName="my-bucket" policyText="your policy" config-ref="Amazon_S3"/>Set bucket logging configuration
<s3:set-bucket-logging-configuration>
Set the logging parameters for a bucket and to specify permissions for who can view and modify the logging parameters.
XML Sample
<s3:set-bucket-logging-configuration bucketName="my-bucket" destinationBucketName="your-bucket" logFilePrefix="logstash-" config-ref="Amazon_S3"/>Set bucket notification configuration
<s3:set-bucket-notification-configuration>
DataSense enabled
Sets the notification configuration for the specified bucket. By default, new buckets have no notification configuration set.
XML Sample
<s3:set-bucket-notification-configuration bucketName="my-bucket" config-ref="Amazon_S3">
<s3:topic-configurations>
<s3:topic-configuration key="" value-ref="topicRef"/>
</s3:topic-configurations>
</s3:set-bucket-notification-configuration>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
The name of the Amazon S3 bucket whose notification configuration is being set. |
x |
||
topicConfigurations |
The request object containing all options for setting the bucket notification configuration. |
#[payload] |
|
Set bucket tagging configuration
<s3:set-bucket-tagging-configuration>
Add a set of tags to an existing bucket
XML Sample
<s3:set-bucket-tagging-configuration bucketName="my-bucket" config-ref="Amazon_S3">
<s3:tag-sets>
<s3:tag-set ref="tagSetRef"/>
</s3:tag-sets>
</s3:set-bucket-tagging-configuration>Set bucket website configuration
<s3:set-bucket-website-configuration>
Sets the given bucket's website configuration. This operation requires the PutBucketWebsite permission. By default, only the bucket owner can configure the website attached to a bucket. However, bucket owners can allow other users to set the website configuration by writing a bucket policy granting them the S3:PutBucketWebsite permission.
XML Sample
<s3:set-bucket-website-configuration bucketName="my-bucket" config-ref="Amazon_S3">
<s3:bucket-website-configuration ref="#[payload]" />
</s3:set-bucket-website-configuration>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the bucket name |
x |
||
bucketWebsiteConfiguration |
the bucket website configuration |
#[payload] |
|
Set bucket versioning configuration
<s3:set-bucket-versioning-configuration>
Sets the versioning status for the given bucket. A bucket's versioning configuration can be in one of three possible states: Off, Enabled and Suspended. By default, new buckets are in the Off state. Once versioning is enabled for a bucket the status can never be reverted to Off.
XML Sample
<s3:set-bucket-versioning-configuration bucketName="my-bucket" status="SUSPENDED" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the bucket name |
x |
||
status |
the version status to set |
OFF |
|
Create object
<s3:create-object>
Uploads an object to S3. Supported contents are InputStreams, Strings, byte arrays and Files.
XML Sample
<s3:create-object bucketName="my-bucket" key="helloWorld.txt" contentType="text/plain" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the object's bucket |
x |
||
key |
the object's key |
x |
||
content |
the content to be uploaded to S3, capable of creating a PutObjectRequest. |
#[payload] |
|
|
contentLength |
the content length. If content is a InputStream, this parameter should be specified, as not doing so will introduce a performance loss as the contents will have to be persisted on disk before being uploaded. Otherwise, it is ignored. An exception to this rule are InputStreams returned by Mule Http Connector: if stream has Content-Length information, it will be used. In any case a content length of 0 is interpreted as an unspecified content length |
|
||
contentMd5 |
the content md5, encoded in base 64. If content is a file, it is ignored. |
|
||
contentType |
the content type of the new object. |
|
||
contentDisposition |
the content disposition of the new object. |
|
||
acl |
the access control list of the new object |
PRIVATE |
|
|
storageClass |
the storage class of the new object |
STANDARD |
|
|
userMetadata |
a map of arbitrary object properties keys and values |
|
||
encryption |
Encryption method for server-side encryption. Supported value AES256. |
|
||
kmsMasterKey |
Encrypt objects uploaded to S3 buckets with AWS KMS master key |
|
Delete object
<s3:delete-object>
Deletes a given object, only the owner of the bucket containing the version can perform this operation. If version is specified, versioning must be enabled, and once deleted, there is no method to restore such version. Otherwise, once deleted, the object can only be restored if versioning was enabled when the object was deleted. If attempting to delete an object that does not exist, Amazon S3 will return a success message instead of an error message.
XML Sample
<s3:delete-object bucketName="my-bucket" key="foo.gzip" config-ref="Amazon_S3"/>Delete objects
<s3:delete-objects>
Deletes multiple objects in a single bucket from S3. Version of the keys is optional.
In some cases, some objects will be successfully deleted, while some attempts will cause an error. If any object in the request cannot be deleted, this method throws a MultiObjectDeleteException with details of the error.XML Sample
<s3:delete-objects bucketName="my-bucket" config-ref="Amazon_S3">
<s3:keys>
<s3:key value="foo.gzip"/>
<s3:key value="bar.gzip"/>
</s3:keys>
</s3:delete-objects>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the objects bucket name |
x |
||
keys |
the objects keys, version is optional |
x |
List objects
<s3:list-objects>
Lazily lists all objects for a given prefix. As S3 does not limit in any way the number of objects, such listing can retrieve an arbitrary amount of objects, and may need to perform extra calls to the api while it is iterated.
XML Sample
<s3:list-objects bucketName="my-bucket" prefix="mk" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the target bucket's name |
x |
||
prefix |
the prefix of the objects to be listed. If unspecified, all objects are listed |
|
||
marker |
where in the bucket to begin listing. The list will only include keys that occur lexicographically after the marker |
|
||
delimiter |
causes keys that contain the same string between a prefix and the first occurrence of the delimiter to be rolled up into a single result element. These rolled-up keys are not returned elsewhere in the response. The most commonly used delimiter is "/", which simulates a hierarchical organization similar to a file system directory structure. |
|
||
maxKeys |
The maximum number of keys to include in the response. If maxKeys is not specified, Amazon S3 will limit the number of results in the response. |
|
||
encodingType |
The encoding method to be applied on the response. |
NOT_ENCODED |
|
List next batch of objects
<s3:list-next-batch-of-objects>
Provides an easy way to continue a truncated object listing and retrieve the next page of results.
XML Sample
<s3:list-next-batch-of-objects config-ref="Amazon_S3">
<s3:previous-object-listing ref="previousObjectListing"/>
</s3:list-next-batch-of-objects>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
previousObjectListing |
The previous truncated ObjectListing. If a non-truncated ObjectListing is passed in, an empty ObjectListing is returned without ever contacting Amazon S3. |
x |
Returns
| Return Java Type | Description |
|---|---|
The next set of ObjectListing results, beginning immediately after the last result in the specified previous ObjectListing. |
List versions
<s3:list-versions>
Lazily lists all object versions for a given bucket that has versioning enabled. As S3 does not limit in any way the number of objects, such listing can retrieve an arbitrary amount of object versions, and may need to perform extra calls to the api while it is iterated.
XML Sample
<s3:list-versions bucketName="my-bucket" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the target bucket's name |
x |
||
prefix |
optional parameter restricting the response to keys which begin with the specified prefix. You can use prefixes to separate a bucket into different sets of keys in a way similar to how a file system uses folders. |
|
||
keyMarker |
where in the sorted list of all versions in the specified bucket to begin returning results. Results are always ordered first lexicographically (i.e. alphabetically) and then from most recent version to least recent version. If a keyMarker is used without a versionIdMarker, results begin immediately after that key's last version. When a keyMarker is used with a versionIdMarker, results begin immediately after the version with the specified key and version ID. |
|
||
versionIdMarker |
where in the sorted list of all versions in the specified bucket to begin returning results. Results are always ordered first lexicographically (i.e. alphabetically) and then from most recent version to least recent version. A keyMarker must be specified when specifying a versionIdMarker. Results begin immediately after the version with the specified key and version ID. |
|
||
delimiter |
causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be rolled up into a single result element in the VersionListing#getCommonPrefixes() list. These rolled-up keys are not returned elsewhere in the response. The most commonly used delimiter is "/", which simulates a hierarchical organization similar to a file system directory structure. |
|
||
maxResults |
the maximum number of results to include in the response. |
|
||
encodingType |
the encoding method to be applied on the response. An object key can contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response. |
NOT_ENCODED |
|
List next batch of versions
<s3:list-next-batch-of-versions>
Provides an easy way to continue a truncated VersionListing and retrieve the next page of results.
XML Sample
<s3:list-next-batch-of-versions config-ref="Amazon_S3">
<s3:previous-version-listing ref="previousVersionListing"/>
</s3:list-next-batch-of-versions>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
previousVersionListing |
The previous truncated VersionListing. If a non-truncated VersionListing is passed in, an empty VersionListing is returned without ever contacting Amazon S3. |
x |
Returns
| Return Java Type | Description |
|---|---|
The next set of VersionListing results, beginning immediately after the last result in the specified previous VersionListing. |
Set object storage class
<s3:set-object-storage-class>
Sets the Amazon S3 storage class for the given object. Changing the storage class of an object in a bucket that has enabled versioning creates a new version of the object with the new storage class. The existing version of the object preservers the previous storage class.
XML Sample
<s3:set-object-storage-class bucketName="my-bucket" key="foo.gzip" storageClass="REDUCED_REDUNDANCY" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the object's bucket name |
x |
||
key |
the object's key |
x |
||
storageClass |
the storage class to set |
STANDARD |
|
Set object acl
<s3:set-object-acl>
Set the access control list (ACL) permissions for an object that already exists in a bucket
XML Sample
<s3:set-object-acl bucketName="my-bucket" key="bar.xml" versionId="L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo" config-ref="Amazon_S3">
<s3:acl ref="aclRef"/>
</s3:set-object-acl>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the object's bucket name |
x |
||
key |
the object's key |
x |
||
versionId |
the specific version of the object |
|
||
acl |
the access control list of the object |
#[payload] |
|
Copy object
<s3:copy-object>
Copies a source object to a new destination; to copy an object, the caller's account must have read access to the source object and write access to the destination bucket. By default, all object metadata for the source object are copied to the new destination object, unless new object metadata in the specified is provided. The AccessControlList is not copied to the new object, and, unless another ACL specified, PRIVATE is assumed. If no destination bucket is specified, the same that the source bucket is used - local copy. Destination object's Content-Type http header would be set with the specified value and if it is passed null, then the default MIME type 'application/octet-stream' would be set.
XML Sample
<s3:copy-object sourceBucketName="my-bucket" sourceKey="foo.gzip" destinationKey="bar.gzip"
destinationStorageClass="STANDARD" config-ref="Amazon_S3"/><s3:copy-object sourceBucketName="my-bucket" sourceKey="foo.gzip" destinationKey="bar.gzip"
destinationStorageClass="PRIVATE" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
sourceBucketName |
the source object's bucket |
x |
||
sourceKey |
the source object's key |
x |
||
sourceVersionId |
the specific version of the source object to copy, if versioning is enabled. Left unspecified if the latest version is desired, or versioning is not enabled. |
|
||
destinationBucketName |
the destination object's bucket. If none provided, a local copy is performed, that is, it is copied within the same bucket. |
|
||
destinationKey |
the destination object's key |
x |
||
destinationAcl |
the acl of the destination object. |
PRIVATE |
|
|
destinationStorageClass |
one of StorageClass enumerated values, defaults to StorageClass#STANDARD |
STANDARD |
|
|
destinationUserMetadata |
the new metadata of the destination object, that if specified, overrides that copied from the source object |
|
||
modifiedSince |
The modified constraint that restricts this request to executing only if the object has been modified after the specified date. This constraint is specified but does not match, no copy is performed |
|
||
unmodifiedSince |
The unmodified constraint that restricts this request to executing only if the object has not been modified after this date. This constraint is specified but does not match, no copy is performed |
|
||
encryption |
Encryption method for server-side encryption. Supported value AES256. |
|
||
contentType |
the destination object's Content-Type HTTP header |
|
Returns
| Return Java Type | Description |
|---|---|
the version id of the new object, or null, if versioning is not enabled |
Create object presigned uri
<s3:create-object-presigned-uri>
Returns a pre-signed URL for accessing an Amazon S3 object. The pre-signed URL can be shared to other users, allowing access to the resource without providing an account's AWS security credentials.
XML Sample
<s3:create-object-presigned-uri bucketName="my-bucket" key="bar.xml" method="GET" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the name of the bucket involved in this request. |
x |
||
key |
the key of the object involved in this request. |
x |
||
expiration |
the expiration date at which point the new pre-signed URL will no longer be accepted by Amazon S3. |
|
||
contentMd5 |
the expected content-md5 header of the request. |
|
||
contentType |
the expected content-type of the request. |
|
||
method |
the HTTP method (GET, PUT, DELETE, HEAD) to be used in this request. |
PUT |
|
|
sseS3Encryption |
the encryption method (KMS, AES256) to use for the presigned URL. |
|
Returns
| Return Java Type | Description |
|---|---|
A non null pre-signed URI that can be used to access an Amazon S3 resource without requiring the user of the URL to know the account's AWS security credentials. |
Get object content
<s3:get-object-content>
Gets the content of an object stored in Amazon S3 under the specified bucket and key. Be extremely careful when using this method; the returned Amazon S3 object contains a direct stream of data from the HTTP connection. The underlying HTTP connection cannot be closed until the user finishes reading the data and closes the stream. Callers should therefore:
- Use the data from the input stream as soon as possible,
- Close the input stream as soon as possible.
XML Sample
<s3:get-object-content bucketName="my-bucket" key="bar.xml" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the object's bucket |
x |
||
key |
the object's key |
x |
||
versionId |
the specific version of the object to get its contents, if versioning is enabled, left unspecified if the latest version is desired, or versioning is not enabled. |
|
||
modifiedSince |
The modified constraint that restricts this request to executing only if the object has been modified after the specified date. |
|
||
unmodifiedSince |
The unmodified constraint that restricts this request to executing only if the object has not been modified after this date. |
|
||
mimeType |
Specifies the mimetype of the object |
|
||
encoding |
Specifies the encding used for the ObjectContent |
|
Returns
| Return Java Type | Description |
|---|---|
TransformingValue |
The object stream stored in Amazon S3 in the specified bucket and key. Returns null if constraints were specified but not met. |
Get object
<s3:get-object>
Gets the object stored in Amazon S3 under the specified bucket and key. Returns null if the specified constraints weren't met. To get an object from Amazon S3, the caller must have Permission#Read access to the object. Callers should be very careful when using this method; the returned Amazon S3 object contains a direct stream of data from the HTTP connection. The underlying HTTP connection cannot be closed until the user finishes reading the data and closes the stream. Regarding conditional get constraints, Amazon S3 will ignore any dates occurring in the future.
XML Sample
<s3:get-object bucketName="my-bucket" key="bar.xml" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the object's bucket |
x |
||
key |
the object's key |
x |
||
versionId |
the specific version of the object to get its contents, if versioning is enabled. Left unspecified if the latest version is desired, or versioning is not enabled. |
|
||
modifiedSince |
The modified constraint that restricts this request to executing only if the object has been modified after the specified date. |
|
||
unmodifiedSince |
The unmodified constraint that restricts this request to executing only if the object has not been modified after this date. |
|
Returns
| Return Java Type | Description |
|---|---|
the S3Object, or null, if conditional get constraints did not match |
Get object acl
<s3:get-object-acl>
Returns the access control list (ACL) of an object. By default, GET returns ACL information about the current version of an object. To return ACL information about a different version, use the versionId attribute.
XML Sample
<s3:get-object-acl bucketName="my-bucket" key="bar.xml" versionId="L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo" config-ref="Amazon_S3" />Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the object's bucket |
x |
||
key |
the object's key |
x |
||
versionId |
the object's version id |
|
Get object metadata
<s3:get-object-metadata>
Gets the metadata for the specified Amazon S3 object without actually fetching the object itself. This is useful in obtaining only the object metadata, and avoids wasting bandwidth on fetching the object data.
XML Sample
<s3:get-object-metadata bucketName="my-bucket" key="baz.bin" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the object's bucket |
x |
||
key |
the object's key |
x |
||
versionId |
the object metadata for the given bucketName and key |
|
Initiate multipart upload
<s3:initiate-multipart-upload>
Initiates a multipart upload and returns an upload ID. This upload ID is used to associate all the parts in the specific multipart upload. You specify this upload ID in each of your subsequent upload part requests. You also include this upload ID in the final request to either complete or abort the multipart upload request.
XML Sample
<s3:initiate-multipart-upload bucketName="my-bucket" key="bar.xml" acl="BUCKET_OWNER_FULL_CONTROL" redirectLocation="/doc/bar.xml" storageClass="GLACIER" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the name of the bucket in which to create the new multipart upload. |
x |
||
key |
the key by which to store the new multipart upload. |
x |
||
objectMetadata |
the additional information about the new object being created, such as content type, content encoding, user metadata, etc. |
|
||
acl |
the optional canned Access Control List (ACL) to set permissions for the new object created when the multipart upload is completed. |
PRIVATE |
|
|
storageClass |
the optional storage class to use when storing this upload's data in S3. |
STANDARD |
|
|
redirectLocation |
Gets the optional redirect location for the new object. |
|
Upload part
<s3:upload-part>
Uploads a part in a multipart upload. You must initiate a multipart upload before you can upload any part.
XML Sample
<s3:upload-part bucketName="my-bucket" key="bar.xml" uploadId="VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR" partNumber="1" partSize="1234567890" content-ref="contentRef" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the name of the bucket containing the existing, initiated multipart upload, with which this new part will be associated. |
x |
||
key |
the key of the initiated multipart upload. |
x |
||
uploadId |
the ID of the existing, initiated multipart upload with which this new part will be associated. |
x |
||
partNumber |
the part number describing this part's position relative to the other parts in the multipart upload. |
x |
||
partSize |
the size of this part, in bytes. |
x |
||
md5Digest |
optional, but recommended, MD5 hash of the content of this part. |
|
||
content |
the stream containing the data to upload for the new part. |
|
||
file |
the file containing the data to upload. |
|
||
fileOffset |
the optional offset in the specified file, at which to begin uploading data for this part. |
|
||
isLastPart |
boolean |
true if the creator of this request has indicated this part is the last part being uploaded in a multipart upload. |
false |
|
Returns
| Return Java Type | Description |
|---|---|
An UploadPartResult from Amazon S3 containing the part number and ETag of the new part. |
Upload part copy
<s3:upload-part-copy>
Copies a source object to a part of a multipart upload. To copy an object, the caller's account must have read access to the source object and write access to the destination bucket.
XML Sample
<s3:upload-part-copy sourceBucketName="my-bucket" sourceKey="bar.xml" destinationBucketName="your-bucket" destinationKey="bar.xml" uploadId="VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR" partNumber="2" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
sourceBucketName |
the name of the bucket containing the source object to be copied. |
x |
||
sourceKey |
the source bucket key under which the source object to be copied is stored. |
x |
||
sourceVersionId |
the version of the source object that was copied, if you have enabled versioning on the source bucket. |
|
||
destinationBucketName |
the destination bucket name which will contain the new, copied object. |
x |
||
destinationKey |
the destination bucket key under which the new, copied object will be stored. |
x |
||
uploadId |
the ID of the existing, initiated multipart upload with which this new part will be associated. |
x |
||
partNumber |
the part number describing this part's position relative to the other parts in the multipart upload. |
x |
||
matchingETagConstraints |
perform a copy if the source object entity tag (ETag) matches the specified value. |
|
||
modifiedSince |
the optional modified constraint that restricts this request to executing only if the source object has been modified after the specified date. |
|
||
unmodifiedSince |
the optional unmodified constraint that restricts this request to executing only if the source object has not been modified after the specified date. |
|
||
firstByte |
the optional first byte from the source bucket to start copy from (starts from 0). |
|
||
lastByte |
the optional last byte from the source bucket to copy till. |
|
Returns
| Return Java Type | Description |
|---|---|
A CopyPartResult object containing the information returned by Amazon S3 about the newly created object, or null if constraints were specified that weren't met when |
Abort multipart upload
<s3:abort-multipart-upload>
Aborts a multipart upload. After a multipart upload is aborted, no additional parts can be uploaded using that upload ID. The storage consumed by any previously uploaded parts will be freed. However, if any part uploads are currently in progress, those part uploads may or may not succeed. As a result, it may be necessary to abort a given multipart upload multiple times in order to completely free all storage consumed by all parts.
XML Sample
<s3:abort-multipart-upload bucketName="my-bucket" key="baar.xml" uploadId="VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR" config-ref=""/>Complete multipart upload
<s3:complete-multipart-upload>
Completes a multipart upload by assembling previously uploaded parts.
XML Sample
<s3:complete-multipart-upload bucketName="my-bucket" key="bar.xml" uploadId="VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR" config-ref="Amazon_S3">
<s3:part-e-tags></s3:part-e-tags>
</s3:complete-multipart-upload>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the name of the bucket containing the multipart upload to complete. |
x |
||
key |
the key under which the multipart upload to complete is stored. |
x |
||
uploadId |
the ID of the multipart upload to complete. |
x |
||
partETags |
the list of part numbers and ETags that identify the individual parts of the multipart upload to complete. |
x |
Returns
| Return Java Type | Description |
|---|---|
A CompleteMultipartUploadResult from S3 containing the ETag for the new object composed of the individual parts. |
List multipart uploads
<s3:list-multipart-uploads>
Lists in-progress multipart uploads. An in-progress multipart upload is a multipart upload that has been initiated, using the InitiateMultipartUpload request, but has not yet been completed or aborted.
XML Sample
<s3:list-multipart-uploads bucketName="my-bucket" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the name of the bucket containing the uploads to list. |
x |
||
delimiter |
the optional delimiter parameter that causes multipart uploads for keys that contain the same string between the prefix and the first occurrence of the delimiter to be combined into a single result element |
|
||
encodingType |
the optional encodingType parameter indicating the encoding method to be applied on the response. |
|
||
keyMarker |
the optional key marker indicating where in the results to begin listing. |
|
||
maxUploads |
the optional maximum number of uploads to return, or null if no maximum number of uploads has been set for this request. |
|
||
prefix |
the optional prefix parameter that restricts the response to multipart uploads for keys that begin with the specified prefix. |
|
||
uploadIdMarker |
the optional upload ID marker indicating where in the results to begin listing. |
|
Returns
| Return Java Type | Description |
|---|---|
A MultipartUploadListing from Amazon S3. |
List parts
<s3:list-parts>
Lists the parts that have been uploaded for a specific multipart upload.
XML Sample
<s3:list-parts bucketName="my-bucket" key="bar.txt" uploadId="VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR" config-ref="Amazon_S3"/>Attributes
| Name | Java Type | Description | Default Value | Required |
|---|---|---|---|---|
config-ref |
Specify which config to use |
x |
||
bucketName |
the name of the bucket containing the multipart upload whose parts are being listed. |
x |
||
key |
the key of the associated multipart upload whose parts are being listed. |
x |
||
uploadId |
the ID of the multipart upload whose parts are being listed. |
x |
||
encodingType |
the optional encodingType parameter indicating the encoding method to be applied on the response. |
|
||
maxParts |
the optional maximum number of parts to be returned in the part listing. |
|
||
partNumberMarker |
the optional part number marker indicating where in the results to being listing parts. |
|
Returns
| Return Java Type | Description |
|---|---|
Returns a PartListing from Amazon S3. |