HTTP headers and query string parameters for XML API

The Cloud Storage XML API uses several standard HTTP headers as well as several extension (custom) HTTP headers. Several of the HTTP methods also support query string parameters. The headers and parameters are described below.

HTTP headers and query string parameters summary

The XML API uses the following standard HTTP headers:

Request	Response	Both
Authorization Content-MD5 Host If-Match If-Modified-Since If-None-Match If-Unmodified-Since	ETag Last-Modified Location	Cache-Control Content-Disposition Content-Encoding Content-Language Content-Length Content-Range Content-Type Date Range Transfer-Encoding

The XML API uses the following extension (custom) HTTP headers:

Request	Response	Both
x-goog-acl x-goog-api-version x-goog-bucket-retention-period x-goog-content-length-range x-goog-content-sha256 x-goog-copy-source x-goog-copy-source-generation x-goog-copy-source-if-generation-match x-goog-copy-source-if-match x-goog-copy-source-if-metageneration-match x-goog-copy-source-if-modified-since x-goog-copy-source-if-none-match x-goog-copy-source-if-unmodified-since x-goog-date x-goog-encryption-key x-goog-encryption-kms-key-name x-goog-if-generation-match x-goog-if-metageneration-match x-goog-metadata-directive x-goog-project-id x-goog-resumable x-goog-user-project	x-goog-component-count x-goog-expiration x-goog-generation x-goog-metageneration x-goog-stored-content-encoding x-goog-stored-content-length	x-goog-encryption-algorithm x-goog-encryption-key-sha256 x-goog-hash x-goog-meta- x-goog-storage-class

The XML API uses the following query string parameters:

AccessKeyId
acl
Action
billing
compose
cors
defaultObjectAcl
delimiter
encryption
encryptionConfig
generation
generation-marker
lifecycle

location
logging
marker
Marker
max-keys
MaxItems
prefix
response-content-disposition
response-content-type
Status
storageClass
tagging

upload_id
UserName
userProject
versioning
versions
websiteConfig
X-Goog-Algorithm
X-Goog-Credential
X-Goog-Date
X-Goog-Expires
X-Goog-SignedHeaders
X-Goog-Signature

Standard HTTP headers

Authorization

A request header that contains a string used to authenticate requests.

Valid Values	An authentication identifier ( `Bearer` \| `GOOG1` \| `AWS` ) followed by one of the following: A valid OAuth 2.0 token An access key A signature
Example	`Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s- ...`
Implementation Details	For more information about how to use this header, see Authentication. Note: If your requests are being routed through a proxy, you may need to check with your network administrator to ensure that the `Authorization` header containing your credentials is not stripped out by the proxy. Without the `Authorization` header, you receive a `MissingSecurityHeader` error and your request is rejected. For more information about accessing Cloud Storage through a proxy server, see the Troubleshooting topic.

Cache-Control

A request and response header that specifies the cache-control setting.

Valid Values	Any valid cache-control value (see the specification).
Example	`Cache-Control: public, max-age=6000`
Implementation Details	You should specify cache-control only for objects that are accessible to all anonymous users. To be anonymously accessible, an object's ACL must grant `READ` or `FULL_CONTROL` permission to `AllUsers`. If an object is accessible to all anonymous users and you do not specify a cache-control setting, Cloud Storage applies a cache-control setting of 3600 seconds. When serving via XML, Cloud Storage respects the cache-control of the object as set by its metadata.

Content-Disposition

A request and response header that specifies presentational information about the data being transmitted.

Valid Values	Any valid content disposition value (see the specification).
Example	`Content-Disposition: attachment; filename=<filename.ext>`
Implementation Details	If you set the Content-Disposition header when uploading an object, it will be served at download time (and subsequently interpreted by web browsers and other HTTP clients). A common use for Content-Disposition is setting it to `attachment;filename=<file_name.ext>`, typically causing the web browser to open a "Save As..." dialog box.

Content-Encoding

A request and response header that specifies the compression algorithm for an object.

Valid Values	Any valid compression algorithm (see the specification).
Example	`Content-Encoding: gzip`
Implementation Details	Cloud Storage does not compress or decompress objects. If you use this header to specify a compression type algorithm (for example, `deflate`), Cloud Storage preserves the header but does not compress or decompress the object.

Content-Language

The ISO 639-1 language code of the content.

Valid Values	See the ISO 639-1 column of Codes for the Representation of Names of Languages for a list of language codes.
Example	`Content-Language: en`

Content-Length

The length (in bytes) of the request or response body.

Valid Values	Any value of zero or greater.
Example	`Content-Length: 1234`
Implementation Details	This is required for all requests except those that use chunked transfer encoding (see the specification). If you do not use chunked transfer encoding and you do not include the `Content-Length` header in a request, the request fails and Cloud Storage responds with a 411 Length Required status code.

Content-MD5

The MD5 digest of the request body.

Valid Values	A valid MD5 digest.
Example	`Content-MD5: iB94gawbwUSiZy5FuruIOQ==`
Implementation Details	See the specification. Cloud Storage can use this to check the integrity of a `PUT` operation.

Content-Range

A request or response header that specifies a byte range.

Valid Values	Any valid byte range.
Example	`Content-Range: bytes 456-987/1234`
Implementation Details	See the specification.

Content-Type

The MIME type of the request or response.

Valid Values	Any valid MIME type (see the specification).
Example	`Content-Type: text/html`
Implementation Details	If you do not specify a content type when you upload an object, the Cloud Storage system defaults to `application/octet-stream` when it serves the object.

Date

The date and time of the request or response.

