import { S3ClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from "../S3Client"; import { RestoreObjectOutput } from "../models/models_0"; import { RestoreObjectRequest } from "../models/models_1"; import { deserializeAws_restXmlRestoreObjectCommand, serializeAws_restXmlRestoreObjectCommand, } from "../protocols/Aws_restXml"; import { getBucketEndpointPlugin } from "@aws-sdk/middleware-bucket-endpoint"; import { getSerdePlugin } from "@aws-sdk/middleware-serde"; import { HttpRequest as __HttpRequest, HttpResponse as __HttpResponse } from "@aws-sdk/protocol-http"; import { Command as $Command } from "@aws-sdk/smithy-client"; import { FinalizeHandlerArguments, Handler, HandlerExecutionContext, MiddlewareStack, HttpHandlerOptions as __HttpHandlerOptions, MetadataBearer as __MetadataBearer, SerdeContext as __SerdeContext, } from "@aws-sdk/types"; export type RestoreObjectCommandInput = RestoreObjectRequest; export type RestoreObjectCommandOutput = RestoreObjectOutput & __MetadataBearer; /** *

Restores an archived copy of an object back into Amazon S3

This action is not supported by Amazon S3 on Outposts.

This action performs the following types of requests:

*
* select - Perform a select query on an archived object
*
*
* restore an archive - Restore an archived object
*

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 Simple Storage Service Developer Guide.

* Querying Archives with Select Requests *

You use a select type of request to perform SQL queries on archived objects. The * archived objects that are being queried by the select request must be formatted as * uncompressed comma-separated values (CSV) files. You can run queries and custom analytics * on your archived data without having to restore your data to a hotter Amazon S3 tier. For an * overview about select requests, see Querying Archived Objects in the Amazon Simple Storage Service Developer Guide.

When making a select request, do the following:

*
Define an output location for the select query's output. This must be an Amazon S3 * bucket in the same AWS Region as the bucket that contains the archive object that is * being queried. The AWS account that initiates the job must have permissions to write * to the S3 bucket. You can specify the storage class and encryption for the output * objects stored in the bucket. For more information about output, see Querying Archived Objects * in the Amazon Simple Storage Service Developer Guide.
*
For more information about the S3 structure in the request body, see * the following:
*
- *
  * PutObject *
  *
- *
  * Managing Access with * ACLs in the Amazon Simple Storage Service Developer Guide *
  *
- *
  * Protecting Data Using * Server-Side Encryption in the * Amazon Simple Storage Service Developer Guide *
  *
*
*
Define the SQL expression for the SELECT type of restoration for your * query in the request body's SelectParameters structure. You can use * expressions like the following examples.
*
- *
  The following expression returns all records from the specified * object.
  *
  * SELECT * FROM Object *
  *
- *
  Assuming that you are not using any headers for data stored in the object, * you can specify columns with positional headers.
  *
  * SELECT s._1, s._2 FROM Object s WHERE s._3 > 100 *
  *
- *
  If you have headers and you set the fileHeaderInfo in the * CSV structure in the request body to USE, you can * specify headers in the query. (If you set the fileHeaderInfo field * to IGNORE, the first row is skipped for the query.) You cannot mix * ordinal positions with header column names.
  *
  * SELECT s.Id, s.FirstName, s.SSN FROM S3Object s *
  *
*

For more information about using SQL with S3 Glacier Select restore, see SQL Reference for Amazon S3 Select and * S3 Glacier Select in the Amazon Simple Storage Service Developer Guide.

When making a select request, you can also do the following:

*
To expedite your queries, specify the Expedited tier. For more * information about tiers, see "Restoring Archives," later in this topic.
*
*
Specify details about the data serialization format of both the input object that * is being queried and the serialization of the CSV-encoded query results.
*

The following are additional important facts about the select feature:

*
The output results are new Amazon S3 objects. Unlike archive retrievals, they are * stored until explicitly deleted-manually or through a lifecycle policy.
*
*
You can issue more than one select request on the same Amazon S3 object. Amazon S3 doesn't * deduplicate requests, so avoid issuing duplicate requests.
*
*
Amazon S3 accepts a select request even if the object has already been restored. A * select request doesn’t return error response 409.
*

* Restoring objects *

Objects that you archive to the S3 Glacier 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 * Archive Access or Deep Archive Access tiers you must first initiate a restore request, and * then wait until the object is moved into the Frequent Access tier. For objects in * S3 Glacier 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. To access an archived object, you must restore the object for the duration * (number of days) that you specify.

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 (or using a select request), 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 * storage class or S3 Intelligent-Tiering Archive tier when occasional urgent requests for a * subset of 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 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 are the * lowest-cost retrieval option in S3 Glacier, enabling you to retrieve large amounts, * even petabytes, of data inexpensively. Bulk retrievals typically finish within 5–12 * hours for objects stored in the S3 Glacier storage class or * S3 Intelligent-Tiering Archive tier. They typically finish within 48 hours for objects stored * in the S3 Glacier Deep Archive storage class or S3 Intelligent-Tiering Deep Archive tier. * Bulk retrievals are free for objects stored in S3 Intelligent-Tiering.
*

For more information about archive retrieval options and provisioned capacity for * Expedited data access, see Restoring Archived Objects in the Amazon Simple Storage Service Developer 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 Simple Storage Service Developer 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 Simple Storage Service Developer 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 Simple Storage Service Developer Guide.

* Responses *

A successful operation 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. (This error does not * apply to SELECT type requests.) *
  *
- *
  * 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 *
  *
*

* *

* Related Resources *

*
* PutBucketLifecycleConfiguration *
*
*
* GetBucketNotificationConfiguration *
*
*
* SQL Reference for * Amazon S3 Select and S3 Glacier Select in the * Amazon Simple Storage Service Developer Guide *
*

*/ export class RestoreObjectCommand extends $Command< RestoreObjectCommandInput, RestoreObjectCommandOutput, S3ClientResolvedConfig > { // Start section: command_properties // End section: command_properties constructor(readonly input: RestoreObjectCommandInput) { // Start section: command_constructor super(); // End section: command_constructor } /** * @internal */ resolveMiddleware( clientStack: MiddlewareStack, configuration: S3ClientResolvedConfig, options?: __HttpHandlerOptions ): Handler { this.middlewareStack.use(getSerdePlugin(configuration, this.serialize, this.deserialize)); this.middlewareStack.use(getBucketEndpointPlugin(configuration)); const stack = clientStack.concat(this.middlewareStack); const { logger } = configuration; const clientName = "S3Client"; const commandName = "RestoreObjectCommand"; const handlerExecutionContext: HandlerExecutionContext = { logger, clientName, commandName, inputFilterSensitiveLog: RestoreObjectRequest.filterSensitiveLog, outputFilterSensitiveLog: RestoreObjectOutput.filterSensitiveLog, }; const { requestHandler } = configuration; return stack.resolve( (request: FinalizeHandlerArguments) => requestHandler.handle(request.request as __HttpRequest, options || {}), handlerExecutionContext ); } private serialize(input: RestoreObjectCommandInput, context: __SerdeContext): Promise<__HttpRequest> { return serializeAws_restXmlRestoreObjectCommand(input, context); } private deserialize(output: __HttpResponse, context: __SerdeContext): Promise { return deserializeAws_restXmlRestoreObjectCommand(output, context); } // Start section: command_body_extra // End section: command_body_extra }