AWS Tools for Windows PowerShell
Command Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Synopsis

Calls the Amazon S3 CopyObject API operation to copy an existing S3 object to another S3 destination (bucket and/or object), or download a single S3 object to a local file or folder or download object(s) matching a supplied key prefix to a folder.

Syntax

CopySingleObjectToLocalFile (Default)
Copy-S3Object
-BucketName <String>
-Key <String>
-LocalFile <String>
-VersionId <String>
-ModifiedSinceDate <DateTime>
-UnmodifiedSinceDate <DateTime>
-UtcModifiedSinceDate <DateTime>
-UtcUnmodifiedSinceDate <DateTime>
-ServerSideEncryptionCustomerMethod <ServerSideEncryptionCustomerMethod>
-ServerSideEncryptionCustomerProvidedKey <String>
-ServerSideEncryptionCustomerProvidedKeyMD5 <String>
-ChecksumMode <ChecksumMode>
-IfNoneMatch <String>
-RequestPayer <RequestPayer>
-Force <SwitchParameter>
-ClientConfig <AmazonS3Config>
-UseAccelerateEndpoint <SwitchParameter>
-UseDualstackEndpoint <SwitchParameter>
-ForcePathStyleAddressing <Boolean>
CopyS3ObjectToS3Object
Copy-S3Object
-BucketName <String>
-Key <String>
-DestinationKey <String>
-DestinationBucket <String>
-VersionId <String>
-MetadataDirective <S3MetadataDirective>
-ContentType <String>
-SourceRegion <Object>
-CannedACLName <S3CannedACL>
-PublicReadOnly <SwitchParameter>
-PublicReadWrite <SwitchParameter>
-StorageClass <S3StorageClass>
-StandardStorage <SwitchParameter>
-ReducedRedundancyStorage <SwitchParameter>
-ServerSideEncryption <ServerSideEncryptionMethod>
-ServerSideEncryptionKeyManagementServiceKeyId <String>
-WebsiteRedirectLocation <String>
-Metadata <Hashtable>
-HeaderCollection <Hashtable>
-TagSet <Tag[]>
-ETagToMatch <String>
-ETagToNotMatch <String>
-ModifiedSinceDate <DateTime>
-UnmodifiedSinceDate <DateTime>
-UtcModifiedSinceDate <DateTime>
-UtcUnmodifiedSinceDate <DateTime>
-CopySourceServerSideEncryptionCustomerMethod <ServerSideEncryptionCustomerMethod>
-CopySourceServerSideEncryptionCustomerProvidedKey <String>
-CopySourceServerSideEncryptionCustomerProvidedKeyMD5 <String>
-ServerSideEncryptionCustomerMethod <ServerSideEncryptionCustomerMethod>
-ServerSideEncryptionCustomerProvidedKey <String>
-ServerSideEncryptionCustomerProvidedKeyMD5 <String>
-ChecksumAlgorithm <ChecksumAlgorithm>
-ChecksumMode <ChecksumMode>
-IfNoneMatch <String>
-RequestPayer <RequestPayer>
-Force <SwitchParameter>
-ClientConfig <AmazonS3Config>
-UseAccelerateEndpoint <SwitchParameter>
-UseDualstackEndpoint <SwitchParameter>
-ForcePathStyleAddressing <Boolean>
CopySingleObjectToLocalFolder
Copy-S3Object
-BucketName <String>
-Key <String>
-VersionId <String>
-LocalFolder <String>
-ModifiedSinceDate <DateTime>
-UnmodifiedSinceDate <DateTime>
-UtcModifiedSinceDate <DateTime>
-UtcUnmodifiedSinceDate <DateTime>
-ServerSideEncryptionCustomerMethod <ServerSideEncryptionCustomerMethod>
-ServerSideEncryptionCustomerProvidedKey <String>
-ServerSideEncryptionCustomerProvidedKeyMD5 <String>
-ChecksumMode <ChecksumMode>
-IfNoneMatch <String>
-RequestPayer <RequestPayer>
-Force <SwitchParameter>
-ClientConfig <AmazonS3Config>
-UseAccelerateEndpoint <SwitchParameter>
-UseDualstackEndpoint <SwitchParameter>
-ForcePathStyleAddressing <Boolean>
CopyMultipleObjectsToLocalFolder
Copy-S3Object
-BucketName <String>
-LocalFolder <String>
-KeyPrefix <String>
-ModifiedSinceDate <DateTime>
-UnmodifiedSinceDate <DateTime>
-UtcModifiedSinceDate <DateTime>
-UtcUnmodifiedSinceDate <DateTime>
-IfNoneMatch <String>
-RequestPayer <RequestPayer>
-Force <SwitchParameter>
-ClientConfig <AmazonS3Config>
-UseAccelerateEndpoint <SwitchParameter>
-UseDualstackEndpoint <SwitchParameter>
-ForcePathStyleAddressing <Boolean>

