Objects: restore

Restores a soft-deleted object.

When a soft-deleted object is restored, a new copy of that object is created in the same bucket and inherits the same metadata as the soft-deleted object. The inherited metadata is the metadata that existed when the original object became soft deleted, with the following exceptions:

The createTime of the new object is set to the time at which the soft-deleted object was restored.
The softDeleteTime and hardDeleteTime values are cleared.
A new generation is assigned and the metageneration is reset to 1.
If the soft-deleted object was in a bucket that had Autoclass enabled, the new object is restored to Standard storage.

If a live object using the same name already exists in the bucket and becomes overwritten, the live object becomes a noncurrent object if Object Versioning is enabled on the bucket. If Object Versioning is not enabled, the live object becomes soft deleted.

Required permissions

The authenticated user must have the following IAM permissions to use this method:

storage.objects.restore
storage.objects.create
storage.objects.delete (only required if overwriting an existing object)
storage.objects.getIamPolicy (only required if projection is true and the relevant bucket has uniform bucket-level access disabled)
storage.objects.setIamPolicy (only required if copySourceAcl is true and the relevant bucket has uniform bucket-level access disabled)

To update object access control lists (ACLs), which only apply to objects stored in buckets with uniform bucket-level access disabled, the authenticated user must also have the storage.objects.setIamPolicy permission. To return ACLs as part of the response, the authenticated user must also have the storage.buckets.getIamPolicy permission.

Request

HTTP request

POST https://storage.googleapis.com/storage/v1/b/bucket/o/object/restore

In addition to standard query parameters, the following query parameters apply to this method.

To see an example of how to include query parameters in a request, see the JSON API Overview page.

Parameters

Parameter name	Value	Description
Path parameters
`bucket`	`string`	Name of the bucket in which the new object will be created. Must be the same bucket that contained the soft-deleted object being restored.
`object`	`string`	Name of the soft-deleted object to restore. For information about how to URL encode object names to be path safe, see Encoding URI path parts.
Required query parameters
`generation`	`long`	Specifies the version of the soft-deleted object to restore.
Optional query parameters
`copySourceAcl`	`boolean`	Applicable only for buckets the don't have uniform bucket-level access enabled. If `true`, copies the soft-deleted object's ACL and applies it to the restored object. If `false` or not specified, the restored object inherits the bucket's default object ACL.
`ifGenerationMatch`	`long`	Makes the operation conditional on there being a live version of the object with a generation number that matches the given value. Setting `ifGenerationMatch` to 0 makes the operation succeed only if there is no such live object.
`ifGenerationNotMatch`	`long`	Makes the operation conditional on there being a live version of the object with a generation number that does not match the given value. If no live object exists, the precondition fails. Setting `ifGenerationNotMatch` to 0 makes the operation succeed if there is a live version of the object.
`ifMetagenerationMatch`	`long`	Makes the operation conditional on there being a live version of the object with a metageneration number that matches the given value.
`ifMetagenerationNotMatch`	`long`	Makes the operation conditional on there being a live version of the object with a metageneration number that does not match the given value.
`projection`	`string`	Set of properties to return. Defaults to `noAcl`, unless the object resource specifies the `acl` property, when it defaults to `full`. Acceptable values are: `full`: Include all properties. `noAcl`: Omit the `owner`, `acl` property.
`restoreToken`	`string`	If you have enabled hierarchical namespace on your bucket and are working with soft-deleted objects, the `restoreToken`, a universally unique identifier (UUID), along with the object's `name` and `generation` value, uniquely identifies the object. The `restoreToken` is required to restore a soft-deleted object only if its `name` and `generation` value do not uniquely identify it. Otherwise, this parameter is optional. To learn how duplicate soft-deleted objects occur and how to uniquely identify them using `restoreToken`, see Restore and retrieve metadata of objects in buckets with hierarchical namespace enabled.

Request body

Do not supply a request body with this method.

Response

If successful, this method returns an object resource in the response body.

The following errors could occur:

If the specified bucket in the request does not have a soft delete policy, the request fails with a 400 Bad Request error with the reason SoftDeletePolicyRequired.
If the soft-deleted object's retention duration has passed, or the soft-deleted object no longer exists, the request fails with a 404 Not Found error with the reason notFound.
If the specified object in the request is not a soft-deleted object but is either live or noncurrent, the request fails with a 412 Failed Precondition error with the reason objectNotSoftDeleted.
If the specified object in the request belongs to a bucket that has a Bucket Lock retention policy, where the object's age is less than the retention duration, the request fails with a 403 Forbidden error with the reason retentionPolicyNotMet.

For more information about status and error codes returned by this API, see the reference page.

Try it!

Use the APIs Explorer below to call this method on live data and see the response.