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 Simple Storage Service (S3) RestoreObject API operation.

Syntax

Restore-S3Object
-BucketName <String>
-Key <String>
-CopyLifetimeInDays <Int32>
-S3_BucketName <String>
-S3_CannedACL <S3CannedACL>
-ChecksumAlgorithm <ChecksumAlgorithm>
-Description <String>
-Owner_DisplayName <String>
-Encryption_EncryptionType <ServerSideEncryptionMethod>
-ExpectedBucketOwner <String>
-AccessControlList_Grant <S3Grant[]>
-Owner_Id <String>
-Encryption_KMSContext <String>
-Encryption_KMSKeyId <String>
-S3_Prefix <String>
-RequestPayer <RequestPayer>
-RestoreRequestType <RestoreRequestType>
-RetrievalTier <GlacierJobTier>
-SelectParameter <SelectParameters>
-S3_StorageClass <S3StorageClass>
-Tagging_TagSet <Tag[]>
-Tier <GlacierJobTier>
-S3_UserMetadata <MetadataCollection>
-VersionId <String>
-Select <String>
-Force <SwitchParameter>
-ClientConfig <AmazonS3Config>
-UseAccelerateEndpoint <SwitchParameter>
-UseDualstackEndpoint <SwitchParameter>
-ForcePathStyleAddressing <Boolean>

Description

This operation is not supported for directory buckets. Restores an archived copy of an object back into Amazon S3 This functionality is not supported for Amazon S3 on Outposts. This action performs the following types of requests:
  • restore an archive - Restore an archived object
For more information about the S3 structure in the request body, see the following:
Permissions
To use this operation, you must have permissions to perform the s3:RestoreObject action. The bucket owner has this permission by default and can grant this permission to others. For more information about permissions, see Permissions Related to Bucket Subresource Operations and Managing Access Permissions to Your Amazon S3 Resources in the Amazon S3 User Guide.
Restoring objects
Objects that you archive to the S3 Glacier Flexible Retrieval or S3 Glacier Deep Archive storage class, and S3 Intelligent-Tiering Archive or S3 Intelligent-Tiering Deep Archive tiers, are not accessible in real time. For objects in the S3 Glacier Flexible Retrieval or S3 Glacier Deep Archive storage classes, you must first initiate a restore request, and then wait until a temporary copy of the object is available. If you want a permanent copy of the object, create a copy of it in the Amazon S3 Standard storage class in your S3 bucket. To access an archived object, you must restore the object for the duration (number of days) that you specify. For objects in the Archive Access or Deep Archive Access tiers of S3 Intelligent-Tiering, you must first initiate a restore request, and then wait until the object is moved into the Frequent Access tier. To restore a specific object version, you can provide a version ID. If you don't provide a version ID, Amazon S3 restores the current version. When restoring an archived object, you can specify one of the following data access tier options in the Tier element of the request body:
  • Expedited - Expedited retrievals allow you to quickly access your data stored in the S3 Glacier Flexible Retrieval storage class or S3 Intelligent-Tiering Archive tier when occasional urgent requests for restoring archives are required. For all but the largest archived objects (250 MB+), data accessed using Expedited retrievals is typically made available within 1–5 minutes. Provisioned capacity ensures that retrieval capacity for Expedited retrievals is available when you need it. Expedited retrievals and provisioned capacity are not available for objects stored in the S3 Glacier Deep Archive storage class or S3 Intelligent-Tiering Deep Archive tier.
  • Standard - Standard retrievals allow you to access any of your archived objects within several hours. This is the default option for retrieval requests that do not specify the retrieval option. Standard retrievals typically finish within 3–5 hours for objects stored in the S3 Glacier Flexible Retrieval storage class or S3 Intelligent-Tiering Archive tier. They typically finish within 12 hours for objects stored in the S3 Glacier Deep Archive storage class or S3 Intelligent-Tiering Deep Archive tier. Standard retrievals are free for objects stored in S3 Intelligent-Tiering.
  • Bulk - Bulk retrievals free for objects stored in the S3 Glacier Flexible Retrieval and S3 Intelligent-Tiering storage classes, enabling you to retrieve large amounts, even petabytes, of data at no cost. Bulk retrievals typically finish within 5–12 hours for objects stored in the S3 Glacier Flexible Retrieval storage class or S3 Intelligent-Tiering Archive tier. Bulk retrievals are also the lowest-cost retrieval option when restoring objects from S3 Glacier Deep Archive. They typically finish within 48 hours for objects stored in the S3 Glacier Deep Archive storage class or S3 Intelligent-Tiering Deep Archive tier.
