Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



HTTP Headers and Query String Parameters

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

Contents

  1. HTTP headers and query string parameters summary
  2. Standard HTTP headers
  3. Extension (custom) HTTP headers
  4. Query string parameters

HTTP headers and query string parameters summary

Standard HTTP Headers

Request
  1. Authorization
  2. Content-MD5
  3. Host
  4. If-Match
  5. If-Modified-Since
  6. If-None-Match
  7. If-Unmodified-Since

Response
  1. ETag
  2. Last-Modified
  3. Location

Both
  1. Cache-Control
  2. Content-Disposition
  3. Content-Encoding
  4. Content-Language
  5. Content-Length
  6. Content-Range
  7. Content-Type
  8. Date
  9. Range
  10. Transfer-Encoding

Extension (Custom) HTTP Headers

Request
  1. x-goog-acl
  2. x-goog-api-version
  3. x-goog-copy-source
  4. x-goog-copy-source-generation
  5. x-goog-copy-source-if-generation-match
  6. x-goog-copy-source-if-match
  7. x-goog-copy-source-if-metageneration-match
  8. x-goog-copy-source-if-modified-since
  9. x-goog-copy-source-if-none-match
  10. x-goog-copy-source-if-unmodified-since
  11. x-goog-date
  12. x-goog-if-generation-match
  13. x-goog-if-metageneration-match
  14. x-goog-metadata-directive
  15. x-goog-project-id
  16. x-goog-resumable

Response
  1. x-goog-component-count
  2. x-goog-expiration
  3. x-goog-generation
  4. x-goog-metageneration
  5. x-goog-stored-content-encoding
  6. x-goog-stored-content-length

Both
  1. x-goog-hash
  2. x-goog-meta-

Query String Parameters

  1. acl
  2. compose
  3. cors
  4. delimiter
  5. generation
  6. generation-marker
  7. lifecycle
  8. location
  9. logging
  10. marker
  11. max-keys
  12. prefix
  13. response-content-disposition
  14. response-content-type
  15. storageClass
  16. upload_id
  17. versioning
  18. versions
  19. websiteConfig

Standard HTTP headers


Authorization

A request header that contains an authentication string used to authenticate requests.

Valid Values

An authentication identifier ( OAuth | GOOG1 | AWS ) followed by one of the following:

A valid OAuth 2.0 token

An access key

A signature

Example

Authorization: OAuth 1/zVNpoQNsOSxZKqOZgckhpQ

Implementation Details

This header is required for the following requests: GET Service, PUT Bucket, DELETE Bucket. 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 will receive a MissingSecurityHeader error and your request will be rejected. For more information about accessing Google Cloud Storage through a proxy server, see the FAQ .

Back to top


Cache-Control

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

Valid Values

Any valid cache control setting.

Example

Cache-Control: public, max-age=6000

Implementation Details

You can 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 all AllUsers . If an object is accessible to all anonymous users and you do not specify a cache control setting, Google Cloud Storage applies a cache control setting of 3600 seconds. Google Cloud Storage sets the cache control to private for any object that is not publicly accessible.

Back to top


Content-Disposition

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

Valid Values

Any valid content disposition value (see 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 browser or HTTP client). 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.

Back to top


Content-Encoding

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

Valid Values

Any valid compression algorithm.

Example

Content-Encoding: gzip

Implementation Details

Google Cloud Storage does not compress or decompress objects. If you use this header to specify a compression type or compression algorithm (for example, deflate ), Google Cloud Storage preserves the header but does not compress or decompress the object.

Back to top


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

Back to top


Content-Length

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

Valid Values

Any byte value of zero or greater.

Example

Content-Length: 1234

Implementation Details

This is required for all requests except PUT Object requests that use chunked transfer encoding. If you do not use chunked transfer encoding and you do not include the Content-Length header in a request, the request fails and Google Cloud Storage responds with a 411 Length Required status code.

Back to top


Content-MD5

The MD5 digest of the request body.

Valid Values

A valid MD5 digest.

