Copy files

Storage.copy method copies an existing file to a different key and returns a {key: 'new S3 Object key'} object upon success.

Storage.copy can copy an object up to 5 GB in a single operation.

To copy a file, you need to provide a source key src and a destination key dest

1await Storage.copy(
2	src: { 
3		key: string,
4		level?: 'private' | 'protected' | 'public',
5		identityId?: string, // only required if you are copying a protected file from another user 
6	},
7	dest: { 
8		key: string,
9		level?: 'private' | 'protected' | 'public',
10	}, 
11	config?: {
12		track?: boolean, // if true, automatically send Storage Events to Amazon Pinpoint
13	}
14)

In addition, you can configure advanced capabilities such as cache control, meta data, and more.

1await Storage.copy({ key: 'src' }, { key: 'dest' }, {
2	cacheControl?: string, // Specifies caching behavior along the request/reply chain
3	expires?: Date, // The date at which the object is no longer cacheable
4	metadata?: [key: string]: string, // A map of metadata to store with the object in S3
5})

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 (Defaults to 'public').

1console.log(await Storage.list('copied/')); // []
2
3// Copies 'existing/srcKey' to 'copied/destKey' within the 'public' access level
4const copied = await Storage.copy({ key: 'existing/srcKey' }, { key: 'copied/destKey' });
5
6// There should now be a new file with key "copied/destKey"
7console.log(await Storage.list('copied/')); // [ { ..., key: 'copied/destKey' } ]
8console.log(copied); // { key: 'copied/destKey' }

Copy files across access levels

To copy file across different access levels, you'll need to explicitly provide the source and destination access levels:

1console.log(await Storage.list('copied/', { level: 'private' })); // []
2
3// Copies 'existing/srcKey' to 'copied/destKey' from 'public' to 'private'
4const copied = await Storage.copy(
5	{ key: 'existing/srcKey', level: 'public' }, 
6	{ key: 'copied/destKey', level: 'private' }
7);
8
9// There should now be a new file with key "copied/destKey" in the 'private' level
10console.log(await Storage.list('copied/', { level: 'private' })); // [ { ..., key: 'copied/destKey' } ]
11console.log(copied); // { key: 'copied/destKey' }

Copy protected files from another user

You can also copy a protected file from another user by providing their identity id

1console.log(await Storage.list('copied/', { level: 'private' })); // []
2
3// Copies 'existing/srcKey' to 'copied/destKey' from 'protected' of another identity ID to 'private' of the current
4// authenticated user
5
6const copied = await Storage.copy(
7	{ key: 'existing/srcKey', level: 'protected', identityId: 'identityId' },
8	{ key: 'copied/destKey', level: 'private' },
9)
10
11// There should now be a new file with key "copied/destKey"
12console.log(await Storage.list('copied/', { level: 'private' })); // [..., key: 'copied/destKey']
13console.log(copied); // { key: 'copied/destKey' }

Cross identity ID copying is only allowed if the source object's access level is set to 'protected'.

How to enable encrypted file copy

To utilize Server-Side Encryption with AWS KMS, the following options can be passed in to Storage.copy:

1const serverSideEncryption = AES256 | aws:kms;
2const SSECustomerAlgorithm = 'string';
3const SSECustomerKey = new Buffer('...') || 'string';
4const SSECustomerKeyMD5 = 'string';
5const SSEKMSKeyId = 'string';
6
7const result = await Storage.copy({ key: 'srcKey' }, { key: 'destKey' }, {
8		serverSideEncryption,
9		SSECustomerAlgorithm,
10		SSECustomerKey,
11		SSECustomerKeyMD5,
12		SSEKMSKeyId
13});

List files

Remove files