Updates the metadata of an object.
Request
HTTP request
PUT https://storage.googleapis.com/storage/v1/b/ bucket /o/ object
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 object resides.
object
string
Name of the object. For information about how to URL encode object names to be path safe,
see Encoding URI path parts
.
Optional query parameters
generation
long
If present, selects a specific revision of this object (as opposed to the latest version,
the default).
ifGenerationMatch
long
Makes the operation conditional on whether the object's current generation matches the
given value. Setting to 0 makes the operation succeed only if there are no live versions
of the object.
ifGenerationNotMatch
long
Makes the operation conditional on whether the object's current generation does not match
the given value. If no live object exists, the precondition fails. Setting to 0 makes the
operation succeed only if there is a live version of the object.
ifMetagenerationMatch
long
Makes the operation conditional on whether the object's current metageneration matches
the given value.
ifMetagenerationNotMatch
long
Makes the operation conditional on whether the object's current metageneration does not
match the given value.
overrideUnlockedRetention
boolean
Applicable for object's that have an unlocked retention configuration
: Required to be set to
true
if the operation includes a retention
property that changes
the mode
to Locked
, reduces the retainUntilTime
,
or removes the retention configuration from the object.predefinedAcl
string
Apply a predefined set of access controls to this object.
Acceptable values are:
Acceptable values are:
-
authenticatedRead: Object owner getsOWNERaccess, andallAuthenticatedUsersgetREADERaccess. -
bucketOwnerFullControl: Object owner getsOWNERaccess, and project team owners getOWNERaccess. -
bucketOwnerRead: Object owner getsOWNERaccess, and project team owners getREADERaccess. -
private: Object owner getsOWNERaccess. -
projectPrivate: Object owner getsOWNERaccess, and project team members get access according to their roles. -
publicRead: Object owner getsOWNERaccess, andallUsersgetREADERaccess.
iamConfiguration.uniformBucketLevelAccess.enabled
is set to true
, requests that include this parameter fail with a 400 Bad Request
response.projection
string
Set of properties to return. Defaults to
Acceptable values are:
full
.Acceptable values are:
-
full: Include all properties. -
noAcl: Omit theowner,aclproperty.
Optional extension headers
X-Goog-Encryption-Algorithm
string
The encryption algorithm to use, which must be
AES256
. Use this header if the
object is encrypted with a customer-supplied
encryption key
and you want the object's content hashes returned in the response.X-Goog-Encryption-Key
string
An RFC 4648
Base64-encoded string of your AES-256 encryption key. Use this header if the object is
encrypted with a customer-supplied
encryption key
and you want the object's content hashes returned in the response.
X-Goog-Encryption-Key-Sha256
string
An RFC 4648
Base64-encoded string of the SHA256 hash of your encryption key. Use this header if the
object is encrypted with a customer-supplied
encryption key
and you want the object's content hashes returned in the response.
Request body
In the request body, supply an object resource with any of the following optional properties:
| Property name | Value | Description | Notes |
|---|---|---|---|
acl[]
|
list
|
Access controls on the object. If empty, this parameter is ignored. Can contain one or more objectAccessControls Resources . |
writable |
cacheControl
|
string
|
Cache-Control
directive for the object data. If omitted, and the object is accessible to all anonymous
users, the default will be "public, max-age=3600"
. |
writable |
contentDisposition
|
string
|
Content-Disposition of the object data. | writable |
contentEncoding
|
string
|
Content-Encoding of the object data. | writable |
contentLanguage
|
string
|
Content-Language of the object data. | writable |
contentType
|
string
|
Content-Type of the object data. If an object is stored without a Content-Type, it is served as application/octet-stream. | writable |
customTime
|
datetime
1
|
A user-specified timestamp for the object in RFC 3339
format. If the
object has customTime
metadata already set on it, any update request must
include a customTime
with an equal or later datetime. |
writable |
eventBasedHold
|
boolean
|
Whether or not the object is subject to an event-based hold . | writable |
metadata
|
object
|
User-provided metadata, in key/value pairs. | writable |
metadata.(key)
|
string
|
An individual metadata entry. | writable |
retention
|
object
|
The object's retention configuration , which defines the earliest datetime that the object can be deleted or replaced. | writable |
retention.mode
|
string
|
The mode of the retention configuration, which can be either Unlocked
or Locked
. If set to Locked
, retention.mode
cannot be
changed, the retention configuration cannot be removed, and retention.retainUntilTime
cannot be reduced. |
writable |
retention.retainUntilTime
|
datetime
1
|
The earliest time that the object can be deleted or replaced, in RFC 3339 format. This property has a maximum value of 3,155,760,000 seconds (100 years) from the current date and time. | writable |
temporaryHold
|
boolean
|
Whether or not the object is subject to a temporary hold . | writable |
Response
If successful, this method returns an object resource in the response body.
For 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.