Example

Content-MD5: iB94gawbwUSiZy5FuruIOQ==

Implementation Details

None.


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

None.

Back to top


Content-Type

The MIME type of the request or response.

Valid Values

Any valid MIME type.

Example

Content-Type: text/html

Implementation Details

If you do not specify a content type when you upload an object, the Google Cloud Storage system defaults to binary/octet-stream when it serves the object.

Back to top


Date

The date and time of the request or response.

Valid Values

A date and time represented in conventional HTTP format.

Example

Date: Wed, 16 Jun 2010 11:11:11 GMT

Implementation Details

For more information about HTTP date formats, see HTTP 1.1 RFC , section 3.3.1.

Back to top


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

None.

Back to top


Host

A request header that specifies the URI for Google Cloud Storage.

Valid Values

A valid format for the URI.

Example

Host: storage.googleapis.com

Implementation Details

None.

Back to top


If-Match

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

Valid Values

A valid entity tag.

Example

If-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 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 Google Cloud Storage returns a 412 Precondition Failed error code.

Back to top


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 Google Cloud Storage returns a 304 Not Modified status code.

For more information about HTTP date formats, see HTTP 1.1 RFC , section 3.3.1.

Back to top


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 Google Cloud Storage returns a 304 Not Modified status code.

Back to top


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 Google Cloud Storage returns a 412 Precondition Failed error code.

For more information about HTTP date formats, see HTTP 1.1 RFC , section 3.3.1.

Back to top


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 HTTP date formats, see HTTP 1.1 RFC , section 3.3.1.

Back to top


Location

A response header that provides you with an upload ID for a resumable upload operation.

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.

Back to top


Range

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

Valid Values

Any contiguous range of bytes.

Example

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

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

Back to top


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. This can be useful if you don't know the Content-Length of the message body. 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 Content-Length of the message body in advance, such as when doing a streaming upload.

Back to top

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

private

public-read

public-read-write

authenticated-read

bucket-owner-read

bucket-owner-full-control

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 .

Back to top


x-goog-api-version

This header is deprecated and is not required.

Back to top


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

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.

Back to top


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 (/). 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 .

Back to top


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 x-goog-copy-source header. If no such generation of the source object exists, Google 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 .

Back to top


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, Google Cloud Storage returns a 412 Precondition Failed error code.

For more information, see Using Object Versions .

Back to top


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

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, Google Cloud Storage returns a 412 Precondition Failed error code.

Back to top


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

A request header that specifies the corresponding request will only go through 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, Google 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 .

Back to top


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, Google Cloud Storage returns a 412 Precondition Failed error code.

For more information about HTTP date formats, see HTTP 1.1 RFC , section 3.3.1.

Back to top


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, Google Cloud Storage returns a 412 Precondition Failed error code.

Back to top


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, Google Cloud Storage returns a 412 Precondition Failed error code.

For more information about HTTP date formats, see HTTP 1.1 RFC , section 3.3.1.

Back to top


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

You can use this request header if your client library does not provide a means for specifying a Date header.

For more information about HTTP date formats, see HTTP 1.1 RFC , section 3.3.1.

Back to top


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 .

Back to top

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, Google Cloud Storage automatically assigns a generation to it. The generation increases monotonically whenever object data is overwritten, which means that a larger generation always implies a newer version of the object. However, there is no defined relationship between the generations on different objects.

For more information, see Using Object Versions .

Back to top


x-goog-if-generation-match

A request header that specifies the corresponding request will only go through if the x-goog-generation of the object matches the value of this header.

Valid Values

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 .

Back to top


x-goog-if-metageneration-match

A request header that specifies the corresponding request will only go through if the x-goog-if-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, Google 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 .

Back to top


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.

Back to top


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, Google Cloud Storage automatically assigns a metageneration of 1. The metageneration increases monotonically 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 .

Back to top


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 Google Cloud Storage.

Valid Values

Either md5= <base64-encoded-md5> or crc32c= <base64-encoded-crc32c> . 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

