Set object retention

To add or modify the retention configuration for an existing object, you make a PUT request that is scoped to the object, and you use the retention query string parameter. You must also include an XML document in the request body that contains the retention configuration that you want to apply. A retention configuration cannot be removed or shortened if its mode is set to COMPLIANCE.

You can also specify a retention configuration at the time you upload an object.

You must have FULL_CONTROL permission to apply a retention configuration to an existing object.

Query string parameters

Parameter	Description	Required
retention	Scopes the request to add or modify the retention configuration for an object. You must specify the retention configuration in an XML document in the request body.	No
generation	Specifies the generation on which to set the retention configuration.	No

See signed URL query string parameters for information on the parameters you include when creating and using signed URLs.

Request headers

In addition to common request headers, the following can be used.

Header	Description	Required
x-goog-bypass-governance-retention	Must be set to true in order to remove an existing retention configuration, make an existing retention configuration shorter, or set the mode of an existing retention configuration to COMPLIANCE.	No

Request body elements

The following request body elements are applicable only if you use the retention query string parameter to add or modify a retention configuration for an existing object. All elements are required.

Element	Description
Retention	Container for object's retention configuration.
Mode	Mode of the object retention configuration. GOVERNANCE corresponds to unlocked mode, and COMPLIANCE corresponds to locked mode.
RetainUntilDate	A date and time represented in RFC 3339 UTC format that determines the time until which the object is retained as immutable.

Request syntax

The following syntax applies to PUT Object requests that use the retention query string parameter and that scope the request to a specific object generation.

PUT /OBJECT_NAME?retention&generation=GENERATION_NUMBER HTTP/1.1
Host: BUCKET_NAME.storage.googleapis.com
Date: DATE
Content-Length: REQUEST_BODY_LENGTH
Content-Type: MIME_TYPE
Authorization: AUTHENTICATION_STRING

XML_DOCUMENT_DEFINING_RETENTION_CONFIGURATION

Response headers

The request can return a variety of response headers depending on the request headers you use.

Response body elements

The response does not include an XML document in the response body.

Example

The following sample applies a retention configuration to the london.jpg object, which is stored in the travel-maps bucket. The configuration sets the Mode to be GOVERNANCE and the RetainUntilDate to be 2028-02-15T05:30:00Z.

Request

PUT /london.jpg?retention HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Mon, 16 Oct 2023 17:08:44 GMT
Content-Length: 138
Content-Type=application/xml; charset=UTF-8
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

<?xml version="1.0" encoding="UTF-8"?>
<Retention>
  <Mode>
    GOVERNANCE
  </Mode>
  <RetainUntilDate>
    2028-02-15T05:30:00Z
  </RetainUntilDate>
</Retention>

Response

HTTP/1.1 200 OK
Date: Mon, 16 Oct 2023 17:08:45 GMT
Content-Length: 0
Content-Type: text/html