Amazon S3 Simple Storage Connector

This adapter manages data and its structures in Amazon S3 Blob Storage. It also persits data in cloud environments.

Properties

Operation

Defines the operation executed by the adapter

Possible values:

CreateBucket: Creates a bucket.
(information) For the operation CreateBucket different configurations are possible. If the parameter bucketVersion is set to ENABLED, the bucket versioning is enabled. Otherwise the versioning is enabled. If the parameter publicAccess is enabled a permission must be defined via the parameter publicPermission.
Required parameters: bucket, bucketVersion, publicAccess, PublicPermission
ChangeBucketVersion: Changes the bucket's versioning configuration.
(information) New buckets have the status OFF by default. Once versioning is enabled, the status can no longer be reset to the status OFF.
Required parameters: bucket, bucketVersion
GetAccessControlList: Lists the grants and permissions for a bucket or file.
(information) If the parameters bucket and file are specified, the grants and permissions are listed for the file. If only bucket is specified, the grants and permissions are listed for the bucket.
Required parameters: bucket, file
AddGrantsPermission: Adds grants with permissions to a bucket or a file.
(information) If the parameter publicAccess is enabled, a publicly accessible bucket or file is created with the permissions defined in the publicPermission parameter. Otherwise, information is taken from the input. If the parameters bucket and file are specified, the grants and permissions are added to the file. If only bucket is specified, the grants and permissions are added to the bucket.
Required parameters: bucket, file
RevokeGrantsPermission: Revokes all permissions for a grant.
(information) If the parameters bucket and file are specified, the grants and permissions are revoked for the file. If only Bucket is specified, the grants and permissions are revoked for the bucket.
Required parameters: bucket, file
RevokePublicPermission: Revokes the public access permissions.
(information)If the parameters bucket and file are specified, the public access permissions to the file are revoked. If only bucket is specified, the public access permissions to the bucket are revoked.
Required parameters: bucket, file
AddBucketPolicy: Adds a bucket policy to the specified bucket.
(information) Find additional information such as sample bucket policies, permissions in a policy and conditions in a policy.
Required parameters: bucket
GetBucketPolicy: Invokes the bucket policy.
Required parameters: bucket
RemoveBucketPolicy: Deletes the policy for the specified bucket.
Required parameters: bucket
Search: Searches for information in the AmazonS3 Simple storage account and optionally for object metadata.
(information) If the parameter includeObjectsMetadata is selected, metadata information from each object are added to the default response.
Required parameters: file, includeObjectsMetadata
Upload: Uploads files to the Amazon S3 Simple storage account.
(information) Create folder structures using "/", e.g. Lib/Document/doc.txt
Required parameters: bucket, file, overwrite, path
Download: Downloads files from the Amazon S3 Simple storage account.
Required parameters: bucket, file
Copy: Copies files to the destination bucket.
(information) To copy a file, permission from the destination bucket is required.
Required parameters: bucket, file, targetBucket, targetFile
Move: Moves files to the destination bucket.
(information) To move a file, permission from the destination bucket is required.
Required parameters: bucket, file, targetBucket, targetFile
Rename: Renames files in the destination bucket.
(information) To rename a file, permission from the destination bucket is required.
Delete: Deletes files or buckets.
(information) If bucket and file are specified, the specified file will be deleted. If only the bucket is specified, all files inside that bucket and then the bucket will be deleted.
DeleteMultiFiles: Deletes multiple files.
Required parameters: bucket, file

Parameters

Adapter

Main adapter class (do not change!)

Possible values: de.softproject.integration.adapter.amazpns3.AmazonS3SimpleStorageAdapter: Main class (default)

keyId

Access key ID used to sign programmatic requests to AWS

(information) The credentials are passed by parameters to the adapter. There are different ways to configure them, see How to get credentials keys.

Possible values: Any string containing the access key Id, e.g. AKIAIOSFODNN7EXAMPLE

secretKey

Secret access key used to sign programmatic requests to AWS

(information) The credentials are passed by parameters to the adapter. There are different ways to configure them, see How to get credentials keys.

Possible values: Any string containing the secret access key e.g. wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

region

Bucket region

Possible values: Any string containing the region name, e.g. us-east-2

(information) Buckets created in a specific region, can not be accessed from a different region, see Regions and Endpoints.

bucket

Bucket name

(information) The bucket must be unique across all existing bucket names in Amazon S3, see Buckets.

Possible values: Any string containing the bucket name

The following rules apply for naming S3 buckets in all AWS Regions. Bucket names...