Google Cloud Storage stores MD5 hashes for all non-composite objects. CRC32Cs are available for all objects.

Back to top


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 , 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, 16 Jun 2010 11:11:11 GMT
Content-Type: image/jpg
Content-Length: 554
Authorization: OAuth 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.

Back to top


x-goog-project-id

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

Valid Values

Any valid project ID name.

Example

x-goog-project-id: 000111222333

Implementation Details

This request header tells Google Cloud Storage which project to create a bucket in or which project to list buckets for. This header should be specified when you create a bucket or list buckets using the Google Cloud Storage REST API.

Back to top


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

Back to top


x-goog-stored-content-encoding

A response header that indicates the content encoding of the object as stored in Google 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".

Back to top


x-goog-stored-content-length

A response header that indicates the content length (in bytes) of the object as stored in Google 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

Back to top



Query string parameters

In the examples of query string parameters described in this section, the URIs are not shown but assumed to be relative to storage.googleapis.com . As described in Request URIs , 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

acl

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

Valid Values

none

Examples

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

Back to top


compose

A query string parameter that enables you to compose a sequence of existing objects into a new composite object.

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.

Back to top


cors

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

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.

Back to top


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.

Back to top


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.

Back to top


generation-marker

A value that indicates which generation 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 lexigraphically greater will be returned in the list of objects.

Back to top


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.

Back to top


location

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

Valid Values

ASIA, ASIA-EAST1, EU, US, US-CENTRAL1, US-CENTRAL2, US-EAST1, US-EAST2, US-EAST3, US-WEST1

Example

/ <bucket> ?location

Implementation Details

Optional for the following requests: GET Bucket.

Back to top


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.

Back to top


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. Any objects whose names are lexigraphically greater than the marker are returned in the list of objects.

Back to top


max-keys

An integer that limits the number of objects returned in a list.

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.

Back to top


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.

Back to top


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

/bucket/object?GoogleAccessId=1234567890123@developer.gserviceaccount.com&Expires;=1331155464&Signature;=BClz9e4UA2MRRDX62TPd8sNpUCxVsqUDG3YGPWvPcwN%2BmWBPqwgUYcOSszCPlgWREeF7oPGowkeKk7J4WApzkzxERdOQmAdrvshKSzUHg8Jqp1lw9tbiJfE2ExdOOIoJVmGLoDeAGnfzCd4fTsWcLbal9sFpqXsQI8IQi1493mw%3D&response-content-disposition;=attachment%3B%20filename%3D%22foo HTTP/1.1

Implementation Details

Allows authenticated GET requests to override the content-disposition returned in the headers.

Back to top

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

/bucket/object?GoogleAccessId=1234567890123@developer.gserviceaccount.com&Expires;=1331155464&Signature;=BClz9e4UA2MRRDX62TPd8sNpUCxVsqUDG3YGPWvPcwN%2BmWBPqwgUYcOSszCPlgWREeF7oPGowkeKk7J4WApzkzxERdOQmAdrvshKSzUHg8Jqp1lw9tbiJfE2ExdOOIoJVmGLoDeAGnfzCd4fTsWcLbal9sFpqXsQI8IQi1493mw%3D&response-content-type;=text%2Fhtml HTTP/1.1

Implementation Details

Allows authenticated GET request to override the content-disposition returned in the headers.

Back to top


storageClass

A query string parameter that enables you to retrieve how data is stored in a bucket.

Valid Values

STANDARD, DURABLE_REDUCED_AVAILABILITY

Example

/ <bucket> ?storageClass

Implementation Details

Optional for the following requests: GET Bucket.

Back to top


upload_id

A query string parameter that specifies that upload ID for a resumable upload operation.

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 initiate the resumable upload, obtain a new upload ID, and start the upload from the beginning using the new upload ID.

Back to top


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.

Back to top


versions

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

Valid Values

none

Example

/ <bucket> ?versions

Implementation Details

Optional for the following requests: GET Bucket.

Back to top


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.

Back to top


Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.