Amazon S3 Simple Storage Connector

This adapter manages data and its structures in Amazon S3 Blob Storage. Moreover, you can use it to persist data in cloud environments.

Properties

Operation

Operation performed by the adapter

Possible values:

CreateBucket: Creates a bucket.
Various configurations can be made for the CreateBucket operation. For example, if the bucketVersion parameter is set to ENABLED, bucket versioning is activated. Otherwise, versioning is disabled. If the publicAccess parameter is activated, an authorization must be defined via the publicPermission parameter.
Required parameters: bucket, bucketVersion, publicAccess , publicPermission
ChangeBucketVersion: Changes the bucket versioning configuration.
New buckets are in the OFF status by default. Once versioning is activated, the status cannot be reset to OFF.
Required parameters: bucket, bucketVersion
GetAccessControlList: Lists the rights and permissions for a bucket or file.
If the bucket and file parameters are specified, the rights and permissions for the file are issued. If only bucket is specified, the bucket's rights and permissions are issued.
Required parameters: bucket, file
AddGrantsPermission: Adds rights with permissions to a bucket or file.
If the publicAccess parameter is enabled, a publicly accessible bucket or file is created with the permissions defined in the publicPermission parameter. Otherwise, the information is taken from the input. If the bucket and file parameters are specified, the rights and permissions are added to the file. If only bucket is specified, the rights and permissions are added to the bucket.
Required parameters: bucket, file
RevokeGrantsPermission: Revokes all permissions.
If the bucket and file parameters are specified, the rights and permissions for the file are revoked. If only bucket is specified, the bucket's rights and permissions are revoked.
Required parameters: bucket, file
RevokePublicPermission: Revokes the permissions for public access.
If the bucket and file parameters are specified, public access permissions to a 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 a specified bucket.
The following links provide additional information, such as bucket policy examples, permissions in a policy, and conditions in policies.
Required parameters: bucket
GetBucketPolicy: Opens 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 also for object metadata.
If the includeObjectsMetadata parameter is selected, metadata information is added to each object in the default response.
Required parameters: file, includeObjectsMetadata
Upload: Uploads files to the Amazon S3 Simple Storage account.
Create folder structures with "/", 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.
To copy a file, a permission for the destination bucket is required.
Required parameters: bucket, file, targetBucket , targetFile
Move: Moves files to the destination bucket.
To move a file, a permission for the destination bucket is required.
Required parameters: bucket, file, targetBucket , targetFile
Rename: Renames files to the destination bucket.
Delete : Deletes files or buckets.
If bucket and file are specified, the specified file is deleted. If only bucket is specified, all files in the bucket and then the bucket itself are deleted. If bucket versioning is enabled, the file versions are deleted first and then the bucket is deleted.
DeleteMultiFiles: Deletes multiple files.
Required parameters: bucket, file

Parameter

Adapter

Adapter main class (do not change!)

Possible values: de.softproject.integration.adapter.amazons3.AmazonS3SimpleStorageAdapter: Main Class (Standard)

keyID

Access key ID for requests to Amazon Web Services (AWS)

The credentials are sent to the adapter via parameters. There are various configuration options, see Setting up access data .

Possible values: Any string with the access key ID, e.g. AKIAIOSFODNN7EXAMPLE

secretKey

Secret access key for requests to AWS

The credentials are sent to the adapter via parameters. There are various configuration options, see Setting up access data .

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

region

Bucket region

Possible values: Any string with the name of the region, for example, us-east-2

Buckets created in a specific region cannot be invoked from another region, see Regional endpoints.

bucket

Bucket name

The bucket name must be unique within Amazon S3 , see Buckets.

Possible values: Any string with the bucket name

The following rules apply to the naming of S3 buckets in all AWS regions. Bucket names ...