Valid Values	A date and time represented in conventional HTTP format (see the specification).
Example	`Date: Wed, 16 Jun 2010 11:11:11 GMT`
Implementation Details	When used to create signed URLs using the V2 signing process, the format should be in conventional HTTP format; see section 7.1.1.2 of the specification. When using the V4 signing process, the format should be in the ISO 8601 basic format `YYYYMMDD'T'HHMMSS'Z'`.

ETag

A response header that contains the entity tag of the object being accessed.

Valid Values	A string of characters enclosed by quotes. For more information, see Hashes and ETags: Best Practices.
Examples	`ETag: "39a59594290b0f9a30662a56d695b71d"` `ETag: "-CKicn4fknbUCEAE="`
Implementation Details	See the specification.

Host

A request header that specifies the URI for Cloud Storage.

Valid Values	A valid format for the URI.
Example	`Host: storage.googleapis.com`
Implementation Details	For more information about valid URIs, see Request Endpoints and the host specification.

If-Match

A request header that specifies an entity tag (ETag).

Valid Values	A valid entity tag.
Example	`If-Match: "881f7881ac1bc144a2672e45babb8839"`
Implementation Details	Only a single entity tag (not a comma-separated list of entity tags) can be specified.You can use this header with the HEAD Object and GET Object methods. If the ETag you specify with this header is the same as the ETag for the object, then the metadata or the object is returned. If the ETag you specify with this header is different than the ETag for the object, then the metadata or the object is not returned and Cloud Storage returns a 412 Precondition Failed error code. For more details, see the specification.

If-Modified-Since

A request header that specifies a date and time.

Valid Values	A date and time represented in conventional HTTP format.
Example	`If-Modified-Since: Fri, 19 Feb 2010 22:04:23 GMT`
Implementation Details	You can use this header with the HEAD Object and GET Object methods. If an object has been modified later than the date and time you specify with this header, then the metadata or the object is returned. If an object has been modified earlier than the date and time you specify with this header, then the metadata or the object is not returned and Cloud Storage returns a 304 Not Modified status code. For more information about the If-Modified-Since header, see the specification. For more detail about HTTP date formats, see the specification, Section 7.1.1.2.

If-None-Match

A request header that specifies an entity tag (ETag).

Valid Values	A valid entity tag.
Example	`If-None-Match: "881f7881ac1bc144a2672e45babb8839"`
Implementation Details	You can use this header with the HEAD Object and GET Object methods. If the ETag you specify with this header is different from the ETag for the object, then the metadata or the object is returned. If the ETag you specify with this header is the same as the ETag of the object, then the metadata or the object is not returned and Cloud Storage returns a 304 Not Modified status code. For more details, see the specification.

If-Unmodified-Since

A request header that specifies a date and time.

Valid Values	A date and time represented in conventional HTTP format.
Example	`If-Unmodified-Since: Fri, 19 Feb 2010 22:04:23 GMT`
Implementation Details	You can use this header with the HEAD Object and GET Object methods. If the object has not been modified later than the date you specify with this header, then the metadata or the object is returned. If the object has been modified later than the date you specify with this header, then the metadata or the object is not returned and Cloud Storage returns a 412 Precondition Failed error code. For more information about the If-Unmodified-Since header, see the specification. For more information about HTTP date formats, see the specification, Section 7.1.1.2.

Last-Modified

A response header that contains the date and time that the object was last modified.

Valid Values	A date and time represented in conventional HTTP format.
Example	`Last-Modified: Fri, 19 Feb 2010 22:04:23 GMT`
Implementation Details	For more information about the Last-Modified header, see the specification. For more information about HTTP date formats, see the specification, Section 7.1.1.2.

Location

A response header used for several purposes:

In response to initiating a resumable upload it provides you with a session URI for a resumable upload operation.
In response to a Cookie-based authentication request it provides you with a unique web origin response URL for the request. See Cookie-based authentication for more details.
In response to a JSON API download request made at a URL other than www.googleapis.com/download it provides a redirect to the JSON API URL where the download can be made.

Valid Values	Any valid URI.
Example	`Location: https://example.storage.googleapis.com/?upload_id=tvA0...rot`
Implementation Details	The `Location` response header is returned when you initiate a resumable upload.

Range

The range of bytes that you want returned in the response, or the range of bytes that have been uploaded to the Cloud Storage system.

Valid Values	Any contiguous range of bytes.
Examples	`Range: bytes=0-1999` (first 2000 bytes) `Range: bytes=-2000` (last 2000 bytes) `Range: bytes=2000-` (from byte 2000 to end of file)
Implementation Details	Cloud Storage does not handle complex disjoint ranges, but it does support simple contiguous byte ranges. Also, byte ranges are inclusive; that is, bytes=0-999 represent the first 1000 bytes in a file or object. A valid and successful request will result in a 206 Partial Content response code. For more information, see the specification.

Transfer-Encoding

A request and response header that specifies if transfer-encoding had been applied to the message body.

Valid Values	`chunked`
Example	`Transfer-Encoding: chunked`
Implementation Details	This header specifies if the message body of a request or response has been chunked. If it is, the server serves the content in a series of chunks, with a final chunk that has a length of zero. If you specify `Transfer-Encoding: Chunked`, you do not need to specify a `Content-Length`. This can be useful if you do not know the length of the message body in advance, such as when doing a streaming upload. For more details about Transfer-Encodings, see the specification. For more details about chunked transfer encoding, see the specification.

Extension (custom) HTTP headers

x-goog-acl

A request header that applies predefined (canned) ACLs to a bucket or object when you upload it or create it.

