1// Code generated by smithy-go-codegen DO NOT EDIT. 2 3package s3 4 5import ( 6 "context" 7 awsmiddleware "github.com/aws/aws-sdk-go-v2/aws/middleware" 8 "github.com/aws/aws-sdk-go-v2/aws/signer/v4" 9 s3cust "github.com/aws/aws-sdk-go-v2/service/s3/internal/customizations" 10 "github.com/aws/aws-sdk-go-v2/service/s3/types" 11 "github.com/aws/smithy-go/middleware" 12 smithyhttp "github.com/aws/smithy-go/transport/http" 13) 14 15// Restores an archived copy of an object back into Amazon S3 This action is not 16// supported by Amazon S3 on Outposts. This action performs the following types of 17// requests: 18// 19// * select - Perform a select query on an archived object 20// 21// * restore an 22// archive - Restore an archived object 23// 24// To use this operation, you must have 25// permissions to perform the s3:RestoreObject action. The bucket owner has this 26// permission by default and can grant this permission to others. For more 27// information about permissions, see Permissions Related to Bucket Subresource 28// Operations 29// (https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-with-s3-actions.html#using-with-s3-actions-related-to-bucket-subresources) 30// and Managing Access Permissions to Your Amazon S3 Resources 31// (https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-access-control.html) 32// in the Amazon S3 User Guide. Querying Archives with Select Requests You use a 33// select type of request to perform SQL queries on archived objects. The archived 34// objects that are being queried by the select request must be formatted as 35// uncompressed comma-separated values (CSV) files. You can run queries and custom 36// analytics on your archived data without having to restore your data to a hotter 37// Amazon S3 tier. For an overview about select requests, see Querying Archived 38// Objects 39// (https://docs.aws.amazon.com/AmazonS3/latest/dev/querying-glacier-archives.html) 40// in the Amazon S3 User Guide. When making a select request, do the following: 41// 42// * 43// Define an output location for the select query's output. This must be an Amazon 44// S3 bucket in the same AWS Region as the bucket that contains the archive object 45// that is being queried. The AWS account that initiates the job must have 46// permissions to write to the S3 bucket. You can specify the storage class and 47// encryption for the output objects stored in the bucket. For more information 48// about output, see Querying Archived Objects 49// (https://docs.aws.amazon.com/AmazonS3/latest/dev/querying-glacier-archives.html) 50// in the Amazon S3 User Guide. For more information about the S3 structure in the 51// request body, see the following: 52// 53// * PutObject 54// (https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) 55// 56// * Managing 57// Access with ACLs 58// (https://docs.aws.amazon.com/AmazonS3/latest/dev/S3_ACLs_UsingACLs.html) in the 59// Amazon S3 User Guide 60// 61// * Protecting Data Using Server-Side Encryption 62// (https://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html) in 63// the Amazon S3 User Guide 64// 65// * Define the SQL expression for the SELECT type of 66// restoration for your query in the request body's SelectParameters structure. You 67// can use expressions like the following examples. 68// 69// * The following expression 70// returns all records from the specified object. SELECT * FROM Object 71// 72// * Assuming 73// that you are not using any headers for data stored in the object, you can 74// specify columns with positional headers. SELECT s._1, s._2 FROM Object s WHERE 75// s._3 > 100 76// 77// * If you have headers and you set the fileHeaderInfo in the CSV 78// structure in the request body to USE, you can specify headers in the query. (If 79// you set the fileHeaderInfo field to IGNORE, the first row is skipped for the 80// query.) You cannot mix ordinal positions with header column names. SELECT s.Id, 81// s.FirstName, s.SSN FROM S3Object s 82// 83// For more information about using SQL with S3 84// Glacier Select restore, see SQL Reference for Amazon S3 Select and S3 Glacier 85// Select 86// (https://docs.aws.amazon.com/AmazonS3/latest/dev/s3-glacier-select-sql-reference.html) 87// in the Amazon S3 User Guide. When making a select request, you can also do the 88// following: 89// 90// * To expedite your queries, specify the Expedited tier. For more 91// information about tiers, see "Restoring Archives," later in this topic. 92// 93// * 94// Specify details about the data serialization format of both the input object 95// that is being queried and the serialization of the CSV-encoded query 96// results. 97// 98// The following are additional important facts about the select 99// feature: 100// 101// * The output results are new Amazon S3 objects. Unlike archive 102// retrievals, they are stored until explicitly deleted-manually or through a 103// lifecycle policy. 104// 105// * You can issue more than one select request on the same 106// Amazon S3 object. Amazon S3 doesn't deduplicate requests, so avoid issuing 107// duplicate requests. 108// 109// * Amazon S3 accepts a select request even if the object has 110// already been restored. A select request doesn’t return error response 111// 409. 112// 113// Restoring objects Objects that you archive to the S3 Glacier or S3 Glacier 114// Deep Archive storage class, and S3 Intelligent-Tiering Archive or S3 115// Intelligent-Tiering Deep Archive tiers are not accessible in real time. For 116// objects in Archive Access or Deep Archive Access tiers you must first initiate a 117// restore request, and then wait until the object is moved into the Frequent 118// Access tier. For objects in S3 Glacier or S3 Glacier Deep Archive storage 119// classes you must first initiate a restore request, and then wait until a 120// temporary copy of the object is available. To access an archived object, you 121// must restore the object for the duration (number of days) that you specify. To 122// restore a specific object version, you can provide a version ID. If you don't 123// provide a version ID, Amazon S3 restores the current version. When restoring an 124// archived object (or using a select request), you can specify one of the 125// following data access tier options in the Tier element of the request body: 126// 127// * 128// Expedited - Expedited retrievals allow you to quickly access your data stored in 129// the S3 Glacier storage class or S3 Intelligent-Tiering Archive tier when 130// occasional urgent requests for a subset of archives are required. For all but 131// the largest archived objects (250 MB+), data accessed using Expedited retrievals 132// is typically made available within 1–5 minutes. Provisioned capacity ensures 133// that retrieval capacity for Expedited retrievals is available when you need it. 134// Expedited retrievals and provisioned capacity are not available for objects 135// stored in the S3 Glacier Deep Archive storage class or S3 Intelligent-Tiering 136// Deep Archive tier. 137// 138// * Standard - Standard retrievals allow you to access any of 139// your archived objects within several hours. This is the default option for 140// retrieval requests that do not specify the retrieval option. Standard retrievals 141// typically finish within 3–5 hours for objects stored in the S3 Glacier storage 142// class or S3 Intelligent-Tiering Archive tier. They typically finish within 12 143// hours for objects stored in the S3 Glacier Deep Archive storage class or S3 144// Intelligent-Tiering Deep Archive tier. Standard retrievals are free for objects 145// stored in S3 Intelligent-Tiering. 146// 147// * Bulk - Bulk retrievals are the lowest-cost 148// retrieval option in S3 Glacier, enabling you to retrieve large amounts, even 149// petabytes, of data inexpensively. Bulk retrievals typically finish within 5–12 150// hours for objects stored in the S3 Glacier storage class or S3 151// Intelligent-Tiering Archive tier. They typically finish within 48 hours for 152// objects stored in the S3 Glacier Deep Archive storage class or S3 153// Intelligent-Tiering Deep Archive tier. Bulk retrievals are free for objects 154// stored in S3 Intelligent-Tiering. 155// 156// For more information about archive retrieval 157// options and provisioned capacity for Expedited data access, see Restoring 158// Archived Objects 159// (https://docs.aws.amazon.com/AmazonS3/latest/dev/restoring-objects.html) in the 160// Amazon S3 User Guide. You can use Amazon S3 restore speed upgrade to change the 161// restore speed to a faster speed while it is in progress. For more information, 162// see Upgrading the speed of an in-progress restore 163// (https://docs.aws.amazon.com/AmazonS3/latest/dev/restoring-objects.html#restoring-objects-upgrade-tier.title.html) 164// in the Amazon S3 User Guide. To get the status of object restoration, you can 165// send a HEAD request. Operations return the x-amz-restore header, which provides 166// information about the restoration status, in the response. You can use Amazon S3 167// event notifications to notify you when a restore is initiated or completed. For 168// more information, see Configuring Amazon S3 Event Notifications 169// (https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html) in the 170// Amazon S3 User Guide. After restoring an archived object, you can update the 171// restoration period by reissuing the request with a new period. Amazon S3 updates 172// the restoration period relative to the current time and charges only for the 173// request-there are no data transfer charges. You cannot update the restoration 174// period when Amazon S3 is actively processing your current restore request for 175// the object. If your bucket has a lifecycle configuration with a rule that 176// includes an expiration action, the object expiration overrides the life span 177// that you specify in a restore request. For example, if you restore an object 178// copy for 10 days, but the object is scheduled to expire in 3 days, Amazon S3 179// deletes the object in 3 days. For more information about lifecycle 180// configuration, see PutBucketLifecycleConfiguration 181// (https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketLifecycleConfiguration.html) 182// and Object Lifecycle Management 183// (https://docs.aws.amazon.com/AmazonS3/latest/dev/object-lifecycle-mgmt.html) in 184// Amazon S3 User Guide. Responses A successful action returns either the 200 OK or 185// 202 Accepted status code. 186// 187// * If the object is not previously restored, then 188// Amazon S3 returns 202 Accepted in the response. 189// 190// * If the object is previously 191// restored, Amazon S3 returns 200 OK in the response. 192// 193// Special Errors 194// 195// * Code: 196// RestoreAlreadyInProgress 197// 198// * Cause: Object restore is already in progress. (This 199// error does not apply to SELECT type requests.) 200// 201// * HTTP Status Code: 409 202// Conflict 203// 204// * SOAP Fault Code Prefix: Client 205// 206// * Code: 207// GlacierExpeditedRetrievalNotAvailable 208// 209// * Cause: expedited retrievals are 210// currently not available. Try again later. (Returned if there is insufficient 211// capacity to process the Expedited request. This error applies only to Expedited 212// retrievals and not to S3 Standard or Bulk retrievals.) 213// 214// * HTTP Status Code: 215// 503 216// 217// * SOAP Fault Code Prefix: N/A 218// 219// Related Resources 220// 221// * 222// PutBucketLifecycleConfiguration 223// (https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketLifecycleConfiguration.html) 224// 225// * 226// GetBucketNotificationConfiguration 227// (https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketNotificationConfiguration.html) 228// 229// * 230// SQL Reference for Amazon S3 Select and S3 Glacier Select 231// (https://docs.aws.amazon.com/AmazonS3/latest/dev/s3-glacier-select-sql-reference.html) 232// in the Amazon S3 User Guide 233func (c *Client) RestoreObject(ctx context.Context, params *RestoreObjectInput, optFns ...func(*Options)) (*RestoreObjectOutput, error) { 234 if params == nil { 235 params = &RestoreObjectInput{} 236 } 237 238 result, metadata, err := c.invokeOperation(ctx, "RestoreObject", params, optFns, addOperationRestoreObjectMiddlewares) 239 if err != nil { 240 return nil, err 241 } 242 243 out := result.(*RestoreObjectOutput) 244 out.ResultMetadata = metadata 245 return out, nil 246} 247 248type RestoreObjectInput struct { 249 250 // The bucket name containing the object to restore. When using this action with an 251 // access point, you must direct requests to the access point hostname. The access 252 // point hostname takes the form 253 // AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. When using this 254 // action with an access point through the AWS SDKs, you provide the access point 255 // ARN in place of the bucket name. For more information about access point ARNs, 256 // see Using Access Points 257 // (https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-access-points.html) 258 // in the Amazon S3 User Guide. When using this action with Amazon S3 on Outposts, 259 // you must direct requests to the S3 on Outposts hostname. The S3 on Outposts 260 // hostname takes the form 261 // AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When using 262 // this action using S3 on Outposts through the AWS SDKs, you provide the Outposts 263 // bucket ARN in place of the bucket name. For more information about S3 on 264 // Outposts ARNs, see Using S3 on Outposts 265 // (https://docs.aws.amazon.com/AmazonS3/latest/userguide/S3onOutposts.html) in the 266 // Amazon S3 User Guide. 267 // 268 // This member is required. 269 Bucket *string 270 271 // Object key for which the action was initiated. 272 // 273 // This member is required. 274 Key *string 275 276 // The account ID of the expected bucket owner. If the bucket is owned by a 277 // different account, the request will fail with an HTTP 403 (Access Denied) error. 278 ExpectedBucketOwner *string 279 280 // Confirms that the requester knows that they will be charged for the request. 281 // Bucket owners need not specify this parameter in their requests. For information 282 // about downloading objects from requester pays buckets, see Downloading Objects 283 // in Requestor Pays Buckets 284 // (https://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html) 285 // in the Amazon S3 Developer Guide. 286 RequestPayer types.RequestPayer 287 288 // Container for restore job parameters. 289 RestoreRequest *types.RestoreRequest 290 291 // VersionId used to reference a specific version of the object. 292 VersionId *string 293} 294 295type RestoreObjectOutput struct { 296 297 // If present, indicates that the requester was successfully charged for the 298 // request. 299 RequestCharged types.RequestCharged 300 301 // Indicates the path in the provided S3 output location where Select results will 302 // be restored to. 303 RestoreOutputPath *string 304 305 // Metadata pertaining to the operation's result. 306 ResultMetadata middleware.Metadata 307} 308 309func addOperationRestoreObjectMiddlewares(stack *middleware.Stack, options Options) (err error) { 310 err = stack.Serialize.Add(&awsRestxml_serializeOpRestoreObject{}, middleware.After) 311 if err != nil { 312 return err 313 } 314 err = stack.Deserialize.Add(&awsRestxml_deserializeOpRestoreObject{}, middleware.After) 315 if err != nil { 316 return err 317 } 318 if err = addSetLoggerMiddleware(stack, options); err != nil { 319 return err 320 } 321 if err = awsmiddleware.AddClientRequestIDMiddleware(stack); err != nil { 322 return err 323 } 324 if err = smithyhttp.AddComputeContentLengthMiddleware(stack); err != nil { 325 return err 326 } 327 if err = addResolveEndpointMiddleware(stack, options); err != nil { 328 return err 329 } 330 if err = v4.AddComputePayloadSHA256Middleware(stack); err != nil { 331 return err 332 } 333 if err = addRetryMiddlewares(stack, options); err != nil { 334 return err 335 } 336 if err = addHTTPSignerV4Middleware(stack, options); err != nil { 337 return err 338 } 339 if err = awsmiddleware.AddRawResponseToMetadata(stack); err != nil { 340 return err 341 } 342 if err = awsmiddleware.AddRecordResponseTiming(stack); err != nil { 343 return err 344 } 345 if err = addClientUserAgent(stack); err != nil { 346 return err 347 } 348 if err = smithyhttp.AddErrorCloseResponseBodyMiddleware(stack); err != nil { 349 return err 350 } 351 if err = smithyhttp.AddCloseResponseBodyMiddleware(stack); err != nil { 352 return err 353 } 354 if err = addOpRestoreObjectValidationMiddleware(stack); err != nil { 355 return err 356 } 357 if err = stack.Initialize.Add(newServiceMetadataMiddleware_opRestoreObject(options.Region), middleware.Before); err != nil { 358 return err 359 } 360 if err = addMetadataRetrieverMiddleware(stack); err != nil { 361 return err 362 } 363 if err = addRestoreObjectUpdateEndpoint(stack, options); err != nil { 364 return err 365 } 366 if err = addResponseErrorMiddleware(stack); err != nil { 367 return err 368 } 369 if err = v4.AddContentSHA256HeaderMiddleware(stack); err != nil { 370 return err 371 } 372 if err = disableAcceptEncodingGzip(stack); err != nil { 373 return err 374 } 375 if err = addRequestResponseLogging(stack, options); err != nil { 376 return err 377 } 378 return nil 379} 380 381func newServiceMetadataMiddleware_opRestoreObject(region string) *awsmiddleware.RegisterServiceMetadata { 382 return &awsmiddleware.RegisterServiceMetadata{ 383 Region: region, 384 ServiceID: ServiceID, 385 SigningName: "s3", 386 OperationName: "RestoreObject", 387 } 388} 389 390// getRestoreObjectBucketMember returns a pointer to string denoting a provided 391// bucket member valueand a boolean indicating if the input has a modeled bucket 392// name, 393func getRestoreObjectBucketMember(input interface{}) (*string, bool) { 394 in := input.(*RestoreObjectInput) 395 if in.Bucket == nil { 396 return nil, false 397 } 398 return in.Bucket, true 399} 400func addRestoreObjectUpdateEndpoint(stack *middleware.Stack, options Options) error { 401 return s3cust.UpdateEndpoint(stack, s3cust.UpdateEndpointOptions{ 402 Accessor: s3cust.UpdateEndpointParameterAccessor{ 403 GetBucketFromInput: getRestoreObjectBucketMember, 404 }, 405 UsePathStyle: options.UsePathStyle, 406 UseAccelerate: options.UseAccelerate, 407 SupportsAccelerate: true, 408 TargetS3ObjectLambda: false, 409 EndpointResolver: options.EndpointResolver, 410 EndpointResolverOptions: options.EndpointOptions, 411 UseDualstack: options.UseDualstack, 412 UseARNRegion: options.UseARNRegion, 413 }) 414} 415