For more information about archive retrieval options and provisioned capacity for Expedited data access, see Restoring Archived Objects in the Amazon S3 User Guide. You can use Amazon S3 restore speed upgrade to change the restore speed to a faster speed while it is in progress. For more information, see Upgrading the speed of an in-progress restore in the Amazon S3 User Guide. To get the status of object restoration, you can send a HEAD request. Operations return the x-amz-restore header, which provides information about the restoration status, in the response. You can use Amazon S3 event notifications to notify you when a restore is initiated or completed. For more information, see Configuring Amazon S3 Event Notifications in the Amazon S3 User Guide. After restoring an archived object, you can update the restoration period by reissuing the request with a new period. Amazon S3 updates the restoration period relative to the current time and charges only for the request-there are no data transfer charges. You cannot update the restoration period when Amazon S3 is actively processing your current restore request for the object. If your bucket has a lifecycle configuration with a rule that includes an expiration action, the object expiration overrides the life span that you specify in a restore request. For example, if you restore an object copy for 10 days, but the object is scheduled to expire in 3 days, Amazon S3 deletes the object in 3 days. For more information about lifecycle configuration, see PutBucketLifecycleConfiguration and Object Lifecycle Management in Amazon S3 User Guide.
Responses
A successful action returns either the 200 OK or 202 Accepted status code.
  • If the object is not previously restored, then Amazon S3 returns 202 Accepted in the response.
  • If the object is previously restored, Amazon S3 returns 200 OK in the response.
  • Special errors:
    • Code: RestoreAlreadyInProgress
    • Cause: Object restore is already in progress.
    • HTTP Status Code: 409 Conflict
    • SOAP Fault Code Prefix: Client
    • Code: GlacierExpeditedRetrievalNotAvailable
    • Cause: expedited retrievals are currently not available. Try again later. (Returned if there is insufficient capacity to process the Expedited request. This error applies only to Expedited retrievals and not to S3 Standard or Bulk retrievals.)
    • HTTP Status Code: 503
    • SOAP Fault Code Prefix: N/A
The following operations are related to RestoreObject: You must URL encode any signed header values that contain spaces. For example, if your header value is my file.txt, containing two spaces after my, you must URL encode this value to my%20%20file.txt.

Parameters