must be unique across all existing bucket names in Amazon S3
must comply with DNS naming conventions
must be at least 3 and no more than 63 characters long
must not contain uppercase characters or underscores
must start with a lowercase letter or number
must be a series of one or more labels
Adjacent labels are separated by a single period (.). Bucket names can contain lowercase letters, numbers, and hyphens. Each label must start and end with a lowercase letter or a number.
must not be formatted as an IP address, e.g. 192.168.5.4
When using virtual hosted-style buckets with Secure Sockets Layer (SSL), the SSL wildcard certificate only matches buckets that don't contain periods. To work around this, use HTTP or write your own certificate verification logic. We recommend not to use periods (".") in bucket names when using virtual hosted-style buckets.

bucketVersion

Bucket versioning to keeping multiple variants of an object in the same bucket

Possible values:

OFF: Versioning is disabled (default)
(information) If versioning for a bucket is enabled, the versioning can no longer be disabled and set to the status OFF. Versioning can only be suspended and set to the status SUSPENDED.
ENABLED: Bucket versioning is enabled
SUSPENDED: Bucket versioning is suspended, if the versioning was enabled before

publicAccess

Specifies whether buckets or files are publicly accessible or not during the AddGrantsPermission operation.

publicPermission

Public Access Configuration.

Possible values:

Permission	When granted on a bucket	When granted on an object
`READ`	Allows to list the objects in the bucket	Allows to read the object data and its metadata
`WRITE`	Allows to create, overwrite, and delete any object in the bucket	Not applicable
`READ_ACP`	Allows to read the bucket ACP	Allows to read the object ACP
`WRITE_ACP`	Allows to write the ACP for the applicable bucket	Allows to write the ACP for the applicable object
`FULL_CONTROL`	Allows to access the bucket permissions `READ`, `WRITE`, `READ_ACP`, and `WRITE_ACP`	Allows to access the object permissions `READ`, `WRITE`, `READ_ACP`, and `WRITE_ACP`

file

Name of file to be saved, see Objects

The following character sets are generally allowed in key names:

Alphanumeric characters [0-9a-zA-Z]
Special characters: !, -, _, ., *, ', (, and )

Possible values: Any string containing the object key name, e.g.

4my-organization
my.great_photos-2014/jan/myvacation.jpg
videos/2014/birthday/video1.wmv

path

Path of the file to be uploaded

Possible values: Any valid path, e.g.

X4DB Path: x4db://1/.....
XSTORE Pathxstore://
Full Path: C:/Documents/....

overwrite

Information whether the file should be overwritten or not

Possible values:

True: Overwrites the file
False: Does not overwrite the file

targetBucket

Name of the bucket where the file will be copied or moved to

Possible values: See parameter bucket

targetFile

Name the file will take when copied or moved to the new path

Possible values: See parameter file

includeObjectsMetadata

Information whether object metadata should be included as part of the response

Possible values:

True: Object metadata are included as part of the response
False: Object metadata are not included as part of the response

Status values

`1`	The operation was executed successfully
`0`	The operation's execution has not yet been completed or no result has been output
`-1`	An error occurred during the operation's execution

Input

The adapter expects any input document, e.g. binary document or a base-64 document (XML or text).

Operation Upload: If parameter path is specified, no input document is required. In all other cases an input document is needed.
Operation Download and Search: No input document is required.

Operation AddGrantsPermission:

XML

<?xml version='1.0' encoding='UTF-8'?>
<RootElement>
    <Grant id="Canonical User ID">
        <permission> Read </permission>
		<permission> Write </permission>
		<permission> WriteAcp </permission>
		<permission> ReadAcp </permission>
		<permission> FullControl </permission>
    </Grant>
</RootElement>

(information) To add object permissions, the parameters bucket and file are required. To add bucket permissions, the parameter bucket is required and file has to be empty.

Operation RevokeGrantsPermission:
XML
```
<?xml version='1.0' encoding='UTF-8'?>
<RootElement>
    <Grant id="Canonical User ID">
    </Grant>
</RootElement>
```
(information) To add object permissions, the parameters bucket and file are required. To add bucket permissions, the parameter bucket is required and file has to be empty.
For the operation AddBucketPolicy the input must have Json format.
(information) Find additional information such as sample bucket policies, permissions in a policy and conditions in a policy.

Operation DeleteMultiFiles:

XML

<?xml version='1.0' encoding='UTF-8'?>
<RootElement>
    <Object name="File Name"></Object>
	<Object name="File Name"></Object>
	<Object name="File Name"></Object>
	<Object name="File Name"></Object>