Valid Values	For buckets: `project-private`, `private`, `public-read`, `public-read-write`, `authenticated-read` For objects: `project-private`, `private`, `bucket-owner-read`, `bucket-owner-full-control`, `public-read`, `authenticated-read`
Example	`x-goog-acl: private`
Implementation Details	When a user uploads an object or creates a bucket without specifying any ACLs, the `private` ACL is applied. For more information about predefined ACLs, see Access Control.

x-goog-api-version

This header is deprecated and is not used.

x-goog-bucket-retention-period

A request header that adds a retention policy to a new bucket.

Valid Values	An integer between 1 and 3,155,760,000.
Example	`x-goog-bucket-retention-period: 32000`
Implementation Details	This request header can only be used when creating a new bucket. When the header is included, the new bucket gains an unlocked retention policy with a duration, in seconds, determined by this header's value.

x-goog-component-count

A response header that indicates the number of components that make up a composite object.

Valid Values	An integer greater than or equal to 1.
Example	`x-goog-component-count: 32`
Implementation Details	This response header is only returned when the accessed object is a composite object. The header returns the number of components that make up the object.

x-goog-content-length-range

A PUT request header. When used, Cloud Storage only accepts the request if the size of the request's content is within the header's specified range.

Valid Values	A `[MIN],[MAX]` pair
Example	`x-goog-content-length-range: 0,256`
Implementation Details	The values for content size are inclusive and given in bytes. If the size of the request's content is in the specified range, it's delivered as requested. If the size of the request's content is outside the specified range, the request fails and a `400 Bad Request` code is returned in the response. If the `x-goog-content-length-range` is used in a request other than `PUT`, the header is silently ignored.

x-goog-content-sha256

A request header that contains a hash of the request body.

Valid Values	A lowercase, hex-encoded, SHA-256 hash or `UNSIGNED-PAYLOAD`
Example	`x-goog-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`
Implementation Details	This header is required for requests that use a signature in the Authorization header. `x-goog-content-sha256` must match the value you used for the payload portion of your canonical request.

x-goog-copy-source

A request header that specifies the source bucket and object for a copy operation.

Valid Values A /<bucket>/<object> path

Example x-goog-copy-source: travel-maps/paris.jpg

Implementation Details

This request header specifies the path to the source object. A valid path must include the bucket and object, separated by a slash (/). Note that the source object path must be a legal URL, so should generally be percent encoded.

You must have READ permission on the source object and at least WRITE permission on the destination bucket to use this header.

If the source and destination objects are the same (including the generation), the copy is treated as an update of the metadata. For details on controlling the update/overwrite behavior, see x-goog-metadata-directive.

x-goog-copy-source-generation

A request header that specifies the generation of the object to copy.

Valid Values	Any positive number (64 bit value)
Example	`x-goog-copy-source-generation: 1360044097839000`
Implementation Details	This request header can be used with x-goog-copy-source to specify the generation of the object to copy from. It's not valid without the x-goog-copy-source header. If no such generation of the source object exists, Cloud Storage returns a 404 Not Found status code. If the source and destination objects are the same (including the generation), the copy is treated as an update of the metadata. For details on controlling the update/overwrite behavior, see x-goog-metadata-directive.

x-goog-copy-source-if-generation-match

A request header that specifies the corresponding copy request will only be executed if the source object x-goog-generation matches the specified value. This header is only valid when used with x-goog-copy-source.

Valid Values	Any positive number (64 bit value)
Example	`x-goog-copy-source-if-generation-match: 1360044097835000`
Implementation Details	This request header can be used to conditionally copy the source object only if it has the specified generation. If the generation does not match, Cloud Storage returns a 412 Precondition Failed error code. For more information, see Using Object Versions.

x-goog-copy-source-if-match

A request header that specifies the conditions for a copy operation.

Valid Values	An entity tag (ETag)
Example	`x-goog-copy-source-if-match: 53fc311c15eda0a031809982ccf92aac`
Implementation Details	Only a single entity tag (not a comma-separated list of entity tags) can be specified. This request header can be used only if you are performing a copy operation with the `x-goog-copy-source` request header. If the ETag you specify with this request header matches the ETag of the source object, then the copy operation proceeds. If the ETag does not match, Cloud Storage returns a 412 Precondition Failed error code.

x-goog-copy-source-if-metageneration-match

A request header that specifies the corresponding request will only be allowed if the metageneration of the source object matches the value of this header.

Valid Values Any positive number (64 bit value)

Example x-goog-copy-source-if-metageneration-match: 4

Implementation Details

If the source object metageneration matches the x-goog-copy-source-if-metageneration-match header, the request will be completed successfully and Google Cloud Storage returns a HTTP 200 OK status. If the metageneration does not match, Cloud Storage returns a 412 Precondition Failed error code.

This value can only be used with x-goog-copy-source-if-generation-match or x-goog-copy-source-generation, and trying to use it without either of them will result in a HTTP 400 BadRequest Invalid Argument error code.

For more information, see Using Object Versions.

x-goog-copy-source-if-modified-since

A request header that specifies the conditions for a copy operation.

Valid Values	A date and time represented in conventional HTTP format.
Example	`x-goog-copy-source-if-modified-since: Fri, 19 Feb 2010 14:05:04 GMT`
Implementation Details	This request header can be used only if you are performing a copy operation with the `x-goog-copy-source` request header. If the date and time you specify is earlier than the `Last-Modified` date of the source object, then the object is copied. If the date and time is later, Cloud Storage returns a 412 Precondition Failed error code. For more information about the If-Modified-Since HTTP header (which, other than the copy source, applies to this use case), see the specification. For more information about HTTP date formats, see the specification, Section 7.1.1.2

x-goog-copy-source-if-none-match

