diff --git a/daprdocs/content/en/reference/components-reference/supported-bindings/s3.md b/daprdocs/content/en/reference/components-reference/supported-bindings/s3.md index e91231dbe27..685bb1a8cdb 100644 --- a/daprdocs/content/en/reference/components-reference/supported-bindings/s3.md +++ b/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:/v1.0/bindings/ + ``` + {{% /tab %}} + + {{% tab "Linux" %}} + ```bash + curl -d '{ "operation": "bulkGet", "data": { "items": [{ "key": "file1.txt" }, { "key": "file2.txt" }], "concurrency": 5 } }' \ + http://localhost:/v1.0/bindings/ + ``` + {{% /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:/v1.0/bindings/ + ``` + {{% /tab %}} + + {{% tab "Linux" %}} + ```bash + curl -d '{ "operation": "bulkCreate", "data": { "items": [{ "key": "file1.txt", "data": "Hello World" }, { "key": "file2.txt", "data": "Another file" }] } }' \ + http://localhost:/v1.0/bindings/ + ``` + {{% /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:/v1.0/bindings/ + ``` + {{% /tab %}} + + {{% tab "Linux" %}} + ```bash + curl -d '{ "operation": "bulkDelete", "data": { "keys": ["file1.txt", "file2.txt"] } }' \ + http://localhost:/v1.0/bindings/ + ``` + {{% /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 %}})