Set bucket metadata
To change a bucket's metadata, you make aPUT request that is scoped to abucket, and you use the appropriate query string parameter along with an XMLdocument in the request body that defines the metadata you want to change. Whenusing the XML API, each request can only change one part of a bucket's metadata.
You must haveFULL_CONTROL permission to send requests that modify bucketmetadata. Also, you must be authenticated to use thePUT Bucket method.
Query string parameters
Exactly one of the following query parameters should be included as part ofthe request to change the bucket's metadata.
| Parameter | Description | Required |
|---|---|---|
billing | Enable or disable theRequester Pays feature for a bucket. | No |
cors | Add, change, or remove theCORS configuration for a bucket. | No |
encryptionConfig | Add, change, or remove the defaultcustomer-managed encryption key for a bucket. | No |
lifecycle | Add, change, or remove thelifecycle configuration for a bucket. | No |
logging | Add, change, or remove thelogging configuration for a bucket. | No |
storageClass | Change the defaultstorage class for a bucket. Changing a bucket's default storage class doesn't affect the storage class of objects that already exist in the bucket. | No |
tagging | Add, change, or remove thelabels for a bucket. | No |
versioning | Enable or disableObject Versioning for a bucket. | No |
websiteConfig | Add, change, or remove thewebsite configuration for a bucket. | No |
Seesigned URL query string parameters for information on the parametersyou include when creating and usingsigned URLs.
Request headers
Request body elements
You should structure the request body based on thequery parameter you usein the request. The contents included in the request body replace any existingsettings or configurations for the specified metadata.
?billing
The following request body elements are applicable only if you use thebillingquery string parameter toenable or disable Requester Pays for an existingbucket.
| Element | Description |
|---|---|
BillingConfiguration | The container forRequesterPays. |
RequesterPays | The status to apply to the Requester Pays feature. Accepted values areEnabled andDisabled. |
?cors
The following request body elements are applicable only if you use thecors query string parameter tospecify CORS for an existing bucket.
| Element | Description |
|---|---|
CorsConfig | Container for one or moreCors configuration containers. If you specify multipleCors containers, the configurations are evaluated in the order listed within theCorsConfig container, with the firstCors container that has a configuration matching the Origin and Method of a request used to determine any CORS response headers to add to the response. |
Cors | Container for aCORS configuration to be applied to the bucket. You can specify multiple Origins and multiple Methods in eachCors container. There will be a match if the request Origin matches any of theOrigins in theCors container and the request Method matches any of theMethods in theCors container. |
Origins | Container for one or moreOrigin elements, specifying the origins permitted for cross origin resource sharing with this Cloud Storage bucket. |
Origin | An Origin permitted for cross origin resource sharing with this Cloud Storage bucket. For example,https://origin1.example.com. If you supply a value that consists of only the wildcard (<Origin>*</Origin>), this gives access to ALL origins. |
Methods | Container for one or moreMethod elements, specifying the HTTP methods permitted in cross origin resource sharing with this Cloud Storage bucket. |
Method | An HTTP method used in this configuration. Valid values areDELETE,GET,HEAD,POST, andPUT.OPTIONS is interpreted as a preflight request, so you don't need to specify this method in your CORS configuration. |
ResponseHeaders | Optional container for one or moreResponseHeader elements. |
ResponseHeader | Specifies a response header that the user agent is permitted to share across origins. |
MaxAgeSec | This value is used to respond to preflight requests, indicating the number of seconds that the client (browser) is allowed to make requests before the client must repeat the preflight request. (Indicates cache expiry time.) Preflight requests are required if the request method containsnon-simple headers or if the request method is notPOST,GET, orHEAD. The value is returned in theAccess-Control-Max-Age header in responses to preflight requests. |
?encryptionConfig
The following request body elements are applicable only if you use theencryptionConfig query string parameter toset or remove the default customer-managed encryption key used for anexisting bucket.
| Element | Description |
|---|---|
EncryptionConfiguration | The container forDefaultKmsKeyName. If this element is empty, the existing default customer-managed encryption key (if any) is removed. |
DefaultKmsKeyName | The name of the Cloud Key Management Service key resource to use by default for objects added to the bucket. |
?lifecycle
The following request body elements are applicable only if you use thelifecycle query string parameter toset or remove the lifecycle configuration for an existing bucket.
| Element | Description |
|---|---|
LifecycleConfiguration | Defines the lifecycle management policies for the bucket, which contains 0 or more (up to 100) rules. Use an empty element (for example,<LifecycleConfiguration/>) to disable lifecycle management for the bucket. |
Rule | Defines a lifecycle management rule, which is made of an action and the conditions that must be met for the action to occur. |
Action | Defines the action to occur. Must contain one and only one action element. |
AbortIncompleteMultipartUpload | Action element to abort incompletemultipart uploads and delete the parts associated with them. Only supports the following conditions:Age,MatchesPrefix, andMatchesSuffix. |
Delete | Action element to delete objects in the bucket. |
SetStorageClass | Action element to change thestorage class of objects in the bucket. |
Condition | Conditions that must be met for the action to occur. A rule must contain at least one condition element. |
Age | Condition element that matches objects over the specified age (in days). |
CreatedBefore | Condition element that matches objects created before midnight of the specified date in UTC. The value is an ISO date string without a timezone, for example2019-01-15. |
CustomTimeBefore | Condition element that matches objects whoseCustom-Time metadata contains a date that's older than the date set by this condition.CustomTimeBefore is an ISO date string without a time zone, for example2020-02-25. |
DaysSinceCustomTime | Condition element that matches objects whoseCustom-Time metadata is more thanDaysSinceCustomTime days old. |
DaysSinceNoncurrentTime | Condition element relevant only for versioned objects. Matches objects that have been noncurrent for more than the specified number of days. |
IsLive | Condition element typically only used in conjunction withobject versioning. When set tofalse, this condition is satisfied for any noncurrent version of an object. When set totrue, this condition is satisfied for the live version of an object. If you don't use object versioning, all your objects are considered live and match whenIsLive istrue. |
MatchesPrefix | Condition element that matches objects whose names begin with the specified prefix. The prefix must meetobject naming requirements. This condition can be added multiple times to the same rule in order to match more than one prefix. |
MatchesStorageClass | Condition element that matches objects of the specifiedstorage class. This condition can be added multiple times to the same rule in order to cover more than one storage class. |
MatchesSuffix | Condition element that matches objects whose names end with the specified suffix. The suffix must meetobject naming requirements. This condition can be added multiple times to the same rule in order to match more than one suffix. |
NoncurrentTimeBefore | Condition element relevant only for versioned objects. Matches objects that becamenoncurrent on a date prior to the date specified in this condition.NoncurrentTimeBefore is an ISO date string without a time zone, for example2020-02-25. |
NumberOfNewerVersions | Condition element relevant only for versioned objects. If the value is N, the condition is satisfied when there are at least N versions (including the live version) newer than this version of the object. |
?logging
The following request body elements are applicable only if you use thelogging query string parameter tospecify the logging configuration for an existing bucket.
| Element | Description |
|---|---|
Logging | Container for a logging configuration. Use an empty element (for example,<Logging/>) to disable logging for the bucket. |
LogBucket | The bucket that will receive log objects. Must be avalid bucket name. Required. |
LogObjectPrefix | The object prefix for log objects. It can be at most 900 characters and must be avalid object name. Optional. |
?storageClass
The following request body element is applicable only if you use thestorageClass query string parameter tospecify the storage class for an existing bucket.
| Element | Description |
|---|---|
StorageClass | Defines the default storage class for the bucket. |
?tagging
The following request body elements are applicable only if you use thetaggingquery string parameter toset the labels for an existing bucket.
| Element | Description |
|---|---|
Tagging | The container forTagSet. |
TagSet | The container for all labels that are applied to the bucket. |
Tag | A container for an individual label. A label is composed of akey:value pair. |
Key | The key for a label. |
Value | The value for a label. |
?versioning
The following request body elements are applicable only if you use theversioning query string parameter toenable or disable Object Versioning for an existing bucket.
| Element | Description |
|---|---|
VersioningConfiguration | Container for versioning configuration. |
Status | Status of versioning for this bucket. Can be eitherEnabled orSuspended. |
?websiteConfig
The following request body elements are applicable only if you use thewebsiteConfig query string parameter to specify a website configuration foran existing bucket.
A bucket's website configuration only applies to requests that use aCNAME orA redirect. For more information on using a bucket to host astatic website, including other options for setting your website configuration,seeHosting a Static Website.
| Element | Description |
|---|---|
WebsiteConfiguration | Container for website configuration. |
MainPageSuffix | An object name suffix to simulate directory index behavior. Must be avalid object name. Optional. |
NotFoundPage | Name of the object to return with 404 responses. Must be avalid object name. Optional. |
Request syntax
The following syntax applies to PUT Bucket requests that change the metadatafor a bucket.
PUT /?METADATA_QUERY_PARAMETER HTTP/1.1Host:BUCKET_NAME.storage.googleapis.comDate:DATE_AND_TIME_OF_REQUESTContent-Length:REQUEST_BODY_LENGTHContent-Type:MIME_TYPE_OF_REQUEST_BODYAuthorization:AUTHENTICATION_STRINGXML_DOCUMENT_DEFINING_BUCKET_METADATA
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 sets a CORS configuration on a bucket namedacme-pets.This CORS configuration sets two origins and the HTTP methods allowed for thoseorigins. In this example, all of the available HTTP methods are allowed.
Request
PUT /?cors HTTP/1.1Host: acme-pets.storage.googleapis.comDate: Thu, 12 Mar 2022 03:38:42 GMTContent-Length: 1320Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg<?xml version="1.0" encoding="UTF-8"?><CorsConfig> <Cors> <Origins> <Origin>http://origin1.example.com</Origin> <Origin>http://origin2.example.com</Origin> </Origins> <Methods> <Method>GET</Method> <Method>HEAD</Method> <Method>PUT</Method> <Method>POST</Method> <Method>DELETE</Method> </Methods> <ResponseHeaders> <ResponseHeader>x-goog-meta-foo1</ResponseHeader> <ResponseHeader>x-goog-meta-foo2</ResponseHeader> </ResponseHeaders> <MaxAgeSec>1800</MaxAgeSec> </Cors></CorsConfig>
Response
HTTP/1.1 200 OKDate: Thu, 12 Mar 2012 03:38:42 GMTExpires: Mon, 01 Jan 1990 00:00:00 GMTCache-Control: no-cache, no-store, must-revalidateContent-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 2026-02-19 UTC.