A request header that specifies the conditions for a copy operation.

Valid Values	An entity tag (ETag)
Example	`x-goog-copy-source-if-none-match: 53fc311c15eda0a031809982ccf92aac`
Implementation Details	This request header can be used only if you are performing a copy operation with the `x-goog-copy-source` request header. If the ETag you specify with this request header does not match the ETag of the source object, then the copy operation proceeds. If the ETag matches, Cloud Storage returns a 412 Precondition Failed error code. For more information about the If-None-Match HTTP header (which, other than the copy source, applies to this use case), see the specification.

x-goog-copy-source-if-unmodified-since

A request header that specifies the conditions for a copy operation.

Valid Values	A date and time represented in conventional HTTP format.
Example	`x-goog-copy-source-if-unmodified-since: Fri, 19 Feb 2010 14:05:04 GMT`
Implementation Details	This request header can be used only if you are performing a copy operation with the `x-goog-copy-source` request header. If the date and time you specify is later than the `Last-Modified` date of the source object, then the object is copied. If the date and time is earlier, Cloud Storage returns a 412 Precondition Failed error code. For more information about the If-Unmodified-Since HTTP header (which, other than the copy source, applies to this use case), see the specification. For more information about HTTP date formats, see the specification, Section 7.1.1.2.

x-goog-date

A request header that specifies a time stamp for authenticated requests.

Valid Values	A date and time represented in conventional HTTP format.
Example	`x-goog-date: Fri, 19 Feb 2010 14:05:04 GMT`
Implementation Details	When used to create signed URLs using the V2 signing process, the format should be in conventional HTTP format; see section 7.1.1.2 of the specification. When using the V4 signing process, the format should be in the ISO 8601 basic format `YYYYMMDD'T'HHMMSS'Z'`.

x-goog-encryption-algorithm

A request and response header that specifies the encryption algorithm to use.

Valid Values	`AES256`
Example	`x-goog-encryption-algorithm: AES256`
Implementation Details	This request and response header is used when you provide customer-supplied encryption keys.

x-goog-encryption-key

A request header that specifies an AES-256 encryption key.

Valid Values	An RFC 4648 Base64-encoded string of a valid AES-256 encryption key
Example	`x-goog-encryption-key: NwbyGGmcKAX4FxGpOERG2Ap33m5NVOgmXznSGTEvG0I=`
Implementation Details	This request header is used when you provide customer-supplied encryption keys.

x-goog-encryption-key-sha256

A request and response header that specifies the SHA256 hash of the encryption key.

Valid Values	An RFC 4648 Base64-encoded string of a valid SHA256 hash for an encryption key
Example	`x-goog-encryption-key-sha256: +eBzkZBt1Mj2CZx69L3c8yXoZB6DtRLlSvXMJB9JGIQ=`
Implementation Details	This request header is used when you provide customer-supplied encryption keys.

x-goog-encryption-kms-key-name

A request header that specifies a Cloud KMS encryption key.

Valid Values	A Cloud KMS encryption key resource.
Example	`x-goog-encryption-kms-key-name: projects/my-project/locations/us-east1/keyRings/my-keyring/cryptoKeys/my-key`
Implementation Details	This request header is used when you want to encrypt a specific object with a customer-managed encryption key.

x-goog-expiration

A response header that specifies when the accessed object will be deleted, per the lifecycle configuration.

Valid Values	A date and time represented in conventional HTTP format.
Example	`x-goog-expiration: Tue, 25 June 2013 00:00:00 GMT`
Implementation Details	This response header is only returned for objects in a bucket with lifecycle management enabled if certain conditions are met. For more information, see object lifecycle behavior.

x-goog-generation

A response header that indicates which version of the object data you are accessing.

Valid Values	Any positive number (64 bit value)
Example	`x-goog-generation: 1360044097835000`
Implementation Details	Whenever an object is created or overwritten, Cloud Storage automatically assigns a generation to it. The generation changes whenever object data is overwritten. However, there is no defined relationship between the generations on different objects. For more information, see Using Object Versions.

x-goog-if-generation-match

A request header that specifies the corresponding request is only allowed if the x-goog-generation of the object matches the value of this header.

Valid Values Zero or any positive number (64 bit value)

Example x-goog-if-generation-match: 1360044097835000

Implementation Details

If the object generation matches the x-goog-if-generation-match header, the request will be completed successfully and Google Cloud Storage returns a HTTP 200 OK status. If the generation does not match, Google Cloud Storage returns a HTTP 412 Precondition Failed error code.

If you set the x-goog-if-generation-match header to 0, Google Cloud Storage only performs the specified request if the object does not currently exist. For example, you can perform a PUT request to create a new object with a x-goog-if-generation-match, and the object will only get created if it doesn't already exist as a live version. If the object exists, the request is aborted.

For more information, see Using Object Versions.

x-goog-if-metageneration-match

A request header that specifies the corresponding request is only allowed if the x-goog-metageneration of the object matches the value of this header.

Valid Values Any positive number (64 bit value)

Example x-goog-if-metageneration-match: 4

Implementation Details

If the object metageneration matches the x-goog-if-metageneration-match header, the request will be completed successfully and Google Cloud Storage returns a HTTP 200 OK status. If the metageneration does not match, Cloud Storage returns a HTTP 412 Precondition Failed error code.

This request header should only be used with x-goog-if-generation-match header to ensure updates to metadata are in fact performed against the generation of the object you are planning to update and hence allows you to perform read-modify-write operations safely.

For more information, see Using Object Versions.

x-goog-metadata-directive

A request header that specifies metadata handling during a copy operation.