</RootElement>

Output

The adapter returns different kind of documents depending on the executed operation:

Operation Upload:
If the adapter was executed successfully (status 1), the adapter returns an XML document.If an error occurred during the adapter's execution (status -1), the adapter does not return anything.
Operation Search:If the adapter was executed successfully (status 1), the adapter returns an XML document with the used filters.Sample output for operation SEARCH <?xml version='1.0' encoding='UTF-8'?> <ListBucket> <Bucket name="test-malaga2" region="eu-west-1"> <Object name="myFile.xml" url="https://s3-eu-west-1.amazonaws.com/test-malaga2/myFile.xml"/> <Object name="myFile2.xml" url="https://s3-eu-west-1.amazonaws.com/test-malaga2/myFile2.xml"/> <Object name="pic2.jpg" url="https://s3-eu-west-1.amazonaws.com/test-malaga2/pic2.jpg"/> <Object name="testing_folders/" url="https://s3-eu-west-1.amazonaws.com/test-malaga2/testing_folders/"/> <Object name="testing_folders/personalData.txt" url="https://s3-eu-west-1.amazonaws.com/test-malaga2/testing_folders/personalData.txt"/> </Bucket> </ListBucket> If the adapter was executed successfully (status 1) and the parameter IncludeObjectsMetada is selected, the metadata for each object are output additionally:Sample output for operation SEARCH including metadata <?xml version='1.0' encoding='UTF-8'?> <ListBucket> <Bucket name="test-malaga2" region="eu-west-1"> <Object name="myFile.xml" url="https://s3-eu-west-1.amazonaws.com/test-malaga2/myFile.xml"> <Metadata lastModified="2018-12-10 13:42:38.000 +0100" instanceLength="158" eTag="a933d9ca99b473c7921c496727a32f91" contentType="application/octet-stream" contentLength="158"/> </Object> <Object name="myFile2.xml" url="https://s3-eu-west-1.amazonaws.com/test-malaga2/myFile2.xml"> <Metadata lastModified="2018-12-10 12:02:07.000 +0100" instanceLength="158" eTag="a933d9ca99b473c7921c496727a32f91" contentType="application/octet-stream" contentLength="158" contentLanguage="English"/> </Object> <Object name="pic2.jpg" url="https://s3-eu-west-1.amazonaws.com/test-malaga2/pic2.jpg"> <Metadata lastModified="2018-12-10 11:37:52.000 +0100" instanceLength="59580" eTag="fb913694d969758b431277b366f53d7" contentType="image/jpeg" contentLength="59580" contentLanguage="Spanish"/> </Object> <Object name="testing_folders/" url="https://s3-eu-west-1.amazonaws.com/test-malaga2/testing_folders/"> <Metadata lastModified="2018-12-10 12:24:54.000 +0100" eTag="d41d8cd98f00b204e9800998ecf8427e" contentType="application/x-directory"/> </Object> <Object name="testing_folders/personalData.txt" url="https://s3-eu-west-1.amazonaws.com/test-malaga2/testing_folders/personalData.txt"> <Metadata lastModified="2018-12-10 12:30:35.000 +0100" instanceLength="33" eTag="7960fb01e91834eb9d5ccbacdf45d0e5" contentType="application/octet-stream" contentLength="33" contentLanguage="Spanish"/> </Object> </Bucket> </ListBucket> If an error occurred during the adapter's execution (status -1), the adapter does not return anything.
Operation Download:If the adapter was executed successfully (status 1), the adapter returns the downloaded blob (text, XML, binary doc etc.).If the object or bucket do not exist the status -1 is returned.

Operation GetAccessControlList:

XML

<AccessControlList>
    <Object Grant="e0188cd1cbfbb71222450e8e416e138172b036cdf3646ab51fb0ae6334d5ae51" Permission="FULL_CONTROL"/>
    <Object Grant="7779a9de4e188ca2c3fd5ef47f12f2a0fd3b9b30d283e343e0a55746d8df4802" Permission="READ"/>
	<Object Grant="7779a9de4e188ca2c3fd5ef47f12f2a0fd3b9b30d283e343e0a55746d8df4802" Permission="READ_ACP"/>
</AccessControlList>

Operation GetBucketPolicy :

Java

{
"Version":"2012-10-17", "Statement":[
}
"Sid":"AddPerm",
"Effect":"Allow",
"Principal":"*",
"Action":"s3:GetObject",
"Resource":"arn:aws:s3:::softprojectamazons3input/*"
}
]
}