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