Handling of S3 Buckets

With the S3 adapter, you can create, delete and list buckets of an S3 endpoint, and retrieve contents and status information of a bucket.

Creating a Bucket

Using the createBucket operation of the S3 adapter, you can create a new bucket to the S3 endpoint.

Name

Type

Direction

Description

Allowed Values / Examples

bucketName

String

in

Name of the bucket to create.

The name of the bucket should be prefixed with the PAS client.

If a bucket with the same name is already existing or if the bucket name does not match the S3 bucket naming rules, an exception is thrown.

pas-doc-examples

We recommend to prefix bucket name with the PAS client code (e.g. pas-test) because multiple PAS clients may use the same S3 installation.

Listing all Available Buckets

Using the listBuckets operation of the S3 adapter, you can get a list of all buckets that are available from the S3 endpoint.

Name	Type	Direction	Description	Allowed Values / Examples
bucketNames	Array of String	out	List of buckets that are available from the specified S3 endpoint.

Deleting a Bucket

Using the deleteBucket operation of the S3 adapter on a bucket, you can delete a bucket from your S3 endpoint. In case the bucket is not empty, you need to set deleteRecursively to true to remove the bucket and all of its contents - otherwise you will get an exception.

Name	Type	Direction	Description	Allowed Values / Examples
bucketName	String	in	Name of the bucket to delete.	There will be no exception if the bucket you want to delete is not existing.
deleteRecursively	Boolean	in	With S3, as a rule, only empty buckets can be deleted. Specify here whether to delete the bucket and all of its contents in one go.	true	Delete the bucket and all its contents.
deleteRecursively	Boolean	in		false	Bucket must be empty to be deleted (default).

Reading the Contents of a Bucket

Using the listObjects operation of the S3 adapter, you can get a list of all objects that are contained in the given bucket.

listObjects ( bucketName: String, objectNames: String[] )

Name	Type	Direction	Description	Allowed Values / Examples
bucketName	String	in	Name of the bucket to list the contents of.	If the bucket is not existing, an exception is thrown.
options	ListObjectsOptions	in	listObjects options as described for the ListObjectsOptions type.	Valid listObject options as described for the ListObjectsOptions type.
objectNames	Array of String	out	List of objects that reside within the given bucket.

The options have the following structure:

Attribute	Type	Description	Examples
delimiter	String	Used to group keys as described in the AWS documentation. The CommonPrefixes return parameter is not returned yet.	`/`
encodingType	String	Used to encode object key names in the XML response as described in the AWS documentation.	`url`
maxKeys	Integer	Maximum number of keys returned in the response as described in the AWS documentation. 1000 is the maximal number of keys. Use maxKeys to reduce this limit.	`100`
prefix	String	Keys that begin with the indicated prefix as described in the AWS documentation.
continuationToken	String	Can be used for pagination of the list response as described in the AWS documentation. No valid token currently available from the xUML Runtime.
startAfter	String	If startAfter was sent with the request, it is included in the response as described in the AWS documentation.
requestPayer	String	Sets the `x-amz-request-payer` header on the request as described in the AWS documentation.
expectedBucketOwner	String	Sets the `x-amz-expected-bucket-owner` header on the request as described in the AWS documentation.
customizedAccessLogTag	Map	Let’s you include custom information to be stored in the access log record for a request as described in the AWS documentation.

Retrieving Bucket Information

Using the bucketStatus operation of the S3 adapter, you can get some general information on the bucket including a list of its contained objects.

Name	Type	Direction	Description	Allowed Values / Examples
bucketName	String	in	Name of the bucket to get the status of.
bucketStatus	BucketStatus	out	Object containing the status information as described for the BucketStatus type.

The returned bucketStatus information has the following structure:

Attribute	Type	Description
name	String	Name of the bucket.
size	Integer	Size of the bucket in bytes.
containedObjects	Array of String	List of objects that reside within the bucket.
creationDate	DateTime	Creation timestamp of the bucket.

Related Pages:

Handling of S3 Buckets

Handling of S3 Objects

S3 Adapter Reference