Valid Values	`COPY` \| `REPLACE`
Example	`x-goog-metadata-directive: REPLACE`
Implementation Details	This request header can be used only if you are performing a copy operation with the `x-goog-copy-source` request header. If you specify `COPY`, the metadata of the source object is applied to the newly-created object. If you specify `REPLACE`, the metadata of the source object is replaced with whatever metadata you provide in the request. If you copy the metadata from the source object to the newly-created object, the ACLs are not copied and the default object ACLs are applied to the new object. You can apply different ACLs during a copy operation by using the `x-goog-acl` request header.

x-goog-metageneration

A response header that indicates which version of the object metadata you are accessing.

Valid Values	Any positive number (64 bit value)
Example	`x-goog-metageneration: 1`
Implementation Details	Whenever an object is created or overwritten, Cloud Storage automatically assigns a metageneration of 1. The metageneration increases whenever object metadata is updated (ACL update, or other metadata updates). This means that a larger metageneration always implies a newer version of the object metadata. However, there is no defined relationship between different generations on different objects, nor even different generations of the same object. Each generation of the object has its own metageneration version that only pertains to its generation. For more information, see Using Object Versions.

x-goog-hash

A request and response header for expressing an object's MD5 and/or CRC32C base64-encoded checksums. As a request header for upload requests, the supplied hashes are validated against the values calculated by Cloud Storage.

Valid Values	Either `md5=<base64-encoded-md5>` or `crc32c=<base64-encoded-crc32c>`. Specify CRC32c values in big-endian byte order. Also, note that HTTP considers comma separated header values as equivalent to separate headers with identical keys.
Examples	`x-goog-hash: crc32c=n03x6A==` `x-goog-hash: md5=Ojk9c3dhfxgoKVVHYwFbHQ==` `x-goog-hash: crc32c=n03x6A==,md5=Ojk9c3dhfxgoKVVHYwFbHQ==`
Implementation Details	Cloud Storage stores MD5 hashes for all non-composite objects. CRC32Cs are available for all objects.

x-goog-meta-

A request and response header that lets you define custom metadata for an object.

Valid Values Any valid header name.

Example x-goog-meta-reviewer: jane

Implementation Details

To use this header you append your custom header name to the x-goog-meta- prefix and then add the header and its associated value to your PUT or POST request. For example, if your objects are associated with various projects, you can add the project-specific information to your object metadata by creating several request headers, such as: x-goog-meta-project-name, x-goog-meta-project-number, and x-goog-meta-project-manager. You could then set a value for these request headers during a PUT or POST request as shown in the following example:

PUT /<some_object.jpg> HTTP/1.1
Host: <some_bucket>.storage.googleapis.com
Date: Wed, 17 Jun 2020 11:11:11 GMT
Content-Type: image/jpg
Content-Length: 554
Authorization: Bearer 1/zVNpoQNsOSxZKqOZgckhpQ
x-goog-meta-project-name: Sales Projections
x-goog-meta-project-number: 878973
x-goog-meta-project-manager: W. Loman

x-goog-meta- headers are stored with an object and are always returned in a response header when you do a GET or HEAD request on an object. Use of headers as custom metadata incurs a charge as discussed in Pricing and Support.

Note: All custom headers and their associated values must contain only printable US-ASCII characters.

Note: We recommend that you limit the total size of custom headers to a few KB.

x-goog-project-id

A request header that specifies which project you are working on.

Valid Values	Any valid project number or name.
Examples	`x-goog-project-id: 000111222333` `x-goog-project-id: my-project-name` `x-goog-project-id: example.com:my-google-apps-for-work-project-name`
Implementation Details	This request header tells Cloud Storage which project to create a bucket in or which project to list buckets for. It is optional for these tasks if you have set a default project for interoperable access.

x-goog-resumable

A request header that initiates a resumable upload operation.

Valid Values	start
Example	`x-goog-resumable: start`
Implementation Details	This request header notifies the Cloud Storage system that you want to initiate a resumable upload. The header can be used only with a POST Object request and can be used only for resumable uploads.

x-goog-storage-class

A request and response header that indicates the storage class of an object.

Valid Values	`STANDARD`, `NEARLINE`, `COLDLINE`, `ARCHIVE`, `MULTI_REGIONAL`, `REGIONAL`
Example	`x-goog-storage-class: NEARLINE`
Implementation Details	This header can be included in `PUT Object` and `POST Object` requests in order to set an object to a storage class besides the default storage class of the associated bucket. The header is included in all `GET Object` responses.

x-goog-stored-content-encoding

A response header that indicates the content encoding of the object as stored in Cloud Storage, independent of any server-driven negotiation that might occur for individual requests for the object.

Valid Values	The content-coding specified in the object upload or `identity`.
Example	`x-goog-stored-content-encoding: gzip`
Implementation Details	If an object was uploaded with no content-coding, then the value of this header is `identity`.

x-goog-stored-content-length

A response header that indicates the content length (in bytes) of the object as stored in Cloud Storage, independent of any server-driven negotiation that might occur for individual requests for the object.

Valid Values	Any byte value of zero or greater.
Example	`x-goog-stored-content-length: 350`
Implementation Details	None

x-goog-user-project

A request header that specifies a user project to bill for access charges associated with the request.

Valid Values	The Project ID for an existing Google Cloud project
Example	`x-goog-user-project: my-project`
Implementation Details	The project specified in the header is billed for charges associated with the request. This header is used, for example, when making requests to buckets that have Requester Pays enabled.

Query string parameters

