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
.
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
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