To get a bucket's metadata, you make a GET
request that is scoped to a bucket,
and you use the appropriate query string parameter. The requested metadata is
returned in an XML document in the response body. When using the XML API, each
request can only return one part of a bucket's metadata.
You must have READ
permission to send requests that get bucket metadata. Also,
you must be authenticated to use the GET Bucket
method.
Query string parameters
Exactly one of the following query parameters should be included as part of the request to get the bucket's metadata.
| Parameter | Description | Required |
|---|---|---|
| Return the status of the Requester Pays feature for a bucket. | No | |
| Return the CORS configuration for a bucket. | No | |
| Applicable to buckets located in configurable dual-regions . Return the regions that constitute the configurable dual-region that a bucket is located within. | No | |
| Return the default customer-managed encryption key for a bucket. | No | |
| Return the lifecycle configuration for a bucket. | No | |
| Return the location of the bucket. Returned values can include a region, predefined dual-region, or multi-region name. For a list of possible locations, see bucket locations . | No | |
| Return the logging configuration for a bucket. | No | |
| Return the object retention configuration of a bucket. If object retention is not enabled for the requested bucket, the request fails with a 404 response. | No | |
| Return the default storage class for a bucket. | No | |
| Return the labels for a bucket. | No | |
| Return the status of Object Versioning for a bucket. | No | |
| Return 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
This request does not include an XML document in the request body.
Request syntax
The following syntax applies to GET Bucket requests that return the metadata for a bucket.
GET /? METADATA_QUERY_PARAMETER HTTP/1.1 Host: BUCKET_NAME .storage.googleapis.com Date: DATE_AND_TIME_OF_REQUEST Content-Length: 0 Authorization: AUTHENTICATION_STRING
Response headers
The request can return a variety of response headers depending on the request headers you use.
Response body elements
The contents of the response body depends on the query parameter you use in the request.
?billing
The following response body elements are applicable only if you use the billing
query string parameter to get the status of Requester Pays
for an
existing bucket.
| Element | Description |
|---|---|
BillingConfiguration
|
The container for RequesterPays
. |
RequesterPays
|
The status of the Requester Pays feature. The status is given as Enabled
or Disabled
. |
?cors
The following response body elements are applicable only if you use the cors
query string parameter to get the CORS configuration
for an
existing bucket.
| Element | Description |
|---|---|
CorsConfig
|
Container for one or more Cors
configuration 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 that is applied to the
bucket. There might be multiple Origins and multiple Methods in each 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. An origin that consists of only the
wildcard ( <Origin>*</Origin>
) 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. |
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. |
?customPlacementConfig
The following response body elements are applicable only if you use the customPlacementConfig
query string parameter to return the regions that
constitute the configurable dual-region
that a bucket is located within.
If the request applies to a bucket located in a region, multi-region, or
predefined dual-region, the response contains an empty DataLocations
element.
| Element | Description |
|---|---|
CustomPlacementConfig
|
The container for DataLocations
|
DataLocations
|
The container for a list of regions that constitute the configurable dual-region . |
DataLocation
|
One of the regions that constitute the configurable dual-region . |
?encryptionConfig
The following response body elements are applicable only if you use the encryptionConfig
query string parameter to get the default customer-managed encryption key
used for an existing
bucket.
| Element | Description |
|---|---|
EncryptionConfiguration
|
The container for DefaultKmsKeyName
. If this element is
empty, the bucket does not have a default key set for it. |
DefaultKmsKeyName
|
The name of the Cloud Key Management Service key resource used by default for objects added to the bucket. |
?lifecycle
The following response body elements are applicable only if you use the lifecycle
query string parameter to get the lifecycle configuration
for an existing bucket.
| Element | Description |
|---|---|
LifecycleConfiguration
|
Container for one or more Rule
elements, which define the
object lifecycle management configuration for the bucket. If this element
is empty, the bucket does not have an object lifecycle management
configuration set for it. |
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. Every Rule
has exactly one
and action element. |
AbortIncompleteMultipartUpload
|
Action element to abort incomplete multipart uploads and delete the parts associated with them. |
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. Every Rule
contains 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 . |
MatchesStorageClass
|
Condition element that matches objects of the specified storage class . |
MatchesSuffix
|
Condition element that matches objects whose names end with the specified 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. |
?location
The following response body element is applicable only if you use the location
query string parameter to get the location
for an existing bucket. Note
that for configurable dual-regions, additional location information can be
obtained by making a request for the bucket's custom placement configuration,
using the customPlacementConfig
query string.
| Element | Description |
|---|---|
LocationConstraint
|
The location of the bucket. Can be the name of a single region, predefined dual-region, or multi-region. For a list of locations, see bucket locations . |
?logging
The following response body elements are applicable only if you use the logging
query string parameter to get the logging configuration
for an existing bucket.
| Element | Description |
|---|---|
Logging
|
Container for a logging configuration. If the element is empty, logging is disabled for the bucket. |
LogBucket
|
The bucket that will receive log objects. |
LogObjectPrefix
|
The object prefix for log objects. |
?object-lock
The following response body elements are applicable only if you use the object-lock
query string parameter to display bucket's object retention configuration
.
| Element | Description |
|---|---|
ObjectLockConfiguration
|
Container for the object retention configuration. |
ObjectLockEnabled
|
Status of object retention for this bucket. Enabled
is the
only valid value for this element. If object retention is not enabled for
the bucket, the overall request fails with a 404 response. |
?storageClass
The following response body element is applicable only if you use the storageClass
query string parameter to get the storage class
for an existing bucket.
| Element | Description |
|---|---|
StorageClass
|
The default storage class for the bucket. |
?tagging
The following response body elements are applicable only if you use the tagging
query string parameter to get 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 response body elements are applicable only if you use the versioning
query string parameter to get the status of Object Versioning
for an existing bucket.
| Element | Description |
|---|---|
VersioningConfiguration
|
Container for versioning configuration. This element can be empty if Object Versioning is not enabled for the bucket. |
Status
|
Status of versioning for this bucket. Can be either Enabled
or Suspended
. |
?websiteConfig
The following response body elements are applicable only if you use the websiteConfig
query string parameter to get the website configuration for
an existing bucket.
| Element | Description |
|---|---|
WebsiteConfiguration
|
Container for website configuration. If the element is empty, there is no website configuration for the bucket. |
MainPageSuffix
|
The object name suffix used to simulate directory index behavior. |
NotFoundPage
|
Name of the object to return with 404 responses. |
Example
The following example retrieves the labels for a bucket named my-bucket
. In
this example, the bucket has two labels applied to it.
Request
GET /?tagging HTTP/1.1 Host: my-bucket.storage.googleapis.com Date: Thu, 24 Jan 2016 02:34:56 GMT Content-Length: 0 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Response
HTTP/1.1 200 OK
Date: Thu, 16 Nov 2023 02:34:56 GMT
Expires: Mon, 01 Jan 1990 00:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 196
Content-Type: text/html
<?xml version="1.0" encoding="UTF-8"?>
<Tagging>
<TagSet>
<Tag>
<Key>environment</Key>
<Value>production</Value>
</Tag>
<Tag>
<Key>billing</Key>
<Value>marketing-department</Value>
</Tag>
</TagSet>
</Tagging>