In the examples of query string parameters described in this section, the URIs are not shown but are assumed to be relative to storage.googleapis.com. As described in Request Endpoints, you can also specify the bucket name as part of the hostname, for example, [BUCKET-NAME].storage.googleapis.com. If you are specifying the bucket as part of the hostname, then do not include the bucket name as part of the URI path. For example, the following are equivalent for getting the ACL of an object:

https://storage.googleapis.com/[BUCKET-NAME]/object-name?acl
https://[BUCKET-NAME].storage.googleapis.com/object-name?acl

AccessKeyId

A query string parameter that enables you to identify which HMAC key you want to update or delete.

Valid Values	An access ID associated with an HMAC key.
Example	`/?Action=UpdateAccessKey&AccessKeyId=GOOG1EXAMPLE&Status=Inactive` `/?Action=DeleteAccessKey&AccessKeyId=GOOG1EXAMPLE`
Implementation Details	The `AccessKeyId` query string parameter allows you to specify which HMAC key you are updating or deleting. You must use `AccessKeyId` in conjunction with the `Action` query parameter. For information on how to retrieve the access ID for your HMAC key, see Getting HMAC key information.

acl

A query string parameter that enables you to retrieve or change the access control list for a bucket or object.

Valid Values	none
Example	`/<bucket>?acl` `/<bucket>/<object>?acl`
Implementation Details	Optional for the following requests: PUT Bucket, PUT Object, GET Bucket, GET Object. If sending a PUT request, you must include an XML document in the request body that specifies the ACLs you want to apply. You cannot use any additional subresources with this query parameter.

Action

A query string parameter that enables you to identify which HMAC key operation to perform.

Valid Values	`ListAccessKeys`, `CreateAccessKey`, `UpdateAccessKey`, `DeleteAccessKey`
Example	`/?Action=ListAccessKeys`
Implementation Details	The `Action` query string parameter allows you to specify which HMAC key operation to perform: `list`, `create`, `update`, or `delete`.

billing

A query string parameter that allows you to enable, disable, or check the status of the Requester Pays feature for a bucket.

Valid Values	Within the request body: `Enabled`, `Disabled`.
Example	`/<bucket>?billing`
Implementation Details	Optional for the following requests: `GET Bucket`, `PUT Bucket`. When used in a `GET Bucket` request, the current status of the Requester Pays feature is returned in the response body. When used in a `PUT Bucket` request, the request body should contain a `<BillingConfiguration>` element that specifies whether to enable or disable the feature. For more information on setting the Requester Pays feature using the XML API, see Set Bucket Requester Pays.

compose

A query string parameter that enables you to compose a sequence of existing objects into a new composite object (used only with the XML API).

Valid Values	none
Example	`/<bucket/object>?compose`
Implementation Details	Optional for PUT Object requests. A ComposeRequest XML document must be supplied in the request body. You cannot use any additional subresources with this query parameter.

cors

A query string parameter that enables you to retrieve or change the Cross-Origin Resource Sharing (CORS) for a bucket.

Valid Values	none
Example	`/<bucket>?cors`
Implementation Details	Optional for the following requests: PUT Bucket, GET Bucket. If sending a PUT request, you must include an XML document in the request body that specifies the CORS you want to apply. You cannot use any additional subresources with this query parameter.

defaultObjectAcl

A query string parameter that enables you to retrieve or change the default object access control list for a bucket.

Valid Values	none
Example	`/<bucket>?defaultObjectAcl`
Implementation Details	Optional for PUT Bucket and GET Bucket requests. If sending a PUT request, you must include an XML document in the request body that specifies the ACL that applies by default to new objects added to the bucket. You cannot use any additional subresources with this query parameter. See Setting default object ACLs for more information.

delimiter

A character or group of characters that is used to restrict a list of objects during a GET Bucket request.

Valid Values	Any Unicode character or characters.
Example	`/?delimiter=/`
Implementation Details	The `delimiter` simplifies a list of objects that use a directory-like naming scheme. You can use a `delimiter` in conjunction with a `prefix` parameter. In this case, the `prefix` is used to specify the directory to be listed, and the delimiter is used to specify the directory separator. All file-like object names are listed in the `Contents` elements of the response, and all subdirectory-like portions of object names are listed in the `CommonPrefixes` elements of the response. If the `prefix` is not provided, the top level directory is listed. The `delimiter` is usually set to `/`, but it can be any sequence of characters. For an example of how to use a `delimiter`, see the Sample Request and Response for the GET Bucket request method.

encryption

A query string parameter that enables you to retrieve an object's encryption information.

Valid Values	none
Example	`/object?encryption`
Implementation Details	Optional for GET Object requests. When the queried object is encrypted by a customer-supplied encryption key, the encryption algorithm and the key's SHA-256 are returned in an `Encryption` element. When the queried object is encrypted by a customer-managed encryption key, the Cloud Key Management Service key resource is returned in an `Encryption` element. In all other cases, an empty `Encryption` element is returned. You cannot use any additional subresources with this query parameter.

encryptionConfig

A query string parameter that enables you to set or retrieve the default customer-managed encryption key that a bucket uses.

Valid Values	none
Example	`/bucket?encryptionConfig`
Implementation Details	Optional for GET Bucket requests. When the queried bucket has a default customer-managed encryption key set on it, the name of the key resource is returned within an `EncryptionConfiguration` element. Optional for PUT Bucket requests. When the request includes a customer-managed encryption key resource in the request body, that key becomes the default encryption key for the bucket. When the request includes an empty `EncryptionConfiguration` element, any existing default key is removed from the bucket.

generation

A value that indicates which generation of the object to fetch.

Valid Values	Any positive number (64 bit value)
Example	`?generation=1360887759327000`
Implementation Details	The `generation` query string parameter allows you to specify which version of the object to operate on.

