Set bucket metadata

To change a bucket's metadata, you make a PUT request that is scoped to a bucket, and you use the appropriate query string parameter along with an XML document in the request body that defines the metadata you want to change. When using the XML API, each request can only change one part of a bucket's metadata.

You must have FULL_CONTROL permission to send requests that modify bucket metadata. Also, you must be authenticated to use the PUT Bucket method.

Query string parameters

Exactly one of the following query parameters should be included as part of the request to change the bucket's metadata.

Parameter	Description	Required
`billing`	Enable or disable the Requester Pays feature for a bucket.	No
`cors`	Add, change, or remove the CORS configuration for a bucket.	No
`encryptionConfig`	Add, change, or remove the default customer-managed encryption key for a bucket.	No
`lifecycle`	Add, change, or remove the lifecycle configuration for a bucket.	No
`logging`	Add, change, or remove the logging configuration for a bucket.	No
`storageClass`	Change the default storage 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 the labels for a bucket.	No
`versioning`	Enable or disable Object Versioning for a bucket.	No
`websiteConfig`	Add, change, or remove the website configuration for a bucket.	No

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

Request headers

See common request headers.

Request body elements

You should structure the request body based on the query parameter you use in the request. The contents included in the request body replace any existing settings or configurations for the specified metadata.

`?billing`

The following request body elements are applicable only if you use the billing query string parameter to enable or disable Requester Pays for an existing bucket.

Element	Description
`BillingConfiguration`	The container for `RequesterPays`.
`RequesterPays`	The status to apply to the Requester Pays feature. Accepted values are `Enabled` and `Disabled`.

`?cors`

The following request body elements are applicable only if you use the cors query string parameter to specify CORS for an existing bucket.

Element	Description
`CorsConfig`	Container for one or more `Cors` configuration containers. If you specify multiple `Cors` containers, the configurations are evaluated in the order listed within the `CorsConfig` container, with the first `Cors` 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 a `CORS` configuration to be applied to the bucket. You can specify multiple Origins and multiple Methods in each `Cors` container. There will be a match if the request Origin matches any of the `Origins` in the `Cors` container and the request Method matches any of the `Methods` in the `Cors` container.
`Origins`	Container for one or more `Origin` 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 more `Method` 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 are `DELETE`, `GET`, `HEAD`, `POST`, and `PUT`. `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 more `ResponseHeader` 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 contains non-simple headers or if the request method is not `POST`, `GET`, or `HEAD`. The value is returned in the `Access-Control-Max-Age` header in responses to preflight requests.

`?encryptionConfig`

The following request body elements are applicable only if you use the encryptionConfig query string parameter to set or remove the default customer-managed encryption key used for an existing bucket.

Element	Description
`EncryptionConfiguration`	The container for `DefaultKmsKeyName`. 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 the lifecycle query string parameter to set 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 incomplete multipart uploads and delete the parts associated with them. Only supports the following conditions: `Age`, `MatchesPrefix`, and `MatchesSuffix`.
`Delete`	Action element to delete objects in the bucket.
`SetStorageClass`	Action element to change the storage 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 example `2019-01-15`.
`CustomTimeBefore`	Condition element that matches objects whose `Custom-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 example `2020-02-25`.
`DaysSinceCustomTime`	Condition element that matches objects whose `Custom-Time` metadata is more than `DaysSinceCustomTime` 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 with object versioning. When set to `false`, this condition is satisfied for any noncurrent version of an object. When set to `true`, 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 when `IsLive` is `true`.
`MatchesPrefix`	Condition element that matches objects whose names begin with the specified prefix. The prefix must meet object 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 specified storage 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 meet object 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 became noncurrent on a date prior to the date specified in this condition. `NoncurrentTimeBefore` is an ISO date string without a time zone, for example `2020-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 the logging query string parameter to specify 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 a valid bucket name. Required.
`LogObjectPrefix`	The object prefix for log objects. It can be at most 900 characters and must be a valid object name. Optional.

`?storageClass`

The following request body element is applicable only if you use the storageClass query string parameter to specify 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 the tagging query string parameter to set the labels for an existing bucket.

Element	Description
`Tagging`	The container for `TagSet`.
`TagSet`	The container for all labels that are applied to the bucket.
`Tag`	A container for an individual label. A label is composed of a `key: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 the versioning query string parameter to enable or disable Object Versioning for an existing bucket.

Element	Description
`VersioningConfiguration`	Container for versioning configuration.
`Status`	Status of versioning for this bucket. Can be either `Enabled` or `Suspended`.

`?websiteConfig`

The following request body elements are applicable only if you use the websiteConfig query string parameter to specify a website configuration for an existing bucket.

A bucket's website configuration only applies to requests that use a CNAME or A redirect. For more information on using a bucket to host a static website, including other options for setting your website configuration, see Hosting a Static Website.

Element	Description
`WebsiteConfiguration`	Container for website configuration.
`MainPageSuffix`	An object name suffix to simulate directory index behavior. Must be a valid object name. Optional.
`NotFoundPage`	Name of the object to return with 404 responses. Must be a valid object name. Optional.

Request syntax

The following syntax applies to PUT Bucket requests that change the metadata for a bucket.

PUT /?METADATA_QUERY_PARAMETER HTTP/1.1
Host: BUCKET_NAME.storage.googleapis.com
Date: DATE_AND_TIME_OF_REQUEST
Content-Length: REQUEST_BODY_LENGTH
Content-Type: MIME_TYPE_OF_REQUEST_BODY
Authorization: AUTHENTICATION_STRING

XML_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 named acme-pets. This CORS configuration sets two origins and the HTTP methods allowed for those origins. In this example, all of the available HTTP methods are allowed.

Request

PUT /?cors HTTP/1.1
Host: acme-pets.storage.googleapis.com
Date: Thu, 12 Mar 2022 03:38:42 GMT
Content-Length: 1320
Authorization: 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 OK
Date: Thu, 12 Mar 2012 03:38:42 GMT
Expires: Mon, 01 Jan 1990 00:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 0
Content-Type: text/html