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 a269f6337ca..9c0c57daad8 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 @@ -237,18 +237,22 @@ RxAmplify.Storage.getUrl(StoragePath.fromString("public/example"), options).subs -### More `getURL` options +### All `getURL` options Option | Type | Description | | -- | -- | ----------- | -| expires | Integer | Number of seconds before the URL expires | -| useAccelerateEndpoint | Boolean | Flag to configure use of acceleration mode | +| bucket | StorageBucket | The bucket in which the object is stored. | +| expires | Integer | Number of seconds before the URL expires. | +| useAccelerateEndpoint | Boolean | Flag to configure use of acceleration mode. | +| validateObjectExistence | Boolean | Flag to check if the file exists. | ```swift -let url = try await Amplify.Storage.getURL(path: .fromString("public/example/path")) +let url = try await Amplify.Storage.getURL( + path: .fromString("public/example/path") +) print("Completed: \(url)") ``` @@ -270,11 +274,12 @@ let url = try await Amplify.Storage.getURL( ) ``` -### More `getURL` options +### All `getURL` options Option | Type | Description | | -- | -- | ----------- | -| expires | Integer | Number of seconds before the URL expires | +| expires | Int | Number of seconds before the URL expires | +| bucket | StorageBucket | The bucket in which the object is stored | @@ -300,9 +305,8 @@ Future getDownloadUrl() async { -## Download to a file - +## Download to a file Use the `downloadData` API to download the file locally. @@ -317,6 +321,7 @@ const { body, eTag } = await downloadData({ +## Download to a file Use the `downloadFile` API to download the file locally on the client. @@ -366,7 +371,7 @@ try { RxProgressAwareSingleOperation download = RxAmplify.Storage.downloadFile( StoragePath.fromString("public/example"), - new File(getApplicationContext().getFilesDir() + "/download.txt" + new File(getApplicationContext().getFilesDir() + "/download.txt") ); download @@ -382,6 +387,8 @@ download +## Download files +### Download to a local file Use the `downloadFile` API to download the file locally on the client. @@ -391,14 +398,14 @@ You can download to a file [URL](https://developer.apple.com/documentation/found ```swift -let downloadToFileName = FileManager.default.urls( +let downloadToFileUrl = FileManager.default.urls( for: .documentDirectory, in: .userDomainMask )[0].appendingPathComponent("myFile.txt") let downloadTask = Amplify.Storage.downloadFile( path: .fromString("public/example/path"), - local: downloadToFileName, + local: downloadToFileUrl, options: nil ) Task { @@ -412,14 +419,14 @@ print("Completed") ```swift -let downloadToFileName = FileManager.default.urls( +let downloadToFileUrl = FileManager.default.urls( for: .documentDirectory, in: .userDomainMask )[0].appendingPathComponent("myFile.txt") let downloadTask = Amplify.Storage.downloadFile( path: .fromString("public/example/path"), - local: downloadToFileName, + local: downloadToFileUrl, options: nil ) let progressSink = downloadTask @@ -441,9 +448,120 @@ let resultSink = downloadTask ``` + +### Download to data in memory + +You can download to in-memory buffer [Data](https://developer.apple.com/documentation/foundation/data) object with `Amplify.Storage.downloadData`: + + + + + +```swift +let downloadTask = Amplify.Storage.downloadData( + path: .fromString("public/example/path") +) +Task { + for await progress in await downloadTask.progress { + print("Progress: \(progress)") + } +} +let data = try await downloadTask.value +print("Completed: \(data)") +``` + + + + + +```swift +let downloadTask = Amplify.Storage.downloadData( + path: .fromString("public/example/path") +) +let progressSink = downloadTask + .inProcessPublisher + .sink { progress in + print("Progress: \(progress)") + } + +let resultSink = downloadTask + .resultPublisher + .sink { + if case let .failure(storageError) = $0 { + print("Failed: \(storageError.errorDescription). \(storageError.recoverySuggestion)") + } + } + receiveValue: { data in + print("Completed: \(data)") + } +``` + + + + + +### Download from a specified bucket + +You can also perform a download operation from a specific bucket by providing the `bucket` option + + + +You can use `.fromOutputs(name:)` to provide a string representing the target bucket's assigned name in the Amplify Backend. + +```swift +// Download to File +let downloadTask = Amplify.Storage.downloadFile( + path: .fromString("public/example/path"), + local: downloadToFileUrl, + options: .init( + bucket: .fromOutputs(name: "secondBucket") + ) +) + +// Download to Data +let downloadTask = Amplify.Storage.downloadData( + path: .fromString("public/example/path"), + options: .init( + bucket: .fromOutputs(name: "secondBucket") + ) +) +``` + + + +You can also use `.fromBucketInfo(_:)` to provide a bucket name and region directly. + +```swift +// Download to File +let downloadTask = Amplify.Storage.downloadFile( + path: .fromString("public/example/path"), + local: downloadToFileUrl, + options: .init( + bucket: .fromBucketInfo(.init( + bucketName: "another-bucket-name", + region: "another-bucket-region") + ) + ) +) + +// Download to Data +let downloadTask = Amplify.Storage.downloadData( + path: .fromString("public/example/path"), + options: .init( + bucket: .fromBucketInfo(.init( + bucketName: "another-bucket-name", + region: "another-bucket-region") + ) + ) +) +``` + + + +## Download to a file You can download a file to a local directory using `Amplify.Storage.downloadFile`. @@ -521,57 +639,6 @@ try { ``` - - -## API to download data in memory - -You can download to in-memory buffer [Data](https://developer.apple.com/documentation/foundation/data) object with `Amplify.Storage.downloadData`: - - - - - -```swift -let downloadTask = Amplify.Storage.downloadData(path: .fromString("public/example/path")) -Task { - for await progress in await downloadTask.progress { - print("Progress: \(progress)") - } -} -let data = try await downloadTask.value -print("Completed: \(data)") -``` - - - - - -```swift -let downloadTask = Amplify.Storage.downloadData(path: .fromString("public/example/path")) -let progressSink = downloadTask - .inProcessPublisher - .sink { progress in - print("Progress: \(progress)") - } - -let resultSink = downloadTask - .resultPublisher - .sink { - if case let .failure(storageError) = $0 { - print("Failed: \(storageError.errorDescription). \(storageError.recoverySuggestion)") - } - } - receiveValue: { data in - print("Completed: \(data)") - } -``` - - - - - - - ### Download from a specified bucket @@ -650,6 +717,152 @@ try { +### Download from a specified bucket + +You can also perform a download operation to a specific bucket by providing the `bucket` option. You can pass in a string representing the target bucket's assigned name in Amplify Backend. + + + + +```java +StorageBucket secondBucket = StorageBucket.fromOutputs("secondBucket"); +StorageDownloadFileOptions options = StorageDownloadFileOptions.builder().bucket(secondBucket).build(); +Amplify.Storage.downloadFile( + StoragePath.fromString("public/example"), + new File(getApplicationContext().getFilesDir() + "/download.txt"), + options, + result -> Log.i("MyAmplifyApp", "Successfully downloaded: " + result.getFile().getName()), + error -> Log.e("MyAmplifyApp", "Download Failure", error) +); +``` + + + + +```kotlin +val secondBucket = StorageBucket.fromOutputs("secondBucket") +val options = StorageDownloadFileOptions.builder().bucket(secondBucket).build() +val file = File("${applicationContext.filesDir}/download.txt") +Amplify.Storage.downloadFile(StoragePath.fromString("public/example"), file, option, + { Log.i("MyAmplifyApp", "Successfully downloaded: ${it.file.name}") }, + { Log.e("MyAmplifyApp", "Download Failure", it) } +) +``` + + + + +```kotlin +val secondBucket = StorageBucket.fromOutputs("secondBucket") +val options = StorageDownloadFileOptions.builder().bucket(secondBucket).build() +val file = File("${applicationContext.filesDir}/download.txt") +val download = Amplify.Storage.downloadFile(StoragePath.fromString("public/example"), file, options) +try { + val fileName = download.result().file.name + Log.i("MyAmplifyApp", "Successfully downloaded: $fileName") +} catch (error: StorageException) { + Log.e("MyAmplifyApp", "Download Failure", error) +} +``` + + + + +```java +StorageBucket secondBucket = StorageBucket.fromOutputs("secondBucket"); +StorageDownloadFileOptions options = StorageDownloadFileOptions.builder().bucket(secondBucket).build(); +RxProgressAwareSingleOperation download = + RxAmplify.Storage.downloadFile( + StoragePath.fromString("public/example"), + new File(getApplicationContext().getFilesDir() + "/download.txt"), + options + ); + +download + .observeResult() + .subscribe( + result -> Log.i("MyAmplifyApp", "Successfully downloaded: " + result.getFile().getName()), + error -> Log.e("MyAmplifyApp", "Download Failure", error) + ); +``` + + + + +Alternatively, you can also pass in an object by specifying the bucket name and region from the console. + + + + +```java +BucketInfo bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2"); +StorageBucket secondBucket = StorageBucket.fromBucketInfo(bucketInfo); +StorageDownloadFileOptions options = StorageDownloadFileOptions.builder().bucket(secondBucket).build(); +Amplify.Storage.downloadFile( + StoragePath.fromString("public/example"), + new File(getApplicationContext().getFilesDir() + "/download.txt"), + options, + result -> Log.i("MyAmplifyApp", "Successfully downloaded: " + result.getFile().getName()), + error -> Log.e("MyAmplifyApp", "Download Failure", error) +); +``` + + + + +```kotlin +val bucketInfo = BucketInfo("second-bucket-name-from-console", "us-east-2") +val secondBucket = StorageBucket.fromBucketInfo(bucketInfo) +val options = StorageDownloadFileOptions.builder().bucket(secondBucket).build() +val file = File("${applicationContext.filesDir}/download.txt") +Amplify.Storage.downloadFile(StoragePath.fromString("public/example"), file, options, + { Log.i("MyAmplifyApp", "Successfully downloaded: ${it.file.name}") }, + { Log.e("MyAmplifyApp", "Download Failure", it) } +) +``` + + + + +```kotlin +val bucketInfo = BucketInfo("second-bucket-name-from-console", "us-east-2") +val secondBucket = StorageBucket.fromBucketInfo(bucketInfo) +val options = StorageDownloadFileOptions.builder().bucket(secondBucket).build() +val file = File("${applicationContext.filesDir}/download.txt") +val download = Amplify.Storage.downloadFile(StoragePath.fromString("public/example"), file, options) +try { + val fileName = download.result().file.name + Log.i("MyAmplifyApp", "Successfully downloaded: $fileName") +} catch (error: StorageException) { + Log.e("MyAmplifyApp", "Download Failure", error) +} +``` + + + + +```java +BucketInfo bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2"); +StorageBucket secondBucket = StorageBucket.fromBucketInfo(bucketInfo); +StorageDownloadFileOptions options = StorageDownloadFileOptions.builder().bucket(secondBucket).build(); +RxProgressAwareSingleOperation download = + RxAmplify.Storage.downloadFile( + StoragePath.fromString("public/example"), + new File(getApplicationContext().getFilesDir() + "/download.txt"), + options, + ); + +download + .observeResult() + .subscribe( + result -> Log.i("MyAmplifyApp", "Successfully downloaded: " + result.getFile().getName()), + error -> Log.e("MyAmplifyApp", "Download Failure", error) + ); +``` + + + + ### Monitor download progress 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 5a45125e633..fc800635832 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 @@ -334,6 +334,196 @@ Note the trailing slash `/` in the given path. If you had used `public/photos` as path, it would also match against files like `public/photos01.jpg`. +### 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 string representing the target bucket's assigned name in Amplify Backend. + + + + +```java +StorageBucket secondBucket = StorageBucket.fromOutputs("secondBucket"); +StoragePagedListOptions options = StoragePagedListOptions.builder() + .setPageSize(1000) + .bucket(secondBucket) + .build(); + +Amplify.Storage.list( + StoragePath.fromString("public/photos/"), + options, + result -> { + for (StorageItem item : result.getItems()) { + Log.i("MyAmplifyApp", "Item: " + item.getPath()); + } + Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken()); + }, + error -> Log.e("MyAmplifyApp", "List failure", error); +); +``` + + + + +```kotlin +val secondBucket = StorageBucket.fromOutputs("secondBucket") +val options = StoragePagedListOptions.builder() + .setPageSize(1000) + .bucket(secondBucket) + .build() + +Amplify.Storage.list(StoragePath.fromString("public/photos/"), options, + { result -> + result.items.forEach { item -> + Log.i("MyAmplifyApp", "Item: ${item.path}") + } + Log.i("MyAmplifyApp", "Next Token: ${result.nextToken}") + }, + { Log.e("MyAmplifyApp", "List failure", it) } +) +``` + + + + +```kotlin +val secondBucket = StorageBucket.fromOutputs("secondBucket") +val options = StoragePagedListOptions.builder() + .setPageSize(1000) + .bucket(secondBucket) + .build() + +try { + val result = Amplify.Storage.list(StoragePath.fromString("public/photos/"), options) + result.items.forEach { + Log.i("MyAmplifyApp", "Item: $it") + } + Log.i("MyAmplifyApp", "next token: ${result.nextToken}") +} catch (error: StorageException) { + Log.e("MyAmplifyApp", "List failure", error) +} +``` + + + + +```java +StorageBucket secondBucket = StorageBucket.fromOutputs("secondBucket"); +StoragePagedListOptions options = StoragePagedListOptions.builder() + .setPageSize(1000) + .bucket(secondBucket) + .build(); + +RxAmplify.Storage.list(StoragePath.fromString("public/photos/"), options) + .subscribe( + result -> { + for (StorageItem item : result.getItems()) { + Log.i("MyAmplifyApp", "Item: " + item.getPath()); + } + Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken()); + }, + error -> Log.e("MyAmplifyApp", "List failure", error); + ); +``` + + + + +Alternatively, you can also pass in an object by specifying the bucket name and region from the console. + + + + +```java +BucketInfo bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2"); +StorageBucket secondBucket = StorageBucket.fromBucketInfo(bucketInfo); +StoragePagedListOptions options = StoragePagedListOptions.builder() + .setPageSize(1000) + .bucket(secondBucket) + .build(); + +Amplify.Storage.list( + StoragePath.fromString("public/photos/"), + options, + result -> { + for (StorageItem item : result.getItems()) { + Log.i("MyAmplifyApp", "Item: " + item.getPath()); + } + Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken()); + }, + error -> Log.e("MyAmplifyApp", "List failure", error); +); +``` + + + + +```kotlin +val bucketInfo = BucketInfo("second-bucket-name-from-console", "us-east-2") +val secondBucket = StorageBucket.fromBucketInfo(bucketInfo) +val options = StoragePagedListOptions.builder() + .setPageSize(1000) + .bucket(secondBucket) + .build() + +Amplify.Storage.list(StoragePath.fromString("public/photos/"), options, + { result -> + result.items.forEach { item -> + Log.i("MyAmplifyApp", "Item: ${item.path}") + } + Log.i("MyAmplifyApp", "Next Token: ${result.nextToken}") + }, + { Log.e("MyAmplifyApp", "List failure", it) } +) +``` + + + + +```kotlin +val bucketInfo = BucketInfo("second-bucket-name-from-console", "us-east-2") +val secondBucket = StorageBucket.fromBucketInfo(bucketInfo) +val options = StoragePagedListOptions.builder() + .setPageSize(1000) + .bucket(secondBucket) + .build() + +try { + val result = Amplify.Storage.list(StoragePath.fromString("public/photos/"), options) + result.items.forEach { + Log.i("MyAmplifyApp", "Item: $it") + } + Log.i("MyAmplifyApp", "next token: ${result.nextToken}") +} catch (error: StorageException) { + Log.e("MyAmplifyApp", "List failure", error) +} +``` + + + + +```java +BucketInfo bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2"); +StorageBucket secondBucket = StorageBucket.fromBucketInfo(bucketInfo); +StoragePagedListOptions options = StoragePagedListOptions.builder() + .setPageSize(1000) + .bucket(secondBucket) + .build(); + +RxAmplify.Storage.list(StoragePath.fromString("public/photos/"), options) + .subscribe( + result -> { + for (StorageItem item : result.getItems()) { + Log.i("MyAmplifyApp", "Item: " + item.getPath()); + } + Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken()); + }, + error -> Log.e("MyAmplifyApp", "List failure", error); + ); +``` + + + + ### Exclude results from nested subpaths By default, the `list` API will return all objects contained within the given path, including objects inside nested subpaths. @@ -538,11 +728,13 @@ Path: public/photos/2024/photos02.jpg Subpath: public/photos/202- ``` -### More `list` options +### All `list` options | Option | Type | Description | | --- | --- | --- | -| pageSize | int | Number between 1 and 1,000 that indicates the limit of how many entries to fetch when retrieving file lists from the server | +| subpathStrategy | SubpathStrategy | The strategy to use when listing contents from subpaths. | +| pageSize | int | Number between 1 and 1,000 that indicates the limit of how many entries to fetch when retrieving file lists from the server. | +| bucket | StorageBucket | The bucket in which the objects are stored. | | nextToken | String | String indicating the page offset at which to resume a listing. | @@ -598,6 +790,43 @@ Note the trailing slash `/` in the given path. If you had used `public/photos` as path, it would also match against files like `public/photos01.jpg`. +### List files from a specified bucket + +You can perform a list operation from a specific bucket by providing the `bucket` option. + + + +You can use `.fromOutputs(name:)` to provide a string representing the target bucket's assigned name in the Amplify Backend. + +```swift +let listResult = try await Amplify.Storage.list( + path: .fromString("public/example/path/myFile.txt"), + local: fileUrl, + options: .init( + bucket: .fromOutputs(name: "secondBucket") + ) +) +``` + + + +You can also use `.fromBucketInfo(_:)` to provide a bucket name and region directly. + +```swift +let listResult = try await Amplify.Storage.list( + path: .fromString("public/example/path/myFile.txt"), + local: fileUrl, + options: .init( + bucket: .fromBucketInfo(.init( + bucketName: "another-bucket-name", + region: "another-bucket-region") + ) + ) +) +``` + + + ### Exclude results from nested subpaths By default, the `list` API will return all objects contained within the given path, including objects inside nested subpaths. @@ -711,11 +940,13 @@ receiveValue: { listResult in -### More `list` options +### All `list` options | Option | Type | Description | | --- | --- | --- | +| subpathStrategy | SubpathStrategy | The strategy to use when listing contents from subpaths | | pageSize | UInt | Number between 1 and 1,000 that indicates the limit of how many entries to fetch when retrieving file lists from the server | +| bucket | StorageBucket | The bucket in which the objects are stored | | nextToken | String | String indicating the page offset at which to resume a listing. | 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 26d8395f052..27e081ec6eb 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 @@ -29,12 +29,12 @@ export function getStaticProps(context) { }; } -Files can be removed from a storage bucket using the 'remove' API. If a file is protected by an identity Id, only the user who owns the file will be able to remove it. - -You can also perform an upload operation to a specific bucket by providing the target bucket's assigned name from Amplify Backend in `bucket` option. +Files can be removed from a storage bucket using the `remove` API. If a file is protected by an identity Id, only the user who owns the file will be able to remove it. +You can also perform a remove operation from a specific bucket by providing the target bucket's assigned name from Amplify Backend in `bucket` option. + ```javascript import { remove } from 'aws-amplify/storage'; @@ -48,12 +48,9 @@ try { console.log('Error ', error); } ``` - Alternatively, you can also pass in an object by specifying the bucket name and region from the console. - - ```javascript import { remove } from 'aws-amplify/storage'; @@ -121,6 +118,152 @@ RxAmplify.Storage.remove(StoragePath.fromString("public/myUploadedFileName.txt") + +## Remove files from a specified bucket + +You can also perform a remove operation to a specific bucket by providing the `bucket` option. You can pass in a string representing the target bucket's assigned name in Amplify Backend. + + + + +```java +StorageBucket secondBucket = StorageBucket.fromOutputs("secondBucket"); +StorageRemoveOptions options = StorageRemoveOptions.builder() + .bucket(secondBucket) + .build(); + +Amplify.Storage.remove( + StoragePath.fromString("public/myUploadedFileName.txt"), + options, + result -> Log.i("MyAmplifyApp", "Successfully removed: " + result.getPath()), + error -> Log.e("MyAmplifyApp", "Remove failure", error) +); +``` + + + + +```kotlin +val secondBucket = StorageBucket.fromOutputs("secondBucket") +val options = StorageRemoveOptions.builder() + .bucket(secondBucket) + .build() + +Amplify.Storage.remove(StoragePath.fromString("public/myUploadedFileName.txt"), options, + { Log.i("MyAmplifyApp", "Successfully removed: ${it.path}") }, + { Log.e("MyAmplifyApp", "Remove failure", it) } +) +``` + + + + +```kotlin +val secondBucket = StorageBucket.fromOutputs("secondBucket") +val options = StorageRemoveOptions.builder() + .bucket(secondBucket) + .build() + +try { + val result = Amplify.Storage.remove(StoragePath.fromString("public/myUploadedFileName.txt"), options) + Log.i("MyAmplifyApp", "Successfully removed: ${result.path}") +} catch (error: StorageException) { + Log.e("MyAmplifyApp", "Remove failure", error) +} +``` + + + + +```java +StorageBucket secondBucket = StorageBucket.fromOutputs("secondBucket"); +StorageRemoveOptions options = StorageRemoveOptions.builder() + .bucket(secondBucket) + .build(); +RxAmplify.Storage.remove(StoragePath.fromString("public/myUploadedFileName.txt"), options) + .subscribe( + result -> Log.i("MyAmplifyApp", "Successfully removed: " + result.getPath()), + error -> Log.e("MyAmplifyApp", "Remove failure", error) + ); +``` + + + + +Alternatively, you can also pass in an object by specifying the bucket name and region from the console. + + + + +```java +BucketInfo bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2"); +StorageBucket secondBucket = StorageBucket.fromBucketInfo(bucketInfo); +StorageRemoveOptions options = StorageRemoveOptions.builder() + .bucket(secondBucket) + .build(); + +Amplify.Storage.remove( + StoragePath.fromString("public/myUploadedFileName.txt"), + options, + result -> Log.i("MyAmplifyApp", "Successfully removed: " + result.getPath()), + error -> Log.e("MyAmplifyApp", "Remove failure", error) +); +``` + + + + +```kotlin +val bucketInfo = BucketInfo("second-bucket-name-from-console", "us-east-2") +val secondBucket = StorageBucket.fromBucketInfo(bucketInfo) +val options = StorageRemoveOptions.builder() + .bucket(secondBucket) + .build() + +Amplify.Storage.remove(StoragePath.fromString("public/myUploadedFileName.txt"), options, + { Log.i("MyAmplifyApp", "Successfully removed: ${it.path}") }, + { Log.e("MyAmplifyApp", "Remove failure", it) } +) +``` + + + + +```kotlin +val bucketInfo = BucketInfo("second-bucket-name-from-console", "us-east-2") +val secondBucket = StorageBucket.fromBucketInfo(bucketInfo) +val options = StorageRemoveOptions.builder() + .bucket(secondBucket) + .build() + +try { + val result = Amplify.Storage.remove(StoragePath.fromString("public/myUploadedFileName.txt"), options) + Log.i("MyAmplifyApp", "Successfully removed: ${result.path}") +} catch (error: StorageException) { + Log.e("MyAmplifyApp", "Remove failure", error) +} +``` + + + + +```java +BucketInfo bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2"); +StorageBucket secondBucket = StorageBucket.fromBucketInfo(bucketInfo); +StorageRemoveOptions options = StorageRemoveOptions.builder() + .bucket(secondBucket) + .build(); + +RxAmplify.Storage.remove(StoragePath.fromString("public/myUploadedFileName.txt"), options) + .subscribe( + result -> Log.i("MyAmplifyApp", "Successfully removed: " + result.getPath()), + error -> Log.e("MyAmplifyApp", "Remove failure", error) + ); +``` + + + + @@ -130,7 +273,9 @@ RxAmplify.Storage.remove(StoragePath.fromString("public/myUploadedFileName.txt") ```swift -let removedObject = try await Amplify.Storage.remove(path: .fromString("public/example/path")) +let removedObject = try await Amplify.Storage.remove( + path: .fromString("public/example/path") +) print("Deleted \(removedObject)") ``` @@ -140,7 +285,9 @@ print("Deleted \(removedObject)") ```swift let sink = Amplify.Publisher.create { - try await Amplify.Storage.remove(path: .fromString("public/example/path")) + try await Amplify.Storage.remove( + path: .fromString("public/example/path") + ) }.sink { if case let .failure(error) = $0 { print("Failed: \(error)") @@ -155,6 +302,41 @@ receiveValue: { removedObject in +## Remove files from a specified bucket + +You can perform a remove operation from a specific bucket by providing the `bucket` option. + + + +You can use `.fromOutputs(name:)` to provide a string representing the target bucket's assigned name in the Amplify Backend. + +```swift +let removedObject = try await Amplify.Storage.remove( + path: .fromString("public/example/path"), + options: .init( + bucket: .fromOutputs(name: "secondBucket") + ) +) +``` + + + +You can also use `.fromBucketInfo(_:)` to provide a bucket name and region directly. + +```swift +let removedObject = try await Amplify.Storage.remove( + path: .fromString("public/example/path"), + options: .init( + bucket: .fromBucketInfo(.init( + bucketName: "another-bucket-name", + region: "another-bucket-region") + ) + ) +) +``` + + + 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 ba0b7719563..9f1d42046b8 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 @@ -186,6 +186,183 @@ try { ``` + +### 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. + + + + +```java +StorageBucket secondBucket = StorageBucket.fromOutputs("secondBucket"); +StorageDownloadFileOptions options = StorageDownloadFileOptions.builder().bucket(secondBucket).build(); +Amplify.Storage.downloadFile( + StoragePath.fromString("public/example"), + new File(getApplicationContext().getFilesDir() + "/download.txt"), + options, + result -> Log.i("MyAmplifyApp", "Successfully downloaded: " + result.getFile().getName()), + error -> Log.e("MyAmplifyApp", "Download Failure", error) +); +``` + + + + +```kotlin +val secondBucket = StorageBucket.fromOutputs("secondBucket") +val options = StorageDownloadFileOptions.builder().bucket(secondBucket).build() +val file = File("${applicationContext.filesDir}/download.txt") +Amplify.Storage.downloadFile(StoragePath.fromString("public/example"), file, option, + { Log.i("MyAmplifyApp", "Successfully downloaded: ${it.file.name}") }, + { Log.e("MyAmplifyApp", "Download Failure", it) } +) +``` + + + + +```kotlin +val secondBucket = StorageBucket.fromOutputs("secondBucket") +val options = StorageDownloadFileOptions.builder().bucket(secondBucket).build() +val file = File("${applicationContext.filesDir}/download.txt") +val download = Amplify.Storage.downloadFile(StoragePath.fromString("public/example"), file, options) +try { + val fileName = download.result().file.name + Log.i("MyAmplifyApp", "Successfully downloaded: $fileName") +} catch (error: StorageException) { + Log.e("MyAmplifyApp", "Download Failure", error) +} +``` + + + + +```java +StorageBucket secondBucket = StorageBucket.fromOutputs("secondBucket"); +StorageDownloadFileOptions options = StorageDownloadFileOptions.builder().bucket(secondBucket).build(); +RxProgressAwareSingleOperation download = + RxAmplify.Storage.downloadFile( + StoragePath.fromString("public/example"), + new File(getApplicationContext().getFilesDir() + "/download.txt"), + options + ); + +download + .observeResult() + .subscribe( + result -> Log.i("MyAmplifyApp", "Successfully downloaded: " + result.getFile().getName()), + error -> Log.e("MyAmplifyApp", "Download Failure", error) + ); +``` + + + + +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. + + + + +```java +BucketInfo bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2"); +StorageBucket secondBucket = StorageBucket.fromBucketInfo(bucketInfo); +StorageDownloadFileOptions options = StorageDownloadFileOptions.builder().bucket(secondBucket).build(); +Amplify.Storage.downloadFile( + StoragePath.fromString("public/example"), + new File(getApplicationContext().getFilesDir() + "/download.txt"), + options, + result -> Log.i("MyAmplifyApp", "Successfully downloaded: " + result.getFile().getName()), + error -> Log.e("MyAmplifyApp", "Download Failure", error) +); +``` + + + + +```kotlin +val bucketInfo = BucketInfo("second-bucket-name-from-console", "us-east-2") +val secondBucket = StorageBucket.fromBucketInfo(bucketInfo) +val options = StorageDownloadFileOptions.builder().bucket(secondBucket).build() +val file = File("${applicationContext.filesDir}/download.txt") +Amplify.Storage.downloadFile(StoragePath.fromString("public/example"), file, options, + { Log.i("MyAmplifyApp", "Successfully downloaded: ${it.file.name}") }, + { Log.e("MyAmplifyApp", "Download Failure", it) } +) +``` + + + + +```kotlin +val bucketInfo = BucketInfo("second-bucket-name-from-console", "us-east-2") +val secondBucket = StorageBucket.fromBucketInfo(bucketInfo) +val options = StorageDownloadFileOptions.builder().bucket(secondBucket).build() +val file = File("${applicationContext.filesDir}/download.txt") +val download = Amplify.Storage.downloadFile(StoragePath.fromString("public/example"), file, options) +try { + val fileName = download.result().file.name + Log.i("MyAmplifyApp", "Successfully downloaded: $fileName") +} catch (error: StorageException) { + Log.e("MyAmplifyApp", "Download Failure", error) +} +``` + + + + +```java +BucketInfo bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2"); +StorageBucket secondBucket = StorageBucket.fromBucketInfo(bucketInfo); +StorageDownloadFileOptions options = StorageDownloadFileOptions.builder().bucket(secondBucket).build(); +RxProgressAwareSingleOperation download = + RxAmplify.Storage.downloadFile( + StoragePath.fromString("public/example"), + new File(getApplicationContext().getFilesDir() + "/download.txt"), + options, + ); + +download + .observeResult() + .subscribe( + result -> Log.i("MyAmplifyApp", "Successfully downloaded: " + result.getFile().getName()), + error -> Log.e("MyAmplifyApp", "Download Failure", error) + ); +``` + + + + + + +### 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. + +```swift +let downloadTask = Amplify.Storage.downloadData( + path: .fromString("public/example/path"), + options: .init( + bucket: .fromOutputs(name: "secondBucket") + ) +) +``` + +Alternatively, you can also directly specify the bucket name and region from the console. See each Amplify Storage API page for additional usage examples. + +```swift +let downloadTask = Amplify.Storage.downloadData( + path: .fromString("public/example/path"), + options: .init( + bucket: .fromBucketInfo(.init( + bucketName: "another-bucket-name", + region: "another-bucket-region") + ) + ) +) +``` + + ## 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 7911d0da6f0..6a4aa8bc747 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 @@ -357,7 +357,7 @@ try dataString.write( let uploadTask = Amplify.Storage.uploadFile( path: .fromString("public/example/path/myFile.txt"), - local: filename + local: fileUrl ) ``` @@ -370,7 +370,7 @@ To upload a file from a data object, specify the `path` and the `data` object to let dataString = "My Data" let data = Data(dataString.utf8) let uploadTask = Amplify.Storage.uploadData( - path: .fromString("public/example/path"), + path: .fromString("public/example/path/myFile.txt"), data: data ) ``` @@ -729,6 +729,284 @@ const result = await uploadData({ ``` + + +### 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 string representing the target bucket's assigned name in Amplify Backend. + + + + +```java +private void uploadFile() { + File exampleFile = new File(getApplicationContext().getFilesDir(), "example"); + + try { + BufferedWriter writer = new BufferedWriter(new FileWriter(exampleFile)); + writer.append("Example file contents"); + writer.close(); + } catch (Exception exception) { + Log.e("MyAmplifyApp", "Upload failed", exception); + } + + StorageBucket secondBucket = StorageBucket.fromOutputs("secondBucket"); + StorageUploadFileOptions options = StorageUploadFileOptions.builder().bucket(secondBucket).build(); + + Amplify.Storage.uploadFile( + StoragePath.fromString("public/example"), + exampleFile, + options, + result -> Log.i("MyAmplifyApp", "Successfully uploaded: " + result.getPath()), + storageFailure -> Log.e("MyAmplifyApp", "Upload failed", storageFailure) + ); +} +``` + + + + +```kotlin +private fun uploadFile() { + val exampleFile = File(applicationContext.filesDir, "example") + exampleFile.writeText("Example file contents") + + val secondBucket = StorageBucket.fromOutputs("secondBucket") + val options = StorageUploadFileOptions.builder().bucket(secondBucket).build() + + Amplify.Storage.uploadFile(StoragePath.fromString("public/example"), exampleFile, options, + { Log.i("MyAmplifyApp", "Successfully uploaded: ${it.path}") }, + { Log.e("MyAmplifyApp", "Upload failed", it) } + ) +} +``` + + + + +```kotlin +private suspend fun uploadFile() { + val exampleFile = File(applicationContext.filesDir, "example") + exampleFile.writeText("Example file contents") + + val secondBucket = StorageBucket.fromOutputs("secondBucket") + val options = StorageUploadFileOptions.builder().bucket(secondBucket).build() + + val upload = Amplify.Storage.uploadFile(StoragePath.fromString("public/example"), exampleFile, options) + try { + val result = upload.result() + Log.i("MyAmplifyApp", "Successfully uploaded: ${result.path}") + } catch (error: StorageException) { + Log.e("MyAmplifyApp", "Upload failed", error) + } +} +``` + + + + +```java +private void uploadFile() { + File exampleFile = new File(getApplicationContext().getFilesDir(), "example"); + + try { + BufferedWriter writer = new BufferedWriter(new FileWriter(exampleFile)); + writer.append("Example file contents"); + writer.close(); + } catch (Exception exception) { + Log.e("MyAmplifyApp", "Upload failed", exception); + } + + StorageBucket secondBucket = StorageBucket.fromOutputs("secondBucket"); + StorageUploadFileOptions options = StorageUploadFileOptions.builder().bucket(secondBucket).build(); + + RxProgressAwareSingleOperation rxUploadOperation = + RxAmplify.Storage.uploadFile(StoragePath.fromString("public/example"), exampleFile, options); + + rxUploadOperation + .observeResult() + .subscribe( + result -> Log.i("MyAmplifyApp", "Successfully uploaded: " + result.getPath()), + error -> Log.e("MyAmplifyApp", "Upload failed", error) + ); +} +``` + + + + + +Alternatively, you can also pass in an object by specifying the bucket name and region from the console. + + + + +```java +private void uploadFile() { + File exampleFile = new File(getApplicationContext().getFilesDir(), "example"); + + try { + BufferedWriter writer = new BufferedWriter(new FileWriter(exampleFile)); + writer.append("Example file contents"); + writer.close(); + } catch (Exception exception) { + Log.e("MyAmplifyApp", "Upload failed", exception); + } + + BucketInfo bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2"); + StorageBucket secondBucket = StorageBucket.fromBucketInfo(bucketInfo); + StorageUploadFileOptions options = StorageUploadFileOptions.builder().bucket(secondBucket).build(); + + Amplify.Storage.uploadFile( + StoragePath.fromString("public/example"), + exampleFile, + options, + result -> Log.i("MyAmplifyApp", "Successfully uploaded: " + result.getPath()), + storageFailure -> Log.e("MyAmplifyApp", "Upload failed", storageFailure) + ); +} +``` + + + + +```kotlin +private fun uploadFile() { + val exampleFile = File(applicationContext.filesDir, "example") + exampleFile.writeText("Example file contents") + + val bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2"); + val secondBucket = StorageBucket.fromBucketInfo(bucketInfo); + val options = StorageUploadFileOptions.builder().bucket(secondBucket).build(); + + Amplify.Storage.uploadFile(StoragePath.fromString("public/example"), exampleFile, options, + { Log.i("MyAmplifyApp", "Successfully uploaded: ${it.path}") }, + { Log.e("MyAmplifyApp", "Upload failed", it) } + ) +} +``` + + + + +```kotlin +private suspend fun uploadFile() { + val exampleFile = File(applicationContext.filesDir, "example") + exampleFile.writeText("Example file contents") + + val bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2"); + val secondBucket = StorageBucket.fromBucketInfo(bucketInfo); + val options = StorageUploadFileOptions.builder().bucket(secondBucket).build(); + + val upload = Amplify.Storage.uploadFile(StoragePath.fromString("public/example"), exampleFile, options) + try { + val result = upload.result() + Log.i("MyAmplifyApp", "Successfully uploaded: ${result.path}") + } catch (error: StorageException) { + Log.e("MyAmplifyApp", "Upload failed", error) + } +} +``` + + + + +```java +private void uploadFile() { + File exampleFile = new File(getApplicationContext().getFilesDir(), "example"); + + try { + BufferedWriter writer = new BufferedWriter(new FileWriter(exampleFile)); + writer.append("Example file contents"); + writer.close(); + } catch (Exception exception) { + Log.e("MyAmplifyApp", "Upload failed", exception); + } + + BucketInfo bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2"); + StorageBucket secondBucket = StorageBucket.fromBucketInfo(bucketInfo); + StorageUploadFileOptions options = StorageUploadFileOptions.builder().bucket(secondBucket).build(); + + RxProgressAwareSingleOperation rxUploadOperation = + RxAmplify.Storage.uploadFile(StoragePath.fromString("public/example"), exampleFile, options); + + rxUploadOperation + .observeResult() + .subscribe( + result -> Log.i("MyAmplifyApp", "Successfully uploaded: " + result.getPath()), + error -> Log.e("MyAmplifyApp", "Upload failed", error) + ); +} +``` + + + + + + + +### Upload to a specified bucket + +You can perform an upload operation to a specific bucket by providing the `bucket` option. + + + +You can use `.fromOutputs(name:)` to provide a string representing the target bucket's assigned name in the Amplify Backend. + +```swift +// Upload from File +let uploadTask = Amplify.Storage.uploadFile( + path: .fromString("public/example/path/myFile.txt"), + local: fileUrl, + options: .init( + bucket: .fromOutputs(name: "secondBucket") + ) +) + +// Upload from Data +let uploadTask = Amplify.Storage.uploadData( + path: .fromString("public/example/path/myFile.txt"), + data: data, + options: .init( + bucket: .fromOutputs(name: "secondBucket") + ) +) +``` + + + +You can also use `.fromBucketInfo(_:)` to provide a bucket name and region directly. + +```swift +// Upload from File +let uploadTask = Amplify.Storage.uploadFile( + path: .fromString("public/example/path/myFile.txt"), + local: fileUrl, + options: .init( + bucket: .fromBucketInfo(.init( + bucketName: "another-bucket-name", + region: "another-bucket-region") + ) + ) +) + +// Upload from Data +let uploadTask = Amplify.Storage.uploadData( + path: .fromString("public/example/path/myFile.txt"), + data: data, + options: .init( + bucket: .fromBucketInfo(.init( + bucketName: "another-bucket-name", + region: "another-bucket-region") + ) + ) +) +``` + + + + + ### Monitor upload progress @@ -902,6 +1180,20 @@ upload +### All `upload` options + +Option | Type | Description | +| -- | -- | ----------- | +| metadata | Map\ | Metadata for the object to store. | +| contentType | String | The standard MIME type describing the format of the object to store. | +| bucket | StorageBucket | The bucket in which the object should be stored. | +| serverSideEncryption | ServerSideEncryption | The server side encryption algorithm. | +| useAccelerateEndpoint | boolean | Flag to determine whether to use acceleration endpoint. | + + + + + ### Query transfers When an upload or download operation is requested using the Amplify Android library, the request is first persisted in the local SQLite Database and then queued for execution. You can query the transfer operation queued in the local database using the transfer ID returned by an upload or download API. Get-Transfer API could retrieve a pending transfer previously en-queued and enable attaching a listener to receive updates on progress change, on-error or on-success, or pause, cancel or resume it. @@ -1184,12 +1476,13 @@ Upload tasks are run using `URLSessionTask` instances internally. You can learn -## More upload options +### All `upload` options Option | Type | Description | | -- | -- | ----------- | -| metadata | Dictionary | Metadata for the object to store. | +| metadata | [String: String] | Metadata for the object to store. | | contentType | String | The standard MIME type describing the format of the object to store. | +| bucket | StorageBucket | The bucket in which the object should be stored |