diff --git a/src/pages/[platform]/build-a-backend/storage/copy-files/index.mdx b/src/pages/[platform]/build-a-backend/storage/copy-files/index.mdx index ea7a3fc485c..51b86297bb8 100644 --- a/src/pages/[platform]/build-a-backend/storage/copy-files/index.mdx +++ b/src/pages/[platform]/build-a-backend/storage/copy-files/index.mdx @@ -134,12 +134,48 @@ Future copy() async { } } ``` +## Specify a bucket or copy across buckets / regions -## More `copy` options +You can also perform a `copy` operation to a specific bucket by providing the `CopyBuckets` option. +This option is an object that takes two `StorageBucket` parameters, which can be constructed by the specified name in the Amplify Backend, or the bucket name and region from the console. + +```dart +final mainBucket = StorageBucket.fromOutputs( + 'mainBucket', +); +final bucket2 = StorageBucket.fromBucketInfo( + BucketInfo( + bucketName: 'second-bucket-name-from-console', + region: 'us-east-2', + ), +), +try { + final result = await Amplify.Storage.copy( + source: const StoragePath.fromString('album/2024/1.jpg'), + destination: const StoragePath.fromString('shared/2024/1.jpg'), + options: StorageCopyOptions( + buckets: CopyBuckets( + source: bucket1, + destination: bucket2, + ), + ), + ).result; + safePrint('Copied file: ${result.copiedItem.path}'); +} on StorageException catch (e) { + print('Error: $e'); +} +``` + + +In order to copy to or from a bucket other than your default, the source and/or destination paths must exist in that bucket + + +## `copy` options Option | Type | Description | | -- | -- | ----------- | | getProperties | boolean | Whether to retrieve properties for the copied object using theAmplify.Storage.getProperties() after the operation completes. When set to true the returned item will contain additional info such as metadata and content type. | +| buckets | CopyBuckets | An object that accepts two `StorageBucket` parameters. To copy to and from the same bucket, use the `CopyBuckets.sameBucket(targetBucket)` method, where `targetBucket` is a `StorageBucket`. Read more at [Configure additional storage buckets](/[platform]/build-a-backend/storage/set-up-storage/#configure-additional-storage-buckets)| Example of `copy` with options: @@ -151,6 +187,9 @@ final result = Amplify.Storage.copy( pluginOptions: S3CopyPluginOptions( getProperties: true, ), + buckets: CopyBuckets.sameBucket( + StorageBucket.fromOutputs('secondBucket'), + ), ), ); ``` diff --git a/src/pages/[platform]/build-a-backend/storage/download-files/index.mdx b/src/pages/[platform]/build-a-backend/storage/download-files/index.mdx index 9c0c57daad8..56c2d5ba134 100644 --- a/src/pages/[platform]/build-a-backend/storage/download-files/index.mdx +++ b/src/pages/[platform]/build-a-backend/storage/download-files/index.mdx @@ -288,13 +288,21 @@ Option | Type | Description | When creating a downloadable URL, you can choose to check if the file exists by setting `validateObjectExistence` to `true` in `S3GetUrlPluginOptions`. If the file is inaccessible or does not exist, a `StorageException` is thrown. This allows you to check if an object exists during generating the presigned URL, which you can then use to download -that object. +that object. You may also pass in a bucket to target into `StorageGetUrlOptions` from either the chosen name in the +backend or the console name and region. If no bucket is provided, the default bucket defined in the backend will be used. +Read more at [Configure additional storage buckets](/[platform]/build-a-backend/storage/set-up-storage/#configure-additional-storage-buckets) ```dart Future getDownloadUrl() async { try { final result = await Amplify.Storage.getUrl( path: const StoragePath.fromString('public/example.txt'), + /* + // targeting a specific bucket by the name defined in the backend + options: StorageGetUrlOptions( + bucket: StorageBucket.fromOutputs('secondBucket'), + ), + */ ).result; safePrint('url: ${result.url}'); } on StorageException catch (e) { @@ -678,7 +686,6 @@ const result = await downloadData({ }).result; ``` - ### Monitor download progress ```javascript @@ -714,7 +721,6 @@ try { ``` - ### Download from a specified bucket @@ -1101,6 +1107,7 @@ Future download() async { Option | Type | Description | | -- | -- | ----------- | +| bucket | StorageBucket | The target bucket from the assigned name in the Amplify Backend or from the bucket name and region in the console

Defaults to the default bucket and region from the Amplify configuration if this option is not provided.

Read more at [Configure additional storage buckets](/[platform]/build-a-backend/storage/set-up-storage/#configure-additional-storage-buckets) | | getProperties | boolean | Whether to retrieve properties for the downloaded object using theAmplify.Storage.getProperties() after the operation completes. When set to true the returned item will contain additional info such as metadata and content type. | | useAccelerateEndpoint | boolean | Whether to use accelerate endpoint.

Read more at [Transfer Acceleration](/[platform]/build-a-backend/storage/upload-files/#transfer-acceleration) | | bytesRange | S3DataBytesRange | The byte range to download from the object | @@ -1116,6 +1123,7 @@ final operation = Amplify.Storage.downloadFile( getProperties: true, useAccelerateEndpoint: true, ), + bucket: StorageBucket.fromOutputs('secondBucket'), ), ); ``` @@ -1135,6 +1143,42 @@ final operation = Amplify.Storage.downloadData( ); ``` +You can also perform a `downloadData` or `downloadFile` operation to a specific bucket by providing the `bucket` option. You can pass in a `StorageBucket` object representing the target bucket from the name defined in the Amplify Backend. + +```dart +final operation = Amplify.Storage.downloadFile( + path: const StoragePath.fromString('public/example.txt'), + localFile: AWSFile.fromPath('/path/to/local/file.txt'), + options: const StorageDownloadFileOptions( + pluginOptions: S3DownloadFilePluginOptions( + getProperties: true, + useAccelerateEndpoint: true, + ), + bucket: StorageBucket.fromOutputs('secondBucket'), + ), +); +``` + +Alternatively, you can also pass in an object by specifying the bucket name and region from the console. + +```dart +final operation = Amplify.Storage.downloadData( + path: const StoragePath.fromString('public/example.txt'), + options: StorageDownloadDataOptions( + pluginOptions: S3DownloadDataPluginOptions( + getProperties: true, + useAccelerateEndpoint: true, + bytesRange: S3DataBytesRange(start: 0, end: 100), + ), + bucket: StorageBucket.fromBucketInfo( + BucketInfo( + bucketName: 'second-bucket-name-from-console', + region: 'us-east-2', + ), + ), + ), +); +``` diff --git a/src/pages/[platform]/build-a-backend/storage/list-files/index.mdx b/src/pages/[platform]/build-a-backend/storage/list-files/index.mdx index 546124747a9..4d7d4976d4a 100644 --- a/src/pages/[platform]/build-a-backend/storage/list-files/index.mdx +++ b/src/pages/[platform]/build-a-backend/storage/list-files/index.mdx @@ -1010,11 +1010,47 @@ Future listAllUnderPublicPath() async { } ``` + + +### List files from a specified bucket +You can also perform a `list` operation to a specific bucket by providing the `bucket` option. You can pass in a `StorageBucket` object representing the target bucket from the name defined in the Amplify Backend. + +```dart +final result = await Amplify.Storage.list( + path: const StoragePath.fromString('path/to/dir'), + options: StorageListOptions( + // highlight-start + // Specify a target bucket using name assigned in Amplify Backend + bucket: StorageBucket.fromOutputs('secondBucket'), + // highlight-end + ), +).result; +``` +Alternatively, you can also pass in an object by specifying the bucket name and region from the console. + +```dart +final result = await Amplify.Storage.list( + path: const StoragePath.fromString('path/to/dir'), + options: StorageListOptions( + // highlight-start + // Alternatively, provide bucket name from console and associated region + bucket: StorageBucket.fromBucketInfo( + BucketInfo( + bucketName: 'second-bucket-name-from-console', + region: 'us-east-2', + ), + ), + // highlight-end + ), +).result; +``` + ### More `list` options | Option | Type | Description | | --- | --- | --- | +| bucket | StorageBucket | The target bucket from the assigned name in the Amplify Backend or from the bucket name and region in the console

Defaults to the default bucket and region from the Amplify configuration if this option is not provided.

Read more at [Configure additional storage buckets](/[platform]/build-a-backend/storage/set-up-storage/#configure-additional-storage-buckets) | | excludeSubPaths | boolean | Whether to exclude objects under the sub paths of the path to list. Defaults to false. | | delimiter | String | The delimiter to use when evaluating sub paths. If excludeSubPaths is false, this value has no impact on behavior. | @@ -1093,6 +1129,35 @@ Future getFileProperties() async { } ``` +As well as specify a bucket to target to view properties of a file + +```dart +Future getFileProperties() async { + try { + final result = await Amplify.Storage.getProperties( + path: const StoragePath.fromString('example.txt'), + options: StorageGetPropertiesOptions( + StorageBucket.fromOutputs('secondBucket'), + ), + // Alternatively, provide bucket name from console and associated region + /* + options: StorageGetPropertiesOptions( + bucket: StorageBucket.fromBucketInfo( + BucketInfo( + bucketName: 'second-bucket-name-from-console', + region: 'us-east-2', + ), + ), + ), + */ + ).result; + safePrint('File size: ${result.storageItem.size}'); + } on StorageException catch (e) { + safePrint(e.message); + } +} +``` + To get the metadata in result for all APIs when building against a web target, you have to configure user defined metadata in CORS. diff --git a/src/pages/[platform]/build-a-backend/storage/remove-files/index.mdx b/src/pages/[platform]/build-a-backend/storage/remove-files/index.mdx index 27e081ec6eb..a52d3dee967 100644 --- a/src/pages/[platform]/build-a-backend/storage/remove-files/index.mdx +++ b/src/pages/[platform]/build-a-backend/storage/remove-files/index.mdx @@ -341,28 +341,42 @@ let removedObject = try await Amplify.Storage.remove( -## Remove single file - -You can remove a single file using `Amplify.Storage.remove` with the `key` and its associated access level: +You can also perform a `remove` operation to a specific bucket by providing the `bucket` option. You can pass in a `StorageBucket` object representing the target bucket from the name defined in the Amplify Backend. ```dart +final result = await Amplify.Storage.remove( + path: const StoragePath.fromString('path/to/file.txt'), + options: StorageRemoveOptions( + // highlight-start + // Specify a target bucket using name assigned in Amplify Backend + bucket: StorageBucket.fromOutputs('secondBucket'), + // highlight-end + ), +).result; +``` -Future removeFile() async { - try { - final result = await Amplify.Storage.remove( - path: const StoragePath.fromString('public/file.txt'), - ).result; - safePrint('Removed file: ${result.removedItem.path}'); - } on StorageException catch (e) { - safePrint(e.message); - } -} +Alternatively, you can also pass in an object by specifying the bucket name and region from the console. +```dart +final result = await Amplify.Storage.remove( + path: const StoragePath.fromString('path/to/file.txt'), + options: StorageRemoveOption( + // highlight-start + // Alternatively, provide bucket name from console and associated region + bucket: StorageBucket.fromBucketInfo( + BucketInfo( + bucketName: 'second-bucket-name-from-console', + region: 'us-east-2', + ), + ), + // highlight-end + ), +).result; ``` ## Remove multiple Files -You can remove multiple files using `Amplify.Storage.removeMany` with the `keys`, the files to be removed in a batch should have the same access level: +You can remove multiple files using `Amplify.Storage.removeMany`, as well as specify a bucket to target, the files to be removed in a batch should have the same access level: ```dart Future remove() async { @@ -372,6 +386,18 @@ Future remove() async { const StoragePath.fromString('public/file-1.txt'), const StoragePath.fromString('public/file-2.txt'), ], + // if this option is not provided, the default bucket in the Amplify Backend will be used + options: StorageRemoveManyOptions( + bucket: StorageBucket.fromOutputs('secondBucket'), + /* Alternatively, provide bucket name from console and associated region + bucket: StorageBucket.fromBucketInfo( + BucketInfo( + bucketName: 'second-bucket-name-from-console', + region: 'us-east-2', + ), + ), + */ + ), ).result; safePrint('Removed files: ${result.removedItems}'); } on StorageException catch (e) { diff --git a/src/pages/[platform]/build-a-backend/storage/set-up-storage/index.mdx b/src/pages/[platform]/build-a-backend/storage/set-up-storage/index.mdx index 9b18f2bccd1..6f2eccb9fa7 100644 --- a/src/pages/[platform]/build-a-backend/storage/set-up-storage/index.mdx +++ b/src/pages/[platform]/build-a-backend/storage/set-up-storage/index.mdx @@ -363,6 +363,54 @@ let downloadTask = Amplify.Storage.downloadData( ``` + +### Storage bucket client usage + +Additional storage buckets can be referenced from application code by passing the `bucket` option to Amplify Storage APIs. You can provide a target bucket's name assigned in Amplify Backend. + +```dart +import 'package:amplify_flutter/amplify_flutter.dart'; + +try { + final result = await Amplify.Storage.downloadData( + path: const StoragePath.fromString('album/2024/1.jpg'), + options: StorageDownloadDataOptions( + // highlight-start + // Specify a target bucket using name assigned in Amplify Backend + bucket: StorageBucket.fromOutputs('secondBucket'), + // highlight-end + ), + ).result; +} on Exception catch (e) { + print('Error: $e'); +} +``` +Alternatively, you can also pass in an object by specifying the bucket name and region from the console. See each Amplify Storage API page for additional usage examples. + +```dart +import 'package:amplify_flutter/amplify_flutter.dart'; + +try { + final result = await Amplify.Storage.downloadData( + path: const StoragePath.fromString('album/2024/1.jpg'), + options: const StorageDownloadDataOptions( + // highlight-start + // Alternatively, provide bucket name from console and associated region + bucket: StorageBucket.fromBucketInfo( + BucketInfo( + bucketName: 'second-bucket-name-from-console', + region: 'us-east-2', + ), + ), + // highlight-end + ), + ).result; +} on Exception catch (e) { + print('Error: $e'); +} +``` + + ## Connect your app code to the storage backend The Amplify Storage library provides client APIs that connect to the backend resources you defined. diff --git a/src/pages/[platform]/build-a-backend/storage/upload-files/index.mdx b/src/pages/[platform]/build-a-backend/storage/upload-files/index.mdx index ce8b9c66477..f8cbb5ef352 100644 --- a/src/pages/[platform]/build-a-backend/storage/upload-files/index.mdx +++ b/src/pages/[platform]/build-a-backend/storage/upload-files/index.mdx @@ -647,10 +647,52 @@ Future upload() async { +### Upload to a specified bucket + +You can also perform an `upload` operation to a specific bucket by providing the `bucket` option. You can pass in a `StorageBucket` object representing the target bucket from the name defined in the Amplify Backend. + +```dart +final data = 'multi bucket upload data byte'.codeUnits; +final result = await Amplify.Storage.uploadData( + data: StorageDataPayload.bytes(data), + path: const StoragePath.fromString('path/to/file.txt'), + options: StorageUploadDataOptions( + // highlight-start + // Specify a target bucket using name assigned in Amplify Backend + bucket: StorageBucket.fromOutputs('secondBucket'), + // highlight-end + ), +).result; +``` +Alternatively, you can also pass in an object by specifying the bucket name and region from the console. + +```dart +final data = 'multi bucket upload data byte'.codeUnits; +final result = await Amplify.Storage.uploadData( + data: StorageDataPayload.bytes(data), + path: const StoragePath.fromString('path/to/file.txt'), + options: StorageUploadDataOptions( + // highlight-start + // Alternatively, provide bucket name from console and associated region + bucket: StorageBucket.fromBucketInfo( + BucketInfo( + bucketName: 'second-bucket-name-from-console', + region: 'us-east-2', + ), + ), + // highlight-end + ), +).result; +``` + + + + ### More upload options Option | Type | Description | | -- | -- | ----------- | +| bucket | StorageBucket | The target bucket from the assigned name in the Amplify Backend or from the bucket name and region in the console

Defaults to default bucket and region from the Amplify configuration if this option is not provided.

Read more at [Configure additional storage buckets](/[platform]/build-a-backend/storage/set-up-storage/#configure-additional-storage-buckets) | | getProperties | boolean | Whether to retrieve properties for the uploaded object using theAmplify.Storage.getProperties() after the operation completes. When set to true the returned item will contain additional info such as metadata and content type. | | useAccelerateEndpoint | boolean | Whether to use accelerate endpoint.

Read more at [Transfer Acceleration](/[platform]/build-a-backend/storage/upload-files/#transfer-acceleration) |