-AccessControlList_Grant <S3Grant[]>
A list of grants. Starting with version 4 of the SDK this property will default to null. If no data for this property is returned from the service the property will also be null. This was changed to improve performance and allow the SDK and caller to distinguish between a property not set or a property being empty to clear out a value. To retain the previous SDK behavior set the AWSConfigs.InitializeCollections static property to true.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputLocation_S3_AccessControlList_Grants
-BucketName <String>
The bucket name containing the object to restore. Access points - When you use this action with an access point for general purpose buckets, you must provide the alias of the access point in place of the bucket name or specify the access point ARN. When you use this action with an access point for directory buckets, you must provide the access point name in place of the bucket name. 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.S3 on Outposts - When you use this action with 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, the destination bucket must be the Outposts access point ARN or the access point alias. For more information about S3 on Outposts, see What is S3 on Outposts? in the Amazon S3 User Guide.
Required?True
Position?1
Accept pipeline input?True (ByValue, ByPropertyName)
-ChecksumAlgorithm <ChecksumAlgorithm>
Indicates the algorithm used to create the checksum for the object when you use the SDK. This header will not provide any additional functionality if you don't use the SDK. When you send this header, there must be a corresponding x-amz-checksum or x-amz-trailer header sent. Otherwise, Amazon S3 fails the request with the HTTP status code 400 Bad Request. For more information, see Checking object integrity in the Amazon S3 User Guide.If you provide an individual checksum, Amazon S3 ignores any provided ChecksumAlgorithm parameter.
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)
-CopyLifetimeInDays <Int32>
Lifetime of the active copy in days. Do not use with restores that specify OutputLocation.The Days element is required for regular restores, and must not be provided for select requests.
Required?False
Position?3
Accept pipeline input?True (ByPropertyName)
AliasesDays
-Description <String>
The optional description for the job.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Encryption_EncryptionType <ServerSideEncryptionMethod>
The server-side encryption algorithm used when storing job results in Amazon S3 (for example, AES256, aws:kms).
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputLocation_S3_Encryption_EncryptionType
-Encryption_KMSContext <String>
If the encryption type is aws:kms, this optional value can be used to specify the encryption context for the restore results.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputLocation_S3_Encryption_KMSContext
-Encryption_KMSKeyId <String>
If the encryption type is aws:kms, this optional value specifies the ID of the symmetric encryption customer managed key to use for encryption of job results. Amazon S3 only supports symmetric encryption KMS keys. For more information, see Asymmetric keys in KMS in the Amazon Web Services Key Management Service Developer Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputLocation_S3_Encryption_KMSKeyId
-ExpectedBucketOwner <String>
The account ID of the expected bucket owner. If the account ID that you provide does not match the actual owner of the bucket, the request fails with the HTTP status code 403 Forbidden (access denied).
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)
-Key <String>
Object key for which the action was initiated.
Required?True
Position?2
Accept pipeline input?True (ByPropertyName)
-Owner_DisplayName <String>
The service has not provided documentation for this parameter; please refer to the service's API reference documentation for the latest available information.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputLocation_S3_AccessControlList_Owner_DisplayName
-Owner_Id <String>
Container for the ID of the owner.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputLocation_S3_AccessControlList_Owner_Id
-RequestPayer <RequestPayer>
The service has not provided documentation for this parameter; please refer to the service's API reference documentation for the latest available information.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-RestoreRequestType <RestoreRequestType>
Amazon S3 Select is no longer available to new customers. Existing customers of Amazon S3 Select can continue to use the feature as usual. Learn moreType of restore request.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-RetrievalTier <GlacierJobTier>
Retrieval tier at which the restore will be processed.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-S3_BucketName <String>
The name of the bucket where the restore results will be placed.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputLocation_S3_BucketName
-S3_CannedACL <S3CannedACL>
The canned ACL to apply to the restore results.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputLocation_S3_CannedACL
-S3_Prefix <String>
The prefix that is prepended to the restore results for this request.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputLocation_S3_Prefix
-S3_StorageClass <S3StorageClass>
The class of storage used to store the restore results.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputLocation_S3_StorageClass
-S3_UserMetadata <MetadataCollection>
A list of metadata to store with the restore results in S3. Starting with version 4 of the SDK this property will default to null. If no data for this property is returned from the service the property will also be null. This was changed to improve performance and allow the SDK and caller to distinguish between a property not set or a property being empty to clear out a value. To retain the previous SDK behavior set the AWSConfigs.InitializeCollections static property to true.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputLocation_S3_UserMetadata
-Select <String>
Use the -Select parameter to control the cmdlet output. The default value is '*'. Specifying -Select '*' will result in the cmdlet returning the whole service response (Amazon.S3.Model.RestoreObjectResponse). Specifying the name of a property of type Amazon.S3.Model.RestoreObjectResponse will result in that property being returned. Specifying -Select '^ParameterName' will result in the cmdlet returning the selected cmdlet parameter value.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-SelectParameter <SelectParameters>
Amazon S3 Select is no longer available to new customers. Existing customers of Amazon S3 Select can continue to use the feature as usual. Learn moreDescribes the parameters for Select job types.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSelectParameters
-Tagging_TagSet <Tag[]>
A collection for a set of tags Starting with version 4 of the SDK this property will default to null. If no data for this property is returned from the service the property will also be null. This was changed to improve performance and allow the SDK and caller to distinguish between a property not set or a property being empty to clear out a value. To retain the previous SDK behavior set the AWSConfigs.InitializeCollections static property to true.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputLocation_S3_Tagging_TagSet
-Tier <GlacierJobTier>
S3 Glacier related parameters pertaining to this job. Do not use with restores that specify OutputLocation.
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)
-VersionId <String>
VersionId used to reference a specific version of the object.
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.RestoreObjectResponse
This cmdlet returns an Amazon.S3.Model.RestoreObjectResponse object containing multiple properties.
Getting Started Guide
Developer Guide
Service API Reference
AWS Tools for PowerShell User Guide

Supported Version

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