Must be unique within Amazon S3
Must comply with DNS naming conventions
Must be at least 3 characters long and not more than 63 characters long
Must not contain uppercase letters or underscores
Must start with a lowercase letter or a number
Must be a string of one or more characters
Consecutive names are separated by a single period (.). Bucket names can contain lowercase letters, numbers, and hyphens. Each name must begin and end with a lowercase letter or a number.
Must not be formatted as an IP address , for example, 192.168.5.4
When using virtual hosted buckets with Secure Sockets Layer (SSL), the SSL wildcard certificate applies only to buckets that do not contain points. To work around this, use HTTP or write your own certificate verification logic. We do not recommend using dots (.) in the bucket name of virtually-hosted buckets.

bucketVersion

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

Possible values:

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

publicAccess

Specifies whether buckets or files are publicly accessible when using the AddGrantsPermission operation

publicPermission

Configuration for public access

Possible values:

Permission	Allowed for buckets	Allowed for objects
`READ`	Allows you to list the objects in the bucket	Allows you to read the object data and metadata
`WRITE`	Allows you to create, overwrite, and delete any object in the bucket	Not applicable
`READ_ACP`	Allows you to read the bucket ACP	Allows you to read the object ACP
`WRITE_ACP`	Allows you to write the ACP for each bucket	Allows you to write the ACP for the respective object
`FULL_CONTROL`	Allows access to the bucket permissions: `READ`, `WRITE`, `READ_ACP`, and `WRITE_ACP`	Allows access to the object permissions: `READ`, `WRITE`, `READ_ACP`, and `WRITE_ACP`

file

Name of the 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 with the object key name, for example

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, for example

X4DB Path: x4db://1/.....
XSTORE path xstore://
Full Path: C:/Documents/....

overwrite

Information on 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 in which the file is to be copied or moved

Possible values: See bucket parameter

targetFile

Name of the file if it is copied or moved under the new path

Possible values: See file parameter

includeObjectsMetadata

Specifies whether or not object metadata is included as part of the response

Possible values:

true: Object metadata is included as part of the response
false: Object metadata is not included as part of the response

Status values

`1`	The adapter operation was executed successfully
`0`	The operation has not yet been completed or no result has been returned
`-1`	An error occurred while running the adapter

Input

The adapter expects any input document, for example, a binary or Base64 document (XML or text).

Upload operation: If the path parameter is specified, no input document is required. In all other cases, an input document is expected.
Download and Search operations: No input document is required.

AddGrantsPermission operation :

Beispiel-Input für die 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>

To add object permissions, the bucket and file parameters are required. To add bucket permissions, the bucket parameter is required and file must be empty.

RevokeGrantsPermission operation:
Beispiel-Input für die Operation RevokeGrantsPermission

XML
```
<?xml version='1.0' encoding='UTF-8'?>
<RootElement>
    <Grant id="Canonical User ID">
    </Grant>
</RootElement>
```
To add object permissions, the bucket and file parameters are required. To add bucket permissions, the bucket parameter is required and file must be empty.
For the AddBucketPolicy operation, the input must be in JSON format
The following links provide additional information, such as bucket policy examples, permissions in a policy, and conditions in policies.

DeleteMultiFiles operation:

Beispiel-Input für die 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 outputs various documents depending on the operation that is performed:

Upload operation:
- If the adapter has been executed successfully (status 1), an XML document is issued.
- If there was an error during adapter execution (status -1), nothing is issued.

Search operation:

If the adapter has been executed successfully (status 1), an XML document is issued with the used filters.

Beispiel-Output für die Operation SEARCH

XML

<?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 has been executed successfully (status 1) and the IncludeObjectsMetada parameter is selected, the metadata for each object is also issued:

Beispiel-Output für die Operation SEARCH inklusive Metadaten

XML

<?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 there was an error during adapter execution (status -1), nothing is issued.

Download operation:
- If the adapter has been executed successfully (status 1), the downloaded blob (text, XML binary document, etc.) is issued.
- If the object or bucket does not exist, the status -1 is returned.

GetAccessControlList operation:

Beispiel-Output für die Operation GetAccessControlList

XML

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

GetBucketPolicy operation:

JAVA

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