Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

amplify-libraries Flutter multibucket support documentation update #8115

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

amplify-libraries Flutter multibucket support documentation update #8115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
93f1b14
updated storage section for multibucket support
ekjotmultani Nov 20, 2024
6ac635e
Merge branch 'aws-amplify:main' into main
ekjotmultani Nov 20, 2024
01516d4
updated api explanations for consistency
ekjotmultani Nov 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 40 additions & 1 deletion src/pages/[platform]/build-a-backend/storage/copy-files/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,12 +134,48 @@ Future<void> 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');
}
```

<Callout>
In order to copy to or from a bucket other than your default, the source and/or destination paths must exist in that bucket
</Callout>

## `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:

Expand All @@ -151,6 +187,9 @@ final result = Amplify.Storage.copy(
pluginOptions: S3CopyPluginOptions(
getProperties: true,
),
buckets: CopyBuckets.sameBucket(
StorageBucket.fromOutputs('secondBucket'),
),
),
);
```
Expand Down
50 changes: 47 additions & 3 deletions src/pages/[platform]/build-a-backend/storage/download-files/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<void> 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) {
Expand Down Expand Up @@ -678,7 +686,6 @@ const result = await downloadData({
}).result;

```

### Monitor download progress

```javascript
Expand Down Expand Up @@ -714,7 +721,6 @@ try {
```

</InlineFilter>

<InlineFilter filters={["android"]}>

### Download from a specified bucket
Expand Down Expand Up @@ -1101,6 +1107,7 @@ Future<void> 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<br/><br/>Defaults to the default bucket and region from the Amplify configuration if this option is not provided.<br/><br/>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. <br/><br/> Read more at [Transfer Acceleration](/[platform]/build-a-backend/storage/upload-files/#transfer-acceleration) |
| bytesRange | S3DataBytesRange | The byte range to download from the object |
Expand All @@ -1116,6 +1123,7 @@ final operation = Amplify.Storage.downloadFile(
getProperties: true,
useAccelerateEndpoint: true,
),
bucket: StorageBucket.fromOutputs('secondBucket'),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Q: This is optional right? Would a more explicit example and/or description be beneficial?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will coalesce them into their own section about multi bucket like the other apis

),
);
```
Expand All @@ -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',
),
),
),
);
```
</InlineFilter>

<InlineFilter filters={["swift"]}>
Expand Down
65 changes: 65 additions & 0 deletions src/pages/[platform]/build-a-backend/storage/list-files/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1010,11 +1010,47 @@ Future<void> listAllUnderPublicPath() async {
}

```
<InlineFilter filters={["flutter"]}>

### 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;
```
</InlineFilter>

### 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<br/><br/>Defaults to the default bucket and region from the Amplify configuration if this option is not provided.<br/><br/>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. |

Expand Down Expand Up @@ -1093,6 +1129,35 @@ Future<void> getFileProperties() async {
}
```

As well as specify a bucket to target to view properties of a file

```dart
Future<void> 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);
}
}
```

<Callout>

To get the metadata in result for all APIs when building against a web target, you have to configure user defined metadata in CORS.
Expand Down
54 changes: 40 additions & 14 deletions src/pages/[platform]/build-a-backend/storage/remove-files/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -341,28 +341,42 @@ let removedObject = try await Amplify.Storage.remove(

<InlineFilter filters={["flutter"]}>

## 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<void> 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<void> remove() async {
Expand All @@ -372,6 +386,18 @@ Future<void> 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) {
Expand Down
48 changes: 48 additions & 0 deletions src/pages/[platform]/build-a-backend/storage/set-up-storage/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -363,6 +363,54 @@ let downloadTask = Amplify.Storage.downloadData(
```
</InlineFilter>

<InlineFilter filters={["flutter"]}>
### 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.
Equartey marked this conversation as resolved.
Show resolved Hide resolved

```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');
}
```
</InlineFilter>

## Connect your app code to the storage backend

The Amplify Storage library provides client APIs that connect to the backend resources you defined.
Expand Down
Loading