Amazon S3

Entities, operations, and actions

All the Integration Connectors provide a layer of abstraction for the objects of the connected application. You can access an application's objects only through this abstraction. The abstraction is exposed to you as entities, operations, and actions.

• Entity: An entity can be thought of as an object, or a collection of properties, in the connected application or service. The definition of an entity differs from a connector to a connector. For example, in a database connector, tables are the entities, in a file server connector, folders are the entities, and in a messaging system connector, queues are the entities.

  However, it is possible that a connector doesn't support or have any entities, in which case the Entities list will be empty.

• Operation: An operation is the activity that you can perform on an entity. You can perform any of the following operations on an entity:
  • List
  • Get
  • Create
  • Update
  • Delete

  Selecting an entity from the available list, generates a list of operations available for the entity. For a detailed description of the operations, see the Connectors task's entity operations. However, if a connector doesn't support any of the entity operations, such unsupported operations aren't listed in the Operations list.

• Action: An action is a first class function that is made available to the integration through the connector interface. An action lets you make changes to an entity or entities, and vary from connector to connector. Normally, an action will have some input parameters, and an output parameter. However, it is possible that a connector doesn't support any action, in which case the Actions list will be empty.

Actions

This section lists some of the actions supported by the connector. To understand how to configure the actions, see Action examples.

CopyObject action

This action lets you copy an object from one bucket to another bucket or within the same bucket.

Input parameters of the CopyObject action

Output parameters of the CopyObject action

This action returns the status 200 (OK) if the copy is successful.

To understand how to configure the CopyObject action, see Action examples.

DownloadObjects action

This action gets one more objects from a bucket.

Input parameters of the DownloadObjects action

Output parameters of the DownloadObjects action

This action returns the status 200 (OK) if the download is successful.

To understand how to configure the DownloadObjects action, see Action examples.

UploadObject action

This action lets you upload an object to a bucket.

Input parameters of the UploadObject action

Output parameters of the UploadObject action

This action returns the status 200 (OK) if the object upload is successful.

To understand how to configure the UploadObject action, see Action examples.

DeleteObject Action

This action lets you delete an object from a bucket.

Input parameters of the DeleteObject action

Output parameters of the DeleteObject action

This action returns the status 200 (OK) if the deletion is successful.

To understand how to configure the DeleteObject action, see Action examples.

MoveObject action

This action let users move an existing object of a specific bucket to another bucket or in the same bucket.

Input parameters of the MoveObject action

Output parameters of the MoveObject action

This action returns the status 200 (OK) if the move operation is successful.

To understand how to configure the MoveObject action, see Action examples.

PutBucketAcl action

This action lets you update the Access Control List (ACL) of a bucket.

Input parameters of the PutBucketAcl action

Output parameters of the PutBucketAcl action

This action returns the status 200 (OK) if the bucket ACL update is successful.

To understand how to configure the PutBucketAcl action, see Action examples.

PutObjectAcl action

This action lets you update the Access Control List (ACL) of an object in a bucket.

Input parameters of the PutObjectAcl action

Output parameters of the PutObjectAcl action

This action returns the status 200 (OK) if the object ACL update is successful.

To understand how to configure the PutObjectAcl action, see Action examples.

Action examples

This section describes how to perform some of the actions in this connector.

Example - Copy an object

This example copies an object from one bucket to another bucket.

1. In the Configure connector task dialog, click Actions.
2. Select the CopyObject action, and then click Done.
3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field:

   {
   "BucketSource": "aws-s3-bucket-source",
   "ObjectSource": "pic.jpg",
   "BucketDestination": "aws-s3-bucket-destination",
   "ObjectDestination": "new_pic.jpg"
   }

If the action is successful, the CopyObject task's connectorOutputPayload response parameter will have a value similar to the following:

[{
"Status": "Success"
}]

Example - Download an object

This example downloads an object from the specified bucket.

1. In the Configure connector task dialog, click Actions.
2. Select the DownloadObjects action, and then click Done.
3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field:

   {
   "Bucket": "aws-s3-bucket-source",
   "HasBytes": true
   }

If the action is successful, the DownloadObjects task's connectorOutputPayload response parameter will have a value similar to the following:

[{
"Success": "True",
"RemoteFile": "prefix1%2Faws-s3-bucket-source%2Finventory-test-1%2F2023-09-10T01-00Z%2Fmanifest.json",
"ContentBytes": "ewogICJzb3VyY2VCdWNrZXQiIDogImF3cy1zMy1idWNrZXQtYmNvbmUiLAogICJnOK"
},
{
"Success": "True",
"RemoteFile": "upload1.txt",
"ContentBytes": "VGhpcyBpcyBhIHRlc3RpbmcgZmlsZQ=="
}]

