JS Gen2 Storage Docs (#7323)

* [Gen2 Storage JS] DownloadData doc updates (#7049) * [JS] Update migration docs to use path (#7143) * [JS] Storage API - path update (#7145) * [Gen2 Storage JS] Update version and path strings (#7307) * fix missed $ in string --------- Co-authored-by: Jim Blanchard <jim.l.blanchard@gmail.com>
aws-amplify · Apr 29, 2024 · b6fe6dd · b6fe6dd
1 parent 4a45526
commit b6fe6dd
Show file tree

Hide file tree

Showing 11 changed files with 688 additions and 262 deletions.
diff --git a/src/directory/directory.mjs b/src/directory/directory.mjs
@@ -337,6 +337,9 @@ export const directory = {
                 {
                   path: 'src/pages/[platform]/build-a-backend/storage/set-up-storage/index.mdx'
                 },
+                {
+                  path: 'src/pages/[platform]/build-a-backend/storage/path/index.mdx'
+                },
                 {
                   path: 'src/pages/[platform]/build-a-backend/storage/storagepath/index.mdx'
                 },

diff --git a/src/pages/[platform]/build-a-backend/storage/configure-access/index.mdx b/src/pages/[platform]/build-a-backend/storage/configure-access/index.mdx
@@ -54,6 +54,12 @@ import common_configureaccess from '/src/fragments/lib/storage/native_common/con
 
 <InlineFilter filters={['javascript',  'react-native', 'angular', 'nextjs', 'react', 'vue']}>
 
+<Callout warning>
+We recommend using the new [Amplify Gen2](https://docs.amplify.aws/gen2/build-a-backend/storage/) experience when defining file access permissions as it offers a more flexible approach to customize access to files.
+
+Note: `accessLevel` parameter is deprecated and maybe removed in next major version.
+</Callout>
+
 Storage module can manage files with three different access levels; `guest`, `protected` and `private`. The Amplify CLI configures three different access levels on the storage bucket: guest, protected and private. When you run `amplify add storage`, the CLI will configure appropriate IAM policies on the bucket using a Cognito identity pool Role. You will have the option of adding CRUD (Create/Update, Read and Delete) based permissions as well, so that Authenticated and Guest users will be granted limited permissions within these levels.
 
 If you had previously enabled user sign-in by running `amplify add auth` in your project, the policies will be connected to an `Authenticated Role` of the identity pool which has scoped permission to the objects in the bucket for each user identity. If you haven't configured user sign-in, then an `Unauthenticated Role` will be assigned for each unique user/device combination, which still has scoped permissions to just their objects.
@@ -84,9 +90,9 @@ import { getUrl } from 'aws-amplify/storage';
 await getUrl({ key: 'welcome.png' }); // Get welcome.png in public space
 ```
 
-## Customization
+## Customization (Deprecated)
 
-### Customize Object Key Path
+### Customize Object Key Path (Deprecated)
 
 You can customize your key path by defining a prefix resolver:
 

diff --git a/src/pages/[platform]/build-a-backend/storage/copy/index.mdx b/src/pages/[platform]/build-a-backend/storage/copy/index.mdx
@@ -46,16 +46,40 @@ import flutter0 from '/src/fragments/lib/storage/flutter/copy.mdx';
 
 <InlineFilter filters={['javascript', 'react-native', 'angular', 'nextjs', 'react', 'vue']}>
 
-`copy` method copies an existing file to a different key and returns a `{key: 'destKey'}` object upon success.
+The `copy` API duplicates an existing file to a designated path and returns an object `{path: 'destPath'}` upon successful completion.
 
 <Callout>
 
 `copy` can copy an object up to 5 GB in a single operation.
 
 </Callout>
 
-To copy a file, you need to provide a source key in `source` and a destination key in `destination`. `accessLevel` can be 'guest', 'private', or 'protected', defaulting to 'guest'.
+To copy a file, you need to provide the existing path in `source` and the destination path in `destination`.
 
+<BlockSwitcher>
+<Block name="With Path (Above v6.2.0)">
+```javascript
+import { copy } from 'aws-amplify/storage';
+
+const copyFile = async () => {
+  try {
+    const response = await copy({
+      source: {
+        path: 'public/album/2024/1.jpg',
+        // Alternatively, path: ({identityId}) => `protected/${identityId}/album/1.jpg`
+      },
+      destination: {
+        path: 'public/shared/2024/1.jpg',
+        // Alternatively, path: ({identityId}) => `protected/${identityId}/shared/1.jpg`
+      },
+    });
+  } catch (error) {
+    console.error('Error', err);
+  }
+};
+```
+</Block>
+<Block name="With Key (Deprecated)">
 ```javascript
 import { copy } from 'aws-amplify/storage';
 
@@ -64,42 +88,86 @@ const copyFile = async () => {
     const response = await copy({
       source: {
         key: 'srcKey',
-        accessLevel: 'private' // optional 'guest', 'private', or 'protected'. Defaults to 'guest'.
+        accessLevel: 'protected' // optional 'guest', 'private', or 'protected'. Defaults to 'guest'.
         targetIdentityId: 'targetIdentityId' // optional, set it to other user's identity ID if copy from other user
       },
       destination: {
         key: 'destKey',
-        accessLevel: 'private' // optional 'guest', 'private', or 'protected'. Defaults to 'guest'.
+        accessLevel: 'protected' // optional 'guest', 'private', or 'protected'. Defaults to 'guest'.
       },
     });
   } catch (error) {
     console.error('Error', err);
   }
 };
 ```
+</Block>
+</BlockSwitcher>
 
 ## Copy files within the same access levels
 
-You can copy a file from the specified key to another key within the same [File Access Level](/[platform]/build-a-backend/storage/configure-access/) (Defaults to 'guest').
+You can copy a file from the specified path to another path within the same [File Access Level](/[platform]/build-a-backend/storage/configure-access/).
+
+<BlockSwitcher>
+<Block name="With Path (Above v6.2.0)">
+```javascript
+import { copy, list } from 'aws-amplify/storage';
+
+// Copies 'existing/srcPath' to 'copied/destPath' within 'public/'
+const copied = await copy({
+  source: { path: 'public/existing/srcPath' },
+  destination: { path: 'public/copied/destPath' }
+});
 
+// There should now be a new file 'copied/destPath' in 'public/'
+console.log((await list({ path: 'public/copied/' })).items); // [ { ..., path: 'public/copied/destPath' } ]
+console.log(copied); // { path: 'public/copied/destPath' }
+```
+</Block>
+<Block name="With Key (Deprecated)">
 ```javascript
 import { copy, list } from 'aws-amplify/storage';
 
-// Copies 'existing/srcKey' to 'copied/destKey' within the 'guest' access level
+// Copies 'existing/srcKey' to 'copied/destKey' within 'public/'
 const copied = await copy({
   source: { key: 'existing/srcKey' },
   destination: { key: 'copied/destKey' }
 });
 
-// There should now be a new file with key "copied/destKey"
+// There should now be a new file with key 'copied/destKey'
 console.log((await list({ prefix: 'copied/' })).items); // [ { ..., key: 'copied/destKey' } ]
 console.log(copied); // { key: 'copied/destKey' }
 ```
+</Block>
+</BlockSwitcher>
 
 ## Copy files across access levels
 
-To copy a file from or to an access level other than default 'guest', you'll need to explicitly provide the access level: 'private' or 'protected'.
+To copy a file to or from an access level, you'll need to explicitly provide the access level in `path` parameter.
 
+<BlockSwitcher>
+<Block name="With Path (Above v6.2.0)">
+```javascript
+import { copy, list } from 'aws-amplify/storage';
+
+// Copies 'existing/srcPath' to 'copied/destPath' from 'guest' to 'private'
+const copied = await copy({
+  source: {
+    path: 'public/existing/srcPath'
+  },
+  destination: {
+    path: ({identityId}) => `private/${identityId}/copied/destPath`
+  }
+});
+
+// There should now be a new file 'copied/destPath' in 'private/'
+console.log(
+  (await list({ path: 'private/copied/'})).items
+); // [ { ..., path: 'private/XXXXX/copied/destPath' } ]
+console.log(copied); // { path: 'private/XXXXX/copied/destPath' }
+```
+</Block>
+<Block name="With Key (Deprecated)">
 ```javascript
 import { copy, list } from 'aws-amplify/storage';
 
@@ -114,22 +182,49 @@ const copied = await copy({
   }
 });
 
-// There should now be a new file with key "copied/destKey" in the 'private' level
+// There should now be a new file with key 'copied/destKey' in the 'private' level
 console.log(
   (await list({ prefix: 'copied/', options: { accessLevel: 'private' } })).items
 ); // [ { ..., key: 'copied/destKey' } ]
 console.log(copied); // { key: 'copied/destKey' }
 ```
+</Block>
+</BlockSwitcher>
 
 ## Copy protected files from another user
 
 You can also copy a protected file from another user by providing their identity id
 
+<BlockSwitcher>
+<Block name="With Path (Above v6.2.0)">
+
+```javascript
+import { copy, list } from 'aws-amplify/storage';
+
+// Copies 'existing/srcPath' to 'copied/destPath' from 'protected' of another user to 'protected' of the current authenticated user
+
+const copied = await copy({
+  source: {
+    path: `protected/${targetUserId}/existing/srcPath`,
+  },
+  destination: {
+    path: ({identityId}) => `protected/${identityId}/copied/destPath`,
+  }
+});
+
+// There should now be a new file 'copied/destPath'
+console.log(
+  (await list({ path: ({identityId}) => `protected/${identityId}/copied/`})).items
+); // [..., path: 'protected/XXXXX/copied/destPath']
+console.log(copied); // { path: 'protected/XXXXX/copied/destPath' }
+```
+</Block>
+<Block name="With Key (Deprecated)">
+
 ```javascript
 import { copy, list } from 'aws-amplify/storage';
 
-// Copies 'existing/srcKey' to 'copied/destKey' from 'protected' of another identity ID to 'private' of the current
-// authenticated user
+// Copies 'existing/srcKey' to 'copied/destKey' from 'protected' of another user to 'private' of the current authenticated user
 
 const copied = await copy({
   source: {
@@ -143,25 +238,17 @@ const copied = await copy({
   }
 });
 
-// There should now be a new file with key "copied/destKey"
+// There should now be a new file with key 'copied/destKey'
 console.log(
   (await list({ prefix: 'copied/', options: { accessLevel: 'private' } })).items
 ); // [..., key: 'copied/destKey']
 console.log(copied); // { key: 'copied/destKey' }
 ```
-
-The format of the response will look similar to the below example
-
-```javascript
-{
-  key: 'copied/destKey';
-}
-```
+</Block>
+</BlockSwitcher>
 
 <Callout>
-
 Cross identity ID copying is only allowed if the source object's access level is set to 'protected'.
-
 </Callout>
 
 </InlineFilter>