Description

Amazon.PowerShell.Cmdlets.S3.CopyS3ObjectCmdlet

Parameters

-BucketName <String>
The name of the bucket containing the source object.When using this action with an access point, you must direct requests to the access point hostname. The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. When using this action with an access point through the Amazon Web Services SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, see Using access points in the Amazon S3 User Guide.When you use this action with Amazon S3 on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When you use this action with S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts in the Amazon S3 User Guide.
Required?True
Position?1
Accept pipeline input?True (ByValue, ByPropertyName)
AliasesSourceBucket
-CannedACLName <S3CannedACL>
Amazon.PowerShell.Cmdlets.S3.CopyS3ObjectCmdlet.CannedACLName
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ChecksumAlgorithm <ChecksumAlgorithm>
Indicates the algorithm you want Amazon S3 to use to create the checksum for the object. For more information, see Checking object integrity in the Amazon S3 User Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ChecksumMode <ChecksumMode>
Specifies base64-encoded MD5 of the encryption key for Amazon S3 to use to decrypt the object. This field is optional, the SDK will calculate the MD5 if this is not set.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ClientConfig <AmazonS3Config>
Amazon.PowerShell.Cmdlets.S3.AmazonS3ClientCmdlet.ClientConfig
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ContentType <String>
Sets the content type of the target object; if not specified an attempt is made to infer it using the destination or source object keys.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-CopySourceServerSideEncryptionCustomerMethod <ServerSideEncryptionCustomerMethod>
Specifies the server-side encryption algorithm used on the source object with the customer provided key. Allowable values: None or AES256.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-CopySourceServerSideEncryptionCustomerProvidedKey <String>
Specifies base64-encoded encryption key for Amazon S3 used on the source object.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-CopySourceServerSideEncryptionCustomerProvidedKeyMD5 <String>
Specifies base64-encoded MD5 of the encryption key for Amazon S3 used on the source object. This field is optional, the SDK will calculate the MD5 if this is not set.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-DestinationBucket <String>
The name of the bucket that will contain the copied object. If not specified, the copy is to another S3 object in the source bucket.Directory buckets - When you use this operation with a directory bucket, you must use virtual-hosted-style requests in the format Bucket_name.s3express-az_id.region.amazonaws.com. Path-style requests are not supported. Directory bucket names must be unique in the chosen Availability Zone. Bucket names must follow the format bucket_base_name--az-id--x-s3 (for example, DOC-EXAMPLE-BUCKET--usw2-az1--x-s3). For information about bucket naming restrictions, see Directory bucket naming rules in the Amazon S3 User Guide.Access points - When you use this action with an access point, you must provide the alias of the access point in place of the bucket name or specify the access point ARN. When using the access point ARN, you must direct requests to the access point hostname. The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. When using this action with an access point through the Amazon Web Services SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, see Using access points in the Amazon S3 User Guide.Access points and Object Lambda access points are not supported by directory buckets.S3 on Outposts - When you use this action with Amazon S3 on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When you use this action with S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts? in the Amazon S3 User Guide.
Required?False
Position?4
Accept pipeline input?True (ByPropertyName)
-DestinationKey <String>
The key for the copy of the source S3 object.
Required?False
Position?3
Accept pipeline input?True (ByPropertyName)
-ETagToMatch <String>
Copies the object if its entity tag (ETag) matches the specified tag; otherwise return a PreconditionFailed.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ETagToNotMatch <String>
Copies the object if its entity tag (ETag) is different than the specified Etag; otherwise returns an error.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Force <SwitchParameter>
This parameter overrides confirmation prompts to force the cmdlet to continue its operation. This parameter should always be used with caution.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ForcePathStyleAddressing <Boolean>
S3 requests can be performed using one of two URI styles: Virtual or Path. When using Virtual style, the bucket is included as part of the hostname. When using Path style the bucket is included as part of the URI path. The default value is $true when the EndpointUrl parameter is specified, $false otherwise.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-HeaderCollection <Hashtable>
Response headers to set on the object.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesHeaders
-IfNoneMatch <String>
Uploads the object only if the object key name does not already exist in the bucket specified. Otherwise, Amazon S3 returns a 412 Precondition Failed error.If a conflicting operation occurs during the upload S3 returns a 409 ConditionalRequestConflict response. On a 409 failure you should re-initiate the multipart upload with CreateMultipartUpload and re-upload each part.Expects the '*' (asterisk) character.For more information about conditional requests, see RFC 7232, or Conditional requests in the Amazon S3 User Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Key <String>
The key of the single source object to copy.
Required?True (CopySingleObjectToLocalFile, CopyS3ObjectToS3Object)
Position?2
Accept pipeline input?True (ByPropertyName)
AliasesSourceKey
-KeyPrefix <String>
Used to download multiple objects to the specified local folder. The supplied prefix will be used to determine the set of objects to download that share the same key prefix. You must specify either this parameter, or the -Key parameter, to determine what object(s) to download.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSourcePrefix
-LocalFile <String>
The full path to the local file that will be created.
Required?True
Position?3
Accept pipeline input?True (ByPropertyName)
AliasesFile
-LocalFolder <String>
The path to a local folder that will contain the downloaded object. If a relative path is supplied, it will be resolved to a full path using the current session's location.When copying to a local folder the object key is used as the filename. Note that object keys that are not valid filenames for the host system could cause an exception to be thrown.
Required?True
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesFolder
-Metadata <Hashtable>
Metadata headers to set on the object.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-MetadataDirective <S3MetadataDirective>
Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request. Valid values are COPY or REPLACE. COPY is the default if not specified.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ModifiedSinceDate <DateTime>
Copies the object if it has been modified since the specified time; otherwise returns an error. This parameter is deprecated.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-PublicReadOnly <SwitchParameter>
If set, applies an ACL making the bucket public with read-only permissions
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-PublicReadWrite <SwitchParameter>
If set, applies an ACL making the bucket public with read-write permissions
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ReducedRedundancyStorage <SwitchParameter>
Specifies S3 should use REDUCED_REDUNDANCY storage class for the object. This provides a reduced (99.99%) durability guarantee at a lower cost as compared to the STANDARD storage class. Use this storage class for non-mission critical data or for data that doesn’t require the higher level of durability that S3 provides with the STANDARD storage class.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-RequestPayer <RequestPayer>
Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ServerSideEncryption <ServerSideEncryptionMethod>
The server-side encryption algorithm used when storing this object in Amazon S3 (for example, AES256, aws:kms).
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ServerSideEncryptionCustomerMethod <ServerSideEncryptionCustomerMethod>
Specifies the server-side encryption algorithm to be used with the customer provided key. Allowable values: None or AES256.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ServerSideEncryptionCustomerProvidedKey <String>
Specifies base64-encoded encryption key for Amazon S3 to use to decrypt the object.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ServerSideEncryptionCustomerProvidedKeyMD5 <String>
Specifies base64-encoded MD5 of the encryption key for Amazon S3 to use to decrypt the object. This field is optional, the SDK will calculate the MD5 if this is not set.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ServerSideEncryptionKeyManagementServiceKeyId <String>
Specifies the AWS KMS key for Amazon S3 to use to encrypt the object. Specifies the Amazon Web Services KMS key ID to use for object encryption. All GET and PUT requests for an object protected by Amazon Web Services KMS will fail if not made via SSL or using SigV4. For information about configuring using any of the officially supported Amazon Web Services SDKs and Amazon Web Services CLI, see Specifying the Signature Version in Request Authentication in the Amazon S3 User Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-SourceRegion <Object>
Specifies the Region that the source bucket resides in; If not specified an attempt is made to infer it using the Region set in your credential profile. The -Region parameter specifies the Destination Region.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-StandardStorage <SwitchParameter>
Specifies the STANDARD storage class, which is the default storage class for S3 objects. Provides a 99.999999999% durability guarantee.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-StorageClass <S3StorageClass>
Specifies the storage class for the object. Please refer to Storage Classes for information on S3 storage classes.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-TagSet <Tag[]>
One or more tags to apply to the object.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-UnmodifiedSinceDate <DateTime>
Copies the object if it hasn't been modified since the specified time; otherwise returns a PreconditionFailed. This parameter is deprecated.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-UseAccelerateEndpoint <SwitchParameter>
Enables S3 accelerate by sending requests to the accelerate endpoint instead of the regular region endpoint. To use this feature, the bucket name must be DNS compliant and must not contain periods (.).
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-UseDualstackEndpoint <SwitchParameter>
Configures the request to Amazon S3 to use the dualstack endpoint for a region. S3 supports dualstack endpoints which return both IPv6 and IPv4 values. The dualstack mode of Amazon S3 cannot be used with accelerate mode.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-UtcModifiedSinceDate <DateTime>
Copies the object if it has been modified since the specified time; otherwise returns an error.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-UtcUnmodifiedSinceDate <DateTime>
Copies the object if it hasn't been modified since the specified time; otherwise returns a PreconditionFailed.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-VersionId <String>
Specifies the version of the source object to copy.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSourceVersionId
-WebsiteRedirectLocation <String>
If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata. This value is unique to each object and is not copied when using the x-amz-metadata-directive header. Instead, you may opt to provide this header in combination with the directive.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)

