Set object retention
To add or modify theretention configuration for an existing object, youmake a PUT request that is scoped to the object, and you use theretentionquery string parameter. You must also include an XML document in the requestbody that contains the retention configuration that you want to apply. Aretention configuration cannot be removed or shortened if its mode is set toCOMPLIANCE.
You can also specify a retention configuration at the time you upload an object.
You must haveFULL_CONTROL permission to apply a retention configuration to anexisting 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 |
Seesigned URL query string parameters for information on the parametersyou include when creating and usingsigned URLs.
Request headers
In addition tocommon request headers, the following can be used.
| Header | Description | Required |
|---|---|---|
x-goog-bypass-governance-retention | Must be set totrue in order to remove an existing retention configuration, make an existing retention configuration shorter, or set the mode of an existing retention configuration toCOMPLIANCE. | No |
Request body elements
The following request body elements are applicable only if you use theretention query string parameter to add or modify a retention configurationfor 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, andCOMPLIANCE corresponds to locked mode. |
RetainUntilDate | A date and time represented inRFC 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 theretentionquery string parameter and that scope the request to a specific objectgeneration.
PUT /OBJECT_NAME?retention&generation=GENERATION_NUMBER HTTP/1.1Host:BUCKET_NAME.storage.googleapis.comDate:DATEContent-Length:REQUEST_BODY_LENGTHContent-Type:MIME_TYPEAuthorization:AUTHENTICATION_STRINGXML_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 thelondon.jpgobject, which is stored in thetravel-maps bucket. The configuration sets theMode to beGOVERNANCE and theRetainUntilDate to be2028-02-15T05:30:00Z.
Request
PUT /london.jpg?retention HTTP/1.1Host: travel-maps.storage.googleapis.comDate: Mon, 16 Oct 2023 17:08:44 GMTContent-Length: 138Content-Type=application/xml; charset=UTF-8Authorization: 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 OKDate: Mon, 16 Oct 2023 17:08:45 GMTContent-Length: 0Content-Type: text/html
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-17 UTC.