# ListObjects

Required Frends version: 5.7+

Required .NET version: 8.0

Compatible Agents: Unknown

Source code: <https://github.com/FrendsPlatform/Frends.AmazonS3>

{% tabs %}
{% tab title="Parameter: Connection" %}

| Name                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 🗝AwsAccessKeyId : `String`     | <p>AWS Access Key ID used for authentication with AWS services.</p><p><br>Default: <code>-</code><br>Example: <code>AKIAQWERTY7NJ5Q7NZ6Q</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 🗝AwsSecretAccessKey : `String` | <p>AWS Secret Access Key used for authentication with AWS services.</p><p><br>Default: <code>-</code><br>Example: <code>TVh5hgd3uGY/2CqH+Kkrrg3dadbXLsYe0jC3h+WD</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Region : `Region`               | <p>AWS Region where the S3 bucket is located.</p><p>Possible values:</p><ul><li><code>AfSouth1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>ApEast1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>ApNortheast1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>ApNortheast2</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>ApNortheast3</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>ApSouth1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>ApSoutheast1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>ApSoutheast2</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>CaCentral1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>CnNorth1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>CnNorthWest1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>EuCentral1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>EuNorth1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>EuSouth1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>EuWest1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>EuWest2</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>EuWest3</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>MeSouth1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>SaEast1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>UsEast1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>UsEast2</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>UsWest1</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><ul><li><code>UsWest2</code>:</li></ul><p>AWS Region where the S3 bucket is located.</p><p><br>Default: <code>-</code><br>Example: <code>EuCentral1</code></p> |
| {% endtab %}                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

{% tab title="Parameter: Input" %}

| Name                  | Description                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| BucketName : `String` | <p>The name of the S3 bucket to list objects from.</p><p><br>Default: <code>-</code><br>Example: <code>my-s3-bucket</code></p> |
| {% endtab %}          |                                                                                                                                |

{% tab title="Parameter: Options" %}

| Name                             | Description                                                                                                                                                                                                                                                                               |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Prefix : `String`                | <p>Limits the response to keys that begin with the specified prefix.</p><p><br>Default: <code>-</code><br>Example: <code>bucket/object1/object2</code></p>                                                                                                                                |
| Delimiter : `String`             | <p>A delimiter character used to group keys hierarchically.</p><p>See: <http://docs.aws.amazon.com/AmazonS3/latest/dev/ListingKeysHierarchy.html></p><p><br>Default: <code>-</code><br>Example: <code>/</code></p>                                                                        |
| MaxKeys : `Int32`                | <p>Sets the maximum number of keys returned in the response.</p><p>The response might contain fewer keys but will never contain more than this value.</p><p><br>Default: <code>1000</code><br>Example: <code>1000</code></p>                                                              |
| StartAfter : `String`            | <p>StartAfter specifies the key to start listing from (exclusive).</p><p>For example, in a bucket with objects { 20220401, 20220402, 20220403 },</p><p>StartAfter=20220401 returns objects 20220402 and 20220403.</p><p><br>Default: <code>-</code><br>Example: <code>20220401</code></p> |
| ThrowErrorOnFailure : `Boolean`  | <p>Determines whether to throw an exception on failure.</p><p>If set to false, returns a Result object with error information instead.</p><p><br>Default: <code>True</code><br>Example: <code>true</code></p>                                                                             |
| ErrorMessageOnFailure : `String` | <p>Custom error message to return when ThrowErrorOnFailure is false.</p><p>If not specified, the original error message will be used.</p><p><br>Default: <code>-</code><br>Example: <code>Failed to create object list</code></p>                                                         |
| {% endtab %}                     |                                                                                                                                                                                                                                                                                           |

{% tab title="Result: Result" %}

| Name                           | Description                                                                                                                                                                  |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Objects : `List<BucketObject>` | List of objects retrieved from the S3 bucket. Empty list if operation failed.                                                                                                |
| Success : `Boolean`            | Indicates whether the operation was successful.                                                                                                                              |
| Error : `Error`                | Error information if the operation failed.                                                                                                                                   |
| ErrorMessage : `String`        | Error message if the operation failed. Returns empty string if operation succeeded. Provided for backward compatibility - use Error property for detailed error information. |
| {% endtab %}                   |                                                                                                                                                                              |

{% tab title="Changelog" %}

## Changelog

### \[2.1.0] - 2025-12-29

#### Changed

* Updated AWS SDK version.

### \[2.0.0] - 2025-07-17

### \[Breaking] Major refactoring with new class structure and error handling

#### Added

* **Connection class**: New dedicated class for AWS connection parameters
  * `AwsAccessKeyId` - AWS access key ID for authentication
  * `AwsSecretAccessKey` - AWS secret access key for authentication
  * `Region` - AWS region for the S3 service
* **Options class**: New class for task configuration options
  * `ThrowErrorOnFailure` - Boolean flag to control error throwing behavior (default: false)
  * `ErrorMessageOnFailure` - Custom error message for failures (default: empty string)
* **Error class**: New structured error handling
  * `Message` - Error message string
  * `AdditionalInfo` - Dynamic property for additional error context
* **ErrorHandler class**: New static utility class for centralized error handling
  * `Handle` method for consistent error processing across the task
* **Result.Success**: New boolean property indicating task execution success
* **Result.Error**: New error property for structured error information

#### Changed

* **\[Breaking]** Renamed `Source` class to `Input` class
* **\[Breaking]** Moved AWS credentials from Input to Connection class:
  * `Input.AwsAccessKeyId` → `Connection.AwsAccessKeyId`
  * `Input.AwsSecretAccessKey` → `Connection.AwsSecretAccessKey`
  * `Input.Region` → `Connection.Region`
* **\[Breaking]** Renamed `Result.ObjectList` to `Result.Objects`
* **\[Breaking]** Task method signature now includes Connection and Options parameters
* Improved error handling with consistent error structure and configurable error behavior

### \[1.0.0] - 2022-04-25

#### Added

* Initial implementation
  {% endtab %}
  {% endtabs %}