Example - Upload an object

This example uploads an object to the specified bucket.

1. In the Configure connector task dialog, click Actions.
2. Select the UploadObject action, and then click Done.
3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field:

   {
   "Bucket": "aws-s3-bucket-source",
   "FileName": "upload_1.txt",
   "Content": "This is a testing file",
   "AccessPolicy": "PUBLIC"
   }

If the action is successful, the UploadObject task's connectorOutputPayload response parameter will have a value similar to the following:

[{
"Status": "success",
"bucket": "aws-s3-bucket-source",
"rss:title": "Object 'upload_1.txt' was created in the bucket: aws-s3-bucket-source",
"object": "upload_1.txt"
}]

Example - Delete an object

This example deletes an object from the specified bucket.

1. In the Configure connector task dialog, click Actions.
2. Select the DeleteObject action, and then click Done.
3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field:

   {
   "Bucket": "aws-s3-bucket-source",
   "Object": "abc.png"
   }

If the action is successful, the DeleteObject task's connectorOutputPayload response parameter will have a value similar to the following:

[{
"Status": "Success"
}]

Example - Move an object

This example moves an object from one bucket to another bucket.

1. In the Configure connector task dialog, click Actions.
2. Select the MoveObject action, and then click Done.
3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field:

   {
   "BucketSource": "aws-s3-bucket-source",
   "ObjectSource": "abc.png",
   "BucketDestination": "aws-s3-bucket-destination",
   "ObjectDestination": "moved.png"
   }

If the action is successful, the MoveObject task's connectorOutputPayload response parameter will have a value similar to the following:

[{
"Status": "Success"
}]

Example - Update the ACL of a bucket

This example updates the access control permissions for a bucket.

1. In the Configure connector task dialog, click Actions.
2. Select the PutBucketAcl action, and then click Done.
3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field:

   {
   "BucketSource": "aws-s3-bucket-source",
   "ACL": "public-read"
   }

If the action is successful, the PutBucketAcl task's connectorOutputPayload response parameter will have a value similar to the following:

[{
"Status": "Success"
}]

Example - Update the ACL of an object

This example updates the access control permissions for an object in a bucket.

1. In the Configure connector task dialog, click Actions.
2. Select the PutObjectAcl action, and then click Done.
3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field:

   {
   "Bucket": "aws-s3-bucket-source",
   "ACL": "aws-exec-read",
   "Key": "AWS_S3_BusinessCase_V2.xlsx"
   }

If the action is successful, the PutObjectAcl task's connectorOutputPayload response parameter will have a value similar to the following:

[{
"Status": "Success"
}]

Entity operation examples

This section shows how to perform some of the entity operations in this connector.

Example - List metadata of all the objects

This example fetches the metadata of all the objects in the Object entity.

1. In the Configure connector task dialog, click Entities.
2. Select Object from the Entity list.
3. Select the List operation, and then click Done.
4. Optionally, in Task Input section of the Connectors task, you can filter your result set by specifying a filter clause. Specify the filter clause value always within the single quotes ('). For example, Bucket='test-bucket'. You can also specify multiple filter conditions by using the logic operators. For example, Bucket='test-bucket' and OwnerId='b1ecc809ad8467088afb'.

Example - Get metadata of a bucket

This example gets the metadata of the bucket with the specified ID from the Bucket entity.

1. In the Configure connector task dialog, click Entities.
2. Select Bucket from the Entity list.
3. Select the Get operation, and then click Done.
4. In the Task Input section of the Connectors task, click EntityId and then enter demo_replication in the Default Value field.

   Here, demo_replication is a unique bucket ID in the Bucket entity.

Example - Create a bucket

This example creates a bucket in the Bucket entity.

1. In the Configure connector task dialog, click Entities.
2. Select Bucket from the Entity list.
3. Select the Create operation, and then click Done.
4. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field:

   {
   "Bucket": "Demo1697528098686"
   }

   If the integration is successful, your connector task's connectorOutputPayload field will have a value similar to the following:

   [{
   "Bucket": "Demo1697528098686"
   }]

Example - Delete a bucket

This example deletes the bucket with the specified ID in the Bucket entity.

1. In the Configure connector task dialog, click Entities.
2. Select Bucket from the Entity list.
3. Select the Delete operation, and then click Done.
4. In the Task Input section of the Connectors task, click entityId and then enter demo1697528098686 in the Default Value field.