Merge pull request #5076 from JoshVanL/bindings-s3-bulk

[1.18] bindings/s3: bulk operations

Author: marcduiker

daprdocs/content/en/reference/components-reference/supported-bindings/s3.md

@@ -158,6 +158,9 @@ This component supports **output binding** with the following operations:
 - `get` : [Get object](#get-object)
 - `delete` : [Delete object](#delete-object)
 - `list`: [List objects](#list-objects)
+- `bulkGet`: [Bulk get objects](#bulk-get-objects)
+- `bulkCreate`: [Bulk create objects](#bulk-create-objects)
+- `bulkDelete`: [Bulk delete objects](#bulk-delete-objects)
 
 ### Create object
 
@@ -515,6 +518,178 @@ The list of objects will be returned as JSON array in the following form:
 }
 ```
 
+### Bulk get objects
+
+To download multiple objects in parallel, invoke the AWS S3 binding with a `POST` method and the following JSON body:
+
+```json
+{
+  "operation": "bulkGet",
+  "data": {
+    "items": [
+      { "key": "file1.txt" },
+      { "key": "file2.txt" },
+      { "key": "file3.txt", "filePath": "/tmp/file3.txt" }
+    ],
+    "concurrency": 5
+  }
+}
+```
+
+The data parameters are:
+
+- `items` - (required) an array of objects to download. Each item has:
+  - `key` - (required) the name of the S3 object.
+  - `filePath` - (optional) if provided, the object is streamed directly to this local file path instead of being returned in the response body.
+- `concurrency` - (optional) the maximum number of concurrent downloads. Defaults to `10`. Must be greater than `0`.
+
+The component-level `encodeBase64` metadata option applies to bulk get. When set to `"true"`, object contents are base64-encoded before being returned in the response body. When `filePath` is specified, the file will contain base64-encoded text rather than raw bytes.
+
+#### Example
+
+{{< tabpane text=true >}}
+
+  {{% tab "Windows" %}}
+  ```bash
+  curl -d "{ \"operation\": \"bulkGet\", \"data\": { \"items\": [{ \"key\": \"file1.txt\" }, { \"key\": \"file2.txt\" }], \"concurrency\": 5 } }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
+  ```
+  {{% /tab %}}
+
+  {{% tab "Linux" %}}
+  ```bash
+  curl -d '{ "operation": "bulkGet", "data": { "items": [{ "key": "file1.txt" }, { "key": "file2.txt" }], "concurrency": 5 } }' \
+        http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
+  ```
+  {{% /tab %}}
+
+{{< /tabpane >}}
+
+#### Response
+
+The response body contains a JSON array with a result for each requested item. Each result includes a per-item error field for partial failure semantics — the operation succeeds overall, and individual failures are reported per key:
+
+```json
+[
+  { "key": "file1.txt", "data": "contents of file1" },
+  { "key": "file2.txt", "data": "contents of file2" },
+  { "key": "missing.txt", "error": "object not found" }
+]
+```
+
+When `filePath` is specified for an item, the `data` field is omitted and the content is written to the specified file.
+
+### Bulk create objects
+
+To upload multiple objects in parallel, invoke the AWS S3 binding with a `POST` method and the following JSON body:
+
+```json
+{
+  "operation": "bulkCreate",
+  "data": {
+    "items": [
+      { "key": "file1.txt", "data": "Hello World" },
+      { "key": "file2.txt", "data": "Another file", "contentType": "text/plain" },
+      { "key": "file3.txt", "filePath": "/path/to/local/file.txt" }
+    ],
+    "concurrency": 5
+  }
+}
+```
+
+The data parameters are:
+
+- `items` - (required) an array of objects to upload. Each item has:
+  - `key` - (required) the name for the S3 object.
+  - `data` - the content to upload. Either `data` or `filePath` must be provided.
+  - `filePath` - a local file path to upload from. Either `data` or `filePath` must be provided.
+  - `contentType` - (optional) the MIME type of the object.
+- `concurrency` - (optional) the maximum number of concurrent uploads. Defaults to `10`. Must be greater than `0`.
+
+The component-level `decodeBase64` metadata option applies to bulk create. When set to `"true"`, the input is decoded from base64 before uploading to S3. This applies to both inline `data` fields and content read from `filePath` — use `filePath` with `decodeBase64` only when the file itself contains base64-encoded content.
+
+#### Example
+
+{{< tabpane text=true >}}
+
+  {{% tab "Windows" %}}
+  ```bash
+  curl -d "{ \"operation\": \"bulkCreate\", \"data\": { \"items\": [{ \"key\": \"file1.txt\", \"data\": \"Hello World\" }, { \"key\": \"file2.txt\", \"data\": \"Another file\" }] } }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
+  ```
+  {{% /tab %}}
+
+  {{% tab "Linux" %}}
+  ```bash
+  curl -d '{ "operation": "bulkCreate", "data": { "items": [{ "key": "file1.txt", "data": "Hello World" }, { "key": "file2.txt", "data": "Another file" }] } }' \
+        http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
+  ```
+  {{% /tab %}}
+
+{{< /tabpane >}}
+
+#### Response
+
+The response body contains a JSON array with a result for each item, including the location of the created object or a per-item error:
+
+```json
+[
+  { "key": "file1.txt", "location": "https://mybucket.s3.us-west-2.amazonaws.com/file1.txt" },
+  { "key": "file2.txt", "location": "https://mybucket.s3.us-west-2.amazonaws.com/file2.txt" },
+  { "key": "bad-file.txt", "error": "either data or filePath is required" }
+]
+```
+
+### Bulk delete objects
+
+To delete multiple objects in a single batch operation, invoke the AWS S3 binding with a `POST` method and the following JSON body:
+
+```json
+{
+  "operation": "bulkDelete",
+  "data": {
+    "keys": ["file1.txt", "file2.txt", "file3.txt"]
+  }
+}
+```
+
+The data parameters are:
+
+- `keys` - (required) an array of object key names to delete. Must contain at least one key.
+
+Bulk delete uses the S3 [DeleteObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) batch API. If more than 1,000 keys are provided, the request is automatically split into batches of 1,000.
+
+#### Example
+
+{{< tabpane text=true >}}
+
+  {{% tab "Windows" %}}
+  ```bash
+  curl -d "{ \"operation\": \"bulkDelete\", \"data\": { \"keys\": [\"file1.txt\", \"file2.txt\"] } }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
+  ```
+  {{% /tab %}}
+
+  {{% tab "Linux" %}}
+  ```bash
+  curl -d '{ "operation": "bulkDelete", "data": { "keys": ["file1.txt", "file2.txt"] } }' \
+        http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
+  ```
+  {{% /tab %}}
+
+{{< /tabpane >}}
+
+#### Response
+
+The response body contains a JSON array with a result for each key, including a per-item error field for partial failure semantics:
+
+```json
+[
+  { "key": "file1.txt" },
+  { "key": "file2.txt" },
+  { "key": "no-permission.txt", "error": "Access Denied" }
+]
+```
+
+An empty `error` field (or its absence) indicates successful deletion.
+
 ## Related links
 
 - [Basic schema for a Dapr component]({{% ref component-schema %}})