generation-marker

A value that indicates the generation number at which you want a list of objects to start.

Valid Values	Any positive number (64 bit value)
Example	`?generation-marker=1360887759327000`
Implementation Details	The `generation-marker` query string parameter is a starting point for paged listings on versioned buckets. Must be used in conjunction with `marker`, to fully specify the object and generation of where to start the listing at. Any object versions with greater than the specified `generation-marker` (including current if it has a greater generation) as well as following objects in lexicographically greater will be returned in the list of objects.

lifecycle

A query string parameter that enables you to retrieve or change the lifecycle management policies for a bucket.

Valid Values	none
Example	`/<bucket>?lifecycle`
Implementation Details	Optional for the following requests: PUT Bucket, GET Bucket. If sending a PUT request, you must include an XML document in the request body that specifies the lifecycle configuration. You cannot use any additional subresources with this query parameter.

location

A query string parameter that enables you to retrieve the location constraint for a bucket.

Valid Values	none
Example	`/<bucket>?location`
Implementation Details	Optional for the following requests: GET Bucket.

logging

A query string parameter that enables you to retrieve or change the logging configuration for a bucket.

Valid Values	none
Example	`/<bucket>?logging`
Implementation Details	Optional for the following requests: PUT Bucket, GET Bucket. If sending a PUT request, you must include an XML document in the request body that specifies the logging configuration. You cannot use any additional subresources with this query parameter.

marker

A string that indicates where you want a list of objects to start.

Valid Values	Any string.
Example	`?marker=test`
Implementation Details	The `marker` query string parameter is a string of Unicode characters that specifies which object you want a list of objects to begin with. This causes a list of objects to be returned that are lexicographically greater than the first object after the `marker`.

Marker

A page token that enables you to list subsequent pages of HMAC keys.

Valid Values	A string provided in a previous `list` response if `IsTruncated` is `true`.
Example	`?Action=ListAccessKeys&Marker=AERPALERN/NEXT/TOKEN`
Implementation Details	The `Marker` query string parameter is a continuation token, used to page through large result sets when listing HMAC keys for a given project. If `IsTruncated` is `true` in a previous `list`response, use the provided `Marker` token in subsequent `list` requests until `IsTruncated` is `false`. You must use `Marker` in conjunction with the `Action` query parameter. For more information, see GET HMAC Key.

max-keys

An integer that limits the number of objects returned in a single result "page".

Valid Values	Any number greater than 0.
Example	`?max-keys=100`
Implementation Details	The `max-keys` query string parameter is an integer that specifies the maximum number of objects you want returned in a list of objects. If a request can return more objects than `max-keys` allows, the `IsTruncated` response element contains a `True` value.

MaxItems

An integer that limits the number of HMAC keys returned in a single result page.

Valid Values	Any number greater than 0.
Example	`?Action=ListAccessKeys&MaxItems=100`
Implementation Details	The `MaxItems` query string parameter is an integer that specifies the maximum number of HMAC keys returned in a single result page. If a request can return more keys than `MaxItems` allows, the `IsTruncated` response element contains a `true` value. You must use `MaxItems` in conjunction with the `Action` query parameter. The service may return fewer results than the specified maximum.

prefix

A string that restricts a list objects to those objects that have a specific prefix.

Valid Values	Any valid prefix.
Example	?prefix=/europe/france
Implementation Details	The `prefix` query string parameter is a string of Unicode characters that restricts the listing to objects whose names begin with the string specified by the `prefix`. You can use the `prefix` query string parameter in conjunction with the `delimiter` query string parameter to create a smaller subset of objects.

response-content-disposition

A query string parameter that allows content-disposition to be overridden for authenticated GET requests.

Valid Values	URL-encoded header to return instead of the content-disposition of the underlying object.
Example	`?response-content-disposition=attachment%3B%20filename%3D%22foo%22`
Implementation Details	Allows authenticated GET requests to override the content-disposition returned in the headers. For more information, see the specification.

response-content-type

A query string parameter that allows content-type to be overridden for authenticated GET requests.

Valid Values	URL-encoded header to return instead of the content-type of the underlying object.
Example	`?response-content-type=text%2Fhtml`
Implementation Details	Allows authenticated GET requests to override the content-disposition returned in the headers. For more information, see the specification.

Status

A query string parameter that allows you to enable or disable an HMAC key.

Valid Values	`Active`, `Inactive`
Example	`?Action=UpdateAccessKey&AccessKeyId=GOOG1EXAMPLE&Status=Inactive`
Implementation Details	The `Status` query string parameter allows you to change the status of an HMAC key between `Active` and `Inactive`. You must use `Status` in conjunction with the `Action` and `AccessKeyId` query parameters.

storageClass

A query string parameter that enables you to set or retrieve the storage class of a bucket.

Valid Values	Within the request body: `STANDARD`, `NEARLINE`, `ARCHIVE`, `COLDLINE`, `MULTI_REGIONAL`, `REGIONAL`,`DURABLE_REDUCED_AVAILABILITY`
Example	`/<bucket>?storageClass`
Implementation Details	Optional for the following requests: `GET Bucket`, `PUT Bucket`. When used in a `GET Bucket` request, the storage class of the specified bucket is returned in the response body. When used in a `PUT Bucket` request, the request body should contain a `<StorageClass>` element that specifies the storage class you want to assign to the bucket. For more information on setting the storage class of a bucket using the XML API, see Set Bucket Storage Class.

tagging

A query string parameter that enables you to set or retrieve the labels applied to a bucket.

Valid Values	Within the request body: A label, given as a `key:value` pair.
Example	`/<bucket>?tagging`
Implementation Details	Optional for the following requests: `GET Bucket`, `PUT Bucket`. When used in a `GET Bucket` request, the labels applied to the specified bucket are returned in the response body. When used in a `PUT Bucket` request, the request body should contain a `<Tagging>` element that specifies the labels you want to apply to the bucket. For more information on applying labels using the XML API, see Set Bucket Labels.

upload_id

A query string parameter that specifies that upload ID for a resumable upload operation. The upload_id is part of the session URI, but you should save the entire session URI because it uniquely defines the request URI for subsequent resumable uploads operations. The session URI is obtained from the Location response header.

Valid Values Any valid upload ID.

Example /?upload_id=tvA0ExBntDaOKdxL46u1NkHxNb...B2Uowrot HTTP/1.1

Implementation Details

An upload ID expires after one week. We recommend that you start a resumable upload as soon as you obtain the upload ID, and that you resume an interrupted upload shortly after the interruption occurred.

If you use an expired upload ID in a request, you will receive a 400 Bad Request status code. In this case, you will have to re-initiate the resumable upload, obtain a new upload ID, and start the upload from the beginning using the new upload ID.

The upload ID is bound to the location it was created, so if you create in one location and use it in another location, your performance will suffer.

The upload ID is a Bearer token, meaning possession of this token acts as an authenticator. Thus, you should be careful not to leak upload IDs.

UserName

A query string parameter that enables you to identify the service account for which you want to create, update, or list an HMAC key.

Valid Values	A valid service account email address.
Example	`/?Action=CreateAccessKey&UserName=serviceAccount@proj.iam.gserviceaccount.com`
Implementation Details	`UserName` is required for creating an HMAC key and optional for updating a key or listing keys associated with a project. You must use `UserName` in conjunction with the `Action` query parameter.

userProject

A query string parameter that specifies a project ID to bill for access charges associated with the request.

Valid Values	Any valid project ID.
Example	`?userProject=example-project`
Implementation Details	The project specified in this parameter is billed for charges associated with the request. `userProject` is used, for example, when making requests to buckets that have Requester Pays enabled. Generally, XML requests that require a project ID should supply one in the `x-goog-user-project` header instead of the `userProject` parameter.

versioning

A query string parameter that enables you to retrieve or change versioning configuration of a bucket.

Valid Values	none
Example	`/<object>?versioning`
Implementation Details	Optional for the following requests: PUT Bucket, GET Bucket. If sending a PUT request, you must include an XML document in the request body that specifies the Versioning Configuration you want to apply. You cannot use any additional subresources with this query parameter.

versions

A query string parameter that enables you to retrieve all generation of objects in a versioned bucket.

Valid Values	none
Example	`/<bucket>?versions=True`
Implementation Details	Optional for the following requests: GET Bucket.

websiteConfig

A query string parameter that enables you to retrieve or change a bucket's website configuration.

Valid Values	none
Example	`/<bucket>?websiteConfig`
Implementation Details	Optional for the following requests: PUT Bucket, GET Bucket. If sending a PUT request, you must include an XML document in the request body that specifies the Website Configuration you want to apply. You cannot use any additional subresources with this query parameter.

X-Goog-Algorithm

A query string parameter to determine the V4 Signed URL algorithm.

Valid Values	`GOOG4-RSA-SHA256` `GOOG4-HMAC-SHA256` `AWS4-HMAC-SHA256`
Implementation Details	Used specifically for V4 Signed Requests such as Signed URLs.

X-Goog-Credential

A query string parameter to determine the credential type used.

Valid Values	`[Service_Account_Email]/[Date]/[Region]/goog4_request` `[Google_HMAC_Access_Key_ID]/[Date]/[Region]/goog4_request` `[AWS_HMAC_Access_Key_ID]/[Date]/[Region]/aws4_request`
Example	Using a Google Service Account: `example%40example-project.iam.gserviceaccount.com%2F20181026%2Fus-central-1%2Fstorage%2Fgoog4_request` Using HMAC: `GOOGTS7C7FUP3AIRVJTE2BCD%2F20181026%2Fus-central-1%2Fstorage%2Fgoog4_request`
Implementation Details	Used specifically for V4 Signed Requests such as Signed URLs.

X-Goog-Date (Query Parameter)

The date and time the signed URL became usable.

Valid Values	Any date that follows: YYYYMMDD'T'HHMMSS'Z'
Example	`?X-Goog-Date=20181026T181309Z`
Implementation Details	Format used is the ISO 8601 basic format YYYYMMDD'T'HHMMSS'Z'.

X-Goog-Expires

A query string parameter to determine how long a V4 Signed URL is active.

Valid Values	1 second up to and including 604800 seconds
Example	`?X-Goog-Expires=900`
Implementation Details	The length of time the signed URL remained valid, measured in seconds from the value in X-Goog-Date (Query Parameter). Maximum value is 7 days or 604800 seconds.

X-Goog-SignedHeaders

A query string parameter to determine the headers signed in a V4 Signed URL.

Valid Values	The only required header is host. Any header that is signed in a V4 Signed URL signature should must be in this list.
Examples	`?X-Goog-SignedHeaders=host` `?X-Goog-SignedHeaders=host,x-goog-acl`
Implementation Details	Headers that had to be included as part of any request that used the signed URL.

X-Goog-Signature

A query string parameter with the value of a V4 Signed URL signature.

Valid Values	Signature of the Signed URL.
Example	?X-Goog-Signature=247a2aa45f169edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa8496def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dcc1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c20580e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b133447032ea7abedc098d2eb14a7
Implementation Details	The authentication string that allowed requests using this signed URL to access the designated resource.