Common Credential and Region Parameters

-AccessKey <String>
The AWS access key for the user account. This can be a temporary access key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAK
-Credential <AWSCredentials>
An AWSCredentials object instance containing access and secret key information, and optionally a token for session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-EndpointUrl <String>
The endpoint to make the call against.Note: This parameter is primarily for internal AWS use and is not required/should not be specified for normal usage. The cmdlets normally determine which endpoint to call based on the region specified to the -Region parameter or set as default in the shell (via Set-DefaultAWSRegion). Only specify this parameter if you must direct the call to a specific custom endpoint.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-NetworkCredential <PSCredential>
Used with SAML-based authentication when ProfileName references a SAML role profile. Contains the network credentials to be supplied during authentication with the configured identity provider's endpoint. This parameter is not required if the user's default network identity can or should be used during authentication.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-ProfileLocation <String>
Used to specify the name and location of the ini-format credential file (shared with the AWS CLI and other AWS SDKs)If this optional parameter is omitted this cmdlet will search the encrypted credential file used by the AWS SDK for .NET and AWS Toolkit for Visual Studio first. If the profile is not found then the cmdlet will search in the ini-format credential file at the default location: (user's home directory)\.aws\credentials.If this parameter is specified then this cmdlet will only search the ini-format credential file at the location given.As the current folder can vary in a shell or during script execution it is advised that you use specify a fully qualified path instead of a relative path.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAWSProfilesLocation, ProfilesLocation
-ProfileName <String>
The user-defined name of an AWS credentials or SAML-based role profile containing credential information. The profile is expected to be found in the secure credential file shared with the AWS SDK for .NET and AWS Toolkit for Visual Studio. You can also specify the name of a profile stored in the .ini-format credential file used with the AWS CLI and other AWS SDKs.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesStoredCredentials, AWSProfileName
-Region <Object>
The system name of an AWS region or an AWSRegion instance. This governs the endpoint that will be used when calling service operations. Note that the AWS resources referenced in a call are usually region-specific.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesRegionToCall
-SecretKey <String>
The AWS secret key for the user account. This can be a temporary secret key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSK, SecretAccessKey
-SessionToken <String>
The session token if the access and secret keys are temporary session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesST

Outputs

Amazon.S3.Model.S3Object or System.IO.FileInfo or System.IO.DirectoryInfo
When copying an object to another object in S3 the cmdlet returns an Amazon.S3.Model.S3Object referencing the new object. When copying a single object from S3 to the local file system the cmdlet returns a FileInfo instance representing the local file. When copying multiple objects to a local folder the cmdlet returns a DirectoryInfo instance to the folder.

Examples

Example 1

Copy-S3Object -BucketName amzn-s3-demo-bucket -Key sample.txt -DestinationKey sample-copy.txt
This command copies the object "sample.txt" from bucket "test-files" to the same bucket but with a new key of "sample-copy.txt".

Example 2

Copy-S3Object -BucketName amzn-s3-demo-source-bucket -Key sample.txt -DestinationKey sample-copy.txt -DestinationBucket amzn-s3-demo-destination-bucket
This command copies the object "sample.txt" from bucket "test-files" to the bucket "backup-files" with a key of "sample-copy.txt".

Example 3

Copy-S3Object -BucketName amzn-s3-demo-bucket -Key sample.txt -LocalFile local-sample.txt
This command downloads the object "sample.txt" from bucket "test-files" to a local file with name "local-sample.txt".

Example 4

Copy-S3Object -BucketName amzn-s3-demo-bucket -Key data/archive.zip -LocalFolder c:\downloads
Downloads the single object to the specified file. The downloaded file will be found at c:\downloads\data\archive.zip

Example 5

Copy-S3Object -BucketName amzn-s3-demo-bucket -KeyPrefix data -LocalFolder c:\downloads
Downloads all objects that match the specified key prefix to the local folder. The relative key hierarchy will be preserved as subfolders in the overall download location.
Getting Started Guide
Developer Guide
Service API Reference
AWS Tools for PowerShell User Guide

Supported Version

AWS Tools for PowerShell: 2.x.y.z