From 08757bedead4639fcb13b83b553c9b238843cd1d Mon Sep 17 00:00:00 2001 From: Allan Zheng Date: Tue, 26 Nov 2024 15:57:31 -0800 Subject: [PATCH 1/3] docs(js): add durability options --- .../[platform]/build-a-backend/storage/copy-files/index.mdx | 3 +++ .../build-a-backend/storage/download-files/index.mdx | 4 ++++ .../[platform]/build-a-backend/storage/list-files/index.mdx | 1 + .../[platform]/build-a-backend/storage/remove-files/index.mdx | 1 + .../[platform]/build-a-backend/storage/upload-files/index.mdx | 1 + 5 files changed, 10 insertions(+) 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..eff93b1cd49 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 @@ -114,6 +114,9 @@ Option | Type | Default | Description | | -- | :--: | :--: | ----------- | | path | string \|
(\{ identityId \}) => string | Required | A string or callback that represents the path in source and destination bucket to copy the object to or from.
**Each segment of the path in `source` must by URI encoded.** | | bucket | string \|
\{ bucketName: string;
region: string; \} | Default bucket and region from Amplify configuration | A string representing the target bucket's assigned name in Amplify Backend or an object specifying the bucket name and region from the console.

Read more at [Configure additional storage buckets](/[platform]/build-a-backend/storage/set-up-storage/#configure-additional-storage-buckets). | +| eTag | string | Optional | The copy **source object** entity tag (ETag) value. Only Copies the object if its ETag matches the specified tag. | +| notModifiedSince | Date | Optional | Copies the **source object** if it hasn't been modified since the specified time.

**This is evaluated only when `eTag` is NOT supplied**| +| expectedBucketOwner | string | Optional | The account ID that owns source or destination bucket. | 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..2b7b190d8ee 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 @@ -106,6 +106,8 @@ const linkToStorageFile = await getUrl({ expiresIn: 300, // whether to use accelerate endpoint useAccelerateEndpoint: true, + // The account ID that owns the requested bucket. + expectedBucketOwner: '123456789012', } }); ``` @@ -116,6 +118,7 @@ Option | Type | Default | Description | | validateObjectExistence | boolean | false | Whether to head object to make sure the object existence before downloading. | | expiresIn | number | 900 | Number of seconds till the URL expires.

The expiration time of the presigned url is dependent on the session and will max out at 1 hour. | | useAccelerateEndpoint | boolean | false | Whether to use accelerate endpoint.

Read more at [Transfer Acceleration](/[platform]/build-a-backend/storage/extend-s3-resources/#example---enable-transfer-acceleration) | +| expectedBucketOwner | string | Optional | The account ID that owns requested bucket. | @@ -1188,6 +1191,7 @@ Option | Type | Default | Description | | onProgress | callback | — | Callback function tracking the upload/download progress. | | bytesRange | \{ start: number; end:number; \} | — | Bytes range parameter to download a part of the file. | | useAccelerateEndpoint | boolean | false | Whether to use accelerate endpoint.

Read more at [Transfer Acceleration](/[platform]/build-a-backend/storage/extend-s3-resources/#example---enable-transfer-acceleration) | +| expectedBucketOwner | string | Optional | The account ID that owns requested bucket. | ## Frequently Asked Questions 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..13c3370a014 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 @@ -240,6 +240,7 @@ const result = await list({ | nextToken | string | — | Indicates whether the list is being continued on this bucket with a token | | subpathStrategy | \{ strategy: 'include' \} \|
\{ 'exclude',
delimiter?: string \} | \{ strategy: 'include' \} | An object representing the subpath inclusion strategy and the delimiter used to group results for exclusion.

Read more at [Excluding subpaths](/[platform]/build-a-backend/storage/list-files/#excluding-subpaths) | | useAccelerateEndpoint | boolean | false | Whether to use accelerate endpoint.

Read more at [Transfer Acceleration](/[platform]/build-a-backend/storage/extend-s3-resources/#example---enable-transfer-acceleration) | +| expectedBucketOwner | string | Optional | The account ID that owns requested bucket. | 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..0ee372de282 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 @@ -389,4 +389,5 @@ Future remove() async { Option | Type | Default | Description | | -- | :--: | :--: | ----------- | | bucket | string \|
\{ bucketName: string;
region: string; \} | Default bucket and region from Amplify configuration | A string representing the target bucket's assigned name in Amplify Backend or an object specifying the bucket name and region from the console.

Read more at [Configure additional storage buckets](/[platform]/build-a-backend/storage/set-up-storage/#configure-additional-storage-buckets) | +| expectedBucketOwner | string | Optional | The account ID that owns requested bucket. | 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..acc1287434d 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 @@ -653,6 +653,7 @@ Option | Type | Description | | -- | -- | ----------- | | 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) | +| expectedBucketOwner | string | Optional | The account ID that owns requested bucket. | Example of `uploadFile` with options: From 5b4b2c1f5d4a2f80495bc663e0a4056e75ce8c3d Mon Sep 17 00:00:00 2001 From: Allan Zheng Date: Wed, 27 Nov 2024 13:51:29 -0800 Subject: [PATCH 2/3] fix: upload docs --- .../build-a-backend/storage/upload-files/index.mdx | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) 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 acc1287434d..a4f264a9491 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 @@ -653,7 +653,6 @@ Option | Type | Description | | -- | -- | ----------- | | 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) | -| expectedBucketOwner | string | Optional | The account ID that owns requested bucket. | Example of `uploadFile` with options: @@ -1567,7 +1566,11 @@ const result = await uploadData({ // configure how object is presented contentDisposition: "attachment", // whether to use accelerate endpoint - useAccelerateEndpoint: true + useAccelerateEndpoint: true, + // the account ID that owns requested bucket + expectedBucketOwner: '123456789012', + // whether to check if an object with the same key already exists before completing the upload + preventOverwrite: true, }, }); ``` @@ -1579,6 +1582,8 @@ Option | Type | Default | Description | | contentDisposition | string | — | Specifies presentational information for the object.

Read more at [Content-Disposition documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) | | metadata | map\ | — | A map of metadata to store with the object in S3.

Read more at [S3 metadata documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html#UserMetadata) | | useAccelerateEndpoint | boolean | false | Whether to use accelerate endpoint.

Read more at [Transfer Acceleration](/[platform]/build-a-backend/storage/upload-files/#transfer-acceleration) | +| expectedBucketOwner | string | - | The account ID that owns requested bucket. | +| preventOverwrite | boolean | false | Whether to check if an object with the same key already exists before completing the upload. If exists, a `Precondition Failed` error will be thrown | From 7b1602a225a0c50198d04effa09f32b1bdf38077 Mon Sep 17 00:00:00 2001 From: Allan Zheng Date: Mon, 2 Dec 2024 13:00:46 -0800 Subject: [PATCH 3/3] chore: add copy example for expected bucket owner --- .../build-a-backend/storage/copy-files/index.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) 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 eff93b1cd49..c08e79a6601 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 @@ -86,7 +86,8 @@ const copyFile = async () => { path: 'album/2024/1.jpg', // Specify a target bucket using name assigned in Amplify Backend // or bucket name from console and associated region - bucket: 'assignedNameInAmplifyBackend' + bucket: 'assignedNameInAmplifyBackend', + expectedBucketOwner: '123456789012' }, destination: { path: 'shared/2024/1.jpg', @@ -95,7 +96,8 @@ const copyFile = async () => { bucket: { bucketName: 'generated-second-bucket-name', region: 'us-east-2' - } + }, + expectedBucketOwner: '123456789013' } }); } catch (error) { @@ -116,7 +118,7 @@ Option | Type | Default | Description | | bucket | string \|
\{ bucketName: string;
region: string; \} | Default bucket and region from Amplify configuration | A string representing the target bucket's assigned name in Amplify Backend or an object specifying the bucket name and region from the console.

Read more at [Configure additional storage buckets](/[platform]/build-a-backend/storage/set-up-storage/#configure-additional-storage-buckets). | | eTag | string | Optional | The copy **source object** entity tag (ETag) value. Only Copies the object if its ETag matches the specified tag. | | notModifiedSince | Date | Optional | Copies the **source object** if it hasn't been modified since the specified time.

**This is evaluated only when `eTag` is NOT supplied**| -| expectedBucketOwner | string | Optional | The account ID that owns source or destination bucket. | +| expectedBucketOwner | string | Optional | `source.expectedBucketOwner`: The account ID that owns the source bucket.

`destination.expectedBucketOwner`: The account ID that owns the destination bucket. |