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:
The XML API uses the following extension (custom) HTTP headers:
The XML API uses the following query string parameters:
Standard HTTP headers
Authorization
A request header that contains a string used to authenticate requests.
| Valid Values | One of the following:
|
| Example | Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s- ... |
| Details |
To create a sample OAuth 2.0 access token for testing, you can use the OAuth 2.0 playground. Note: If your requests are being routed
through a proxy, you may need to check with your network administrator
to ensure that the |
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 |
| 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 |
| 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=FILENAMEt,
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. This header is also used for requests that use a V4 signature in
the Authorization header and upload data in chunks.
| Valid Values | Any valid compression algorithm (see the
specification) or aws-chunked |
| Example | Content-Encoding: gzip |
| Details | Cloud Storage does not compress objects and only decompresses
objects in certain scenarios. If
you use this header to specify a compression type algorithm (for example,
deflate), Cloud Storage preserves the header as
object metadata, but does not
compress or decompress the object.
If an upload request uses |
Content-Language
Language code of the content.
| Valid Values | A string of up to 100 characters. 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 |
| 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== |
| 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 |
| Details | When appearing in a response, the When included as part of a resumable
upload request, Byte ranges are inclusive; that is, For additional details, particularly regarding download responses, 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 |
| 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 |
| 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 Object metadata. |
| Examples | ETag: "39a59594290b0f9a30662a56d695b71d"ETag: "-CKicn4fknbUCEAE=" |
| 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 |
| 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" |
| Details | 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 |
| 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" |
| 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 |
| 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 |
| 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 completing a multipart upload it provides you with an endpoint for accessing the assembled object.
- In response to a Cookie-based authentication request it provides you with a unique web origin response URL for the request.
- In response to a JSON API download request made at a URL other than
www.googleapis.com/downloadit 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 |
| Details | The Location response header is returned when you initiate
a resumable upload. |
Range
A request header indicating the range of bytes that you want returned, and a response header indicating the range of bytes that have been uploaded to the Cloud Storage system.
| Valid Values | A single, 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) |
| Details |
When included as a header in a request for object data, only the
specified range of bytes for the object gets returned in the response
body, which is useful when downloading an object in parallel requests or
when resuming an interrupted download. A valid and successful request
results in a
206 Partial
Content response code. Multiple byte ranges in a single request are
not accepted, and in certain
circumstances the When returned as part of a response associated with a resumable upload,
Byte ranges are inclusive. For example, |
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 |
| Details | This header specifies if the message body of a request or response
has been chunked. If it is, content is received or served in a series of
chunks, with the final chunk having a length of zero. If you specify
In an upload request that uses For more details about Transfer-Encodings, see the specification. For more details about chunked transfer encoding, see the specification. |
Extension (custom) HTTP headers
x-amz-decoded-content-length
A request header that indicates the size of an upload that uses chunked transfer encoding.
| Valid Values | An integer indicating the total size of the data being uploaded |
| Example | x-amz-decoded-content-length: 66560 |
| Details | This header is required when a request that has a
V4 Signature in its
Authorization header uses the header
Transfer-Encoding: Chunked. The value
of the x-amz-decoded-content-length header must equal the
total decoded size of the object data being uploaded in the request.
Cloud Storage does not support a
x-goog-decoded-content-length header.
|
x-goog-acl
A request header that applies predefined ACLs to a bucket or object when you upload it or create it.
| Valid Values | For buckets: For objects: |
| Example | x-goog-acl: private |
| Details | When a user uploads an object or creates a bucket without specifying
any ACLs, the private ACL is applied. |
x-goog-allowed-resources
A request header that restricts the resources the request is allowed to act on.
| Valid Values | An RFC 4648 Base64-encoded string of the organization restriction definition. |
| Example | x-goog-allowed-resources: ewogInJlc291cmNlcyI6IFsib3JnYW5pemF0aW9ucy8xMjM0NTY3ODkiLCAib3JnYW5pemF0aW9ucy8xMDExMTIxMzE0Il0sCiAib3B0aW9ucyI6ICJzdHJpY3QiCn0K |
| Details | This request header prevents a request from proceeding unless each resource in the request is within an organization specified by the header. For more information, see Introduction to organization restrictions. |
x-goog-api-version
This header is deprecated and is not used.
x-goog-bucket-object-lock-enabled
A request header that enables object retention configurations for a new bucket.
| Valid Values | true |
| Example | x-goog-bucket-object-lock-enabled: true |
| Details | This request header can only be used when creating a new bucket. When
the header is included and set to true, objects added to the
bucket can be configured to have a retention configuration. Values other
than true cause this header to be ignored. |
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 |
| 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-bypass-governance-retention
A request header that enables you to shorten, remove, or lock a retention configuration for an object.
| Valid Values | true |
| Example | x-goog-bypass-governance-retention: true |
| Details | This request header is used as part of a request to change an existing
retention configuration on an object. This header must be set to
true in order to remove the retention configuration, make the
retention configuration shorter, or set the mode of the retention
configuration to COMPLIANCE. Note that a retention
configuration cannot be removed or shortened if its mode is set to
COMPLIANCE. |
x-goog-custom-audit-KEY
A request header that adds custom information to audit logs generated by Cloud Audit Logs.
| Valid Values | Any valid header name and value. The KEY in the
header name can contain up to 64 characters, including the
x-goog-custom-audit prefix. The value can contain up to
1,200 characters. |
| Example | x-goog-custom-audit-job: test-job-id |
| Details | Each request can contain up to four header entries. Custom information
is added to the
metadata
field of the protoPayload in the audit log entry. |
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 |
| 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 |
| 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 |
| Details | This header is required for requests that use a signature in the |