Sign in

1. Products
2. Google Cloud Platform
3. Google Cloud Storage

Google Cloud Storage

Feedback on this document

Reference Methods

Google Cloud Storage supports several standard HTTP request methods. Each method can use numerous request headers and response headers. The following document describes all of the supported HTTP methods as well as the most frequently used headers that are used with each method. The documentation does not describe all of the possible request headers you could use, rather, it describes only those headers that you are likely to use or see in a request and response.

Service Requests

1. GET Service

Bucket Requests

1. DELETE Bucket
2. GET Bucket
3. HEAD Bucket
4. PUT Bucket

Object Requests

1. DELETE Object
2. GET Object
3. HEAD Object
4. POST Object
5. PUT Object

If you do not provide authorization information when required to perform a request, the Google Cloud Storage issues a 401 unauthorized error. For more information, see Status Codes .

Conventions used in this document:

• The Authorization header is represented as <authentication string> . If you are using the XML API in a simple migration scenario, for example, to work interoperably with another storage provider, then the Authorization has the format discussed in Authentication in a Simple Migration Scenario . Otherwise, the Authorization header has the format discussed in OAuth 2.0 Authentication .

• The Host header used in this document is of the form:

  Host: BUCKET-NAME.storage.googleapis.com

  where the bucket name is specified as part of the hostname. In all operations except GET service, you can also specify the bucket as part of the URL path. For more information, see Request URIs .

GET Service

Lists all of the buckets in a specified project.

Request Details

Query String Parameters

This request does not use query string parameters.

Request Headers

Header	Description	Required
Authorization	The authentication string for the request.	Yes
Content-Length	The length of the request body without headers (in bytes).	Yes
Date	The date and time of the request.	Yes
Host	The URI for Google Cloud Storage.	Yes
x-goog-project-id	The project ID of a project.	Yes

Request Body Elements

This request does not include an XML document in the request body.

Request Syntax

GET / HTTP/1.1
Host: storage.googleapis.com
Date: <date>
Authorization: <authentication string>
Content-Length: <request body length>
x-goog-project-id: <project id>

Response Details

Response Headers

The request can return a variety of response headers depending on the request headers you use.

Response Body Elements

Element	Description
ListAllMyBucketsResult	Container for bucket information.
Owner	Container for bucket owner information.
ID	Google Cloud Storage ID of the bucket owner.
DisplayName	Not currently implemented. The value is always an empty string.
Buckets	Container for information about the owner's buckets.
Bucket	Container for information about a specific bucket.
Name	Name of the bucket.
CreationDate	Creation date for the bucket.

Status Code Details

If the GET Service request fails, it returns a 403 Forbidden status code. The body of the error response will also contain a message describing the reason why the request failed.

Sample Request and Response

The following sample lists the buckets in the specified project.

Sample Request

GET / HTTP/1.1
Host: storage.googleapis.com
Date: Mon, 15 Feb  2010 11:00:00 GMT
Content-Length: 0
x-goog-project-id: 123456789123
Authorization: <authentication string>

Sample Response

HTTP/1.1 200 OK
Content-Length: 648
Content-Type: application/xml
Date: Mon, 15 Feb  2010 11:00:01 GMT

<?xml version='1.0' encoding='utf-8'?>
<ListAllMyBucketsResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Owner>
    <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
    <DisplayName></DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <Name>city-maps</Name>
      <CreationDate>2009-12-16T18:36:25.369Z</CreationDate>
    </Bucket>
    <Bucket>
      <Name>state-maps</Name>
      <CreationDate>2009-12-16T18:42:37.408Z</CreationDate>
    </Bucket>
    <Bucket>
      <Name>country-maps</Name>
      <CreationDate>2010-01-22T01:27:03.633Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

Comments

The GET Service method is a simple GET request without a bucket or object scope. The request returns the list of buckets in an XML document in the response body. The request must be authenticated (anonymous requests will fail). By default, only the project owners group can list buckets because they are the owner of all buckets within the project. The project team and project editors groups have only view or write access to buckets, respectively.

Back to top

DELETE Bucket

Deletes an empty bucket.

Request Details

Query String Parameters

This request does not use query string parameters.

Request Headers

Header	Description	Required
Authorization	The authentication string for the request.	Yes
Content-Length	The length of the request body without headers (in bytes).	Yes
Date	The date and time of the request.	Yes
Host	The URI for Google Cloud Storage.	Yes

Request Body Elements

This request does not include an XML document in the request body.

Request Syntax

DELETE / HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Authorization: <authentication string>
Content-Length: <request body length>

Response Details

Response Headers

The request can return a variety of response headers depending on the request headers you use.

Response Body Elements

The response does not include an XML document in the response body.

Status Code Details

If there are objects in the bucket when you attempt to delete it you will get a 409 Conflict status code and the body of the error response will contain BucketNotEmpty in the Code element.

If the bucket does not exist you will get a 404 Not Found status code and the body of the error response will contain NoSuchBucket in the Code element.

Sample Request and Response

The following sample deletes a bucket named travel-maps.

Sample Request

DELETE / HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Mon, 15 Feb  2010 11:00:00 GMT
Content-Length: 0
Authorization: <authentication string>

Sample Response

HTTP/1.1 204 No Content
Date: Mon, 15 Feb  2010 11:00:01 GMT
Expires: Mon, 15 Feb  2010 11:00:01 GMT

Comments

The DELETE Bucket method is a simple DELETE request with bucket scope. You must be a member of the project owners group to delete buckets. Also, all DELETE Bucket requests must be authenticated.

As a best practice, after you delete all of the objects from a bucket you should set the bucket ACLs so that no users can create objects in the bucket.

Back to top

GET Bucket

Lists the objects that are in a bucket, as well as a bucket's configuration including ACL , CORS , Lifecycle , Logging , and Object Versioning .

Request Details

Query String Parameters

Parameter	Description	Required
acl	You can use this to display the ACLs of an existing bucket.	No
cors	You can use this to display the CORS configuration of an existing bucket.	No
delimiter	A character or multiple characters that can be used to simplify a list of objects that use a directory-like naming scheme. Can be used in conjunction with a prefix .	No
generation-marker	The object generation after which you want to start listing objects. If you use generation-marker, you must also use marker.	No
lifecycle	You can use this to display the lifecycle configuration of an existing bucket.	No
location	You can use this to display the location of the bucket. For a list of locations, see Specifying Bucket Location .	No
logging	You can use this only to display the logging configuration of an existing bucket.	No
marker	The object name after which you want to start listing objects.	No
max-keys	The maximum number of objects to return in a list object request.	No
prefix	A string that can be used to limit the number of objects that are returned in a GET Bucket request. Can be used in conjunction with a delimiter .	No
storageClass	You can use this to display the storage class of the bucket, STANDARD or DURABLE_REDUCED_AVAILABILITY.	No
versioning	You can use this to display the versioning configuration of an existing bucket.	No
versions	If specified on a versioned bucket, returns the list of all object versions. If omitted, only lists current versions.	No

Request Headers

Header	Description	Required
Authorization	The authentication string for the request.	Yes
Content-Length	The length of the request body without headers (in bytes).	Yes
Date	The date and time of the request.	Yes
Host	The URI for Google Cloud Storage.	Yes

Request Body Elements

This request does not include an XML document in the request body.

Request Syntax

The following syntax applies to GET Bucket requests that use the acl query string parameter.

GET /?acl HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>

The following syntax applies to GET Bucket requests that use the cors query string parameter.

GET /?cors HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>

The following syntax applies to GET Bucket requests that use the lifecycle query string parameter.

GET /?lifecycle HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>

The following syntax applies to GET Bucket requests that use the location query string parameter.

GET /?location HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>

The following syntax applies to GET Bucket requests that use the logging query string parameter.

GET /?logging HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>

The following syntax applies to GET Bucket requests that use the storageClass query string parameter.

GET /?storageClass HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>

The following syntax applies to GET Bucket requests that use the versioning query string parameter.

GET /?versioning HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>

The following syntax applies to GET Bucket requests that use either no parameters, or one or more of the delimiter , generation-marker , marker , max-keys , prefix , and versions query string parameters.

GET /?prefix=a_prefix&marker=a_marker&max-keys=max_number_of_keys&delimiter=a_delimiter HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>

Response Details

Response Headers

The request can return a variety of response headers depending on the request headers you use.

Response Body Elements

The following response body elements are applicable only if you use either no parameters, or one or more of the delimiter , generation-marker , marker , max-keys , prefix , or versions query string parameters to list objects in a bucket.

Element	Description
ListBucketResult	Container for the object information you are requesting.
Name	The bucket name.
CommonPrefixes	Container for prefixes that satisfy your prefix and delimiter constraints. This container is used only if you specify a delimiter and a prefix in the request.
Delimiter	The delimiter that you specified in the request.
MaxKeys	The max-keys that you specified in the request.
Prefix	The prefix that you specified in the request.
GenerationMarker	The generation-marker that you specified in the request.
NextGenerationMarker	If the list of returned objects is incomplete and versions parameter was used, NextGenerationMarker provides the generation of the last object that was returned. If the list is already complete, NextGenerationMarker is not returned.
Marker	The marker that you specified in the request.
NextMarker	NextMarker provides the name of the last object that was returned. The value of NextMarker can be provided in the marker query string parameter in a future GET Bucket call to continue listing the Bucket after this set of results. If there are no more objects in the Bucket that follow the last object in the list, NextMarker is not returned.
IsTruncated	Indicates whether or not all of the objects in a bucket appear on the list. If max-keys is less than the number of objects in a bucket, this element is True.
Contents	Container for object information if versions query parameter is not used.
Version	Container for object information if versions query parameter is used.
Key	The name of an object.
Generation	The generation of the object.
MetaGeneration	Generation of the metadata of the object.
IsLatest	If versions query parameter specified, this is set to true if the object is currently live. Live meaning that if this object is requested without generation, this object is returned.
LastModified	The date and time that an object was last modified.
DeletedTime	If versions query parameter was specified, contains the date and time that an object was overwritten or deleted for non-current objects.
ETag	An HTTP 1.1 entity tag for the object.
Size	Size of the object in bytes.
StorageClass	STANDARD or DURABLE_REDUCED_AVAILABILITY.
Owner	Container for object owner information.
ID	A Google Storage ID.
DisplayName	Not currently implemented.

The following response body elements are applicable only if you use the acl query string parameter to list a bucket's ACLs.

Element	Description
Owner	Container for bucket owner information.
ID	The Google Storage ID of the bucket owner or the Google Storage ID of the user or group for whom the ACLs apply.
Name	Comment field for GroupByEmail , GroupById , UserByEmail , and UserById .
AccessControlList	Container for the ACLs you are retrieving.
Entries	Container for the ACL entries you are retrieving.
Entry	The ACL entry you are retrieving.
Scope	The scope to which the ACLs apply.
Permission	The permission that has been granted. Can be any of the Google Cloud Storage permissions, including READ , WRITE , or FULL_CONTROL
EmailAddress	A Google account email address or a Google group email address.
Domain	A Google Apps domain.

The following response body elements are applicable only if you use the cors query string parameter to get the bucket's CORS configuration.

Element	Description
CorsConfig	Container for one or more Cors configuration containers. If you specify multiple Cors configurations, be aware that the Cors configurations will be evaluated in the order listed within the CorsConfig container, with the first Cors configuration matching the Origin and Method of the request used to determine any CORS response headers to add to the response.
Cors	Container for a CORS configuration to be applied to the bucket.You can specify multiple Origins and multiple Methods in each Cors container. There will be a match if the request Origin matches any of the Origins in the Cors container and the request Method matches any of the Methods in the Cors container.

The following response body elements are applicable only if you use the lifecycle query string parameter to display the bucket's lifecycle configuration.

The following response body elements are applicable only if you use the location query string parameter to display the bucket's location constraint.

The following response body elements are applicable only if you use the logging query string parameter to display the bucket's logging configuration.

The following response body elements are applicable only if you use the storageClass query string parameter to display how data is stored in the bucket.

The following response body elements are applicable only if you use the versioning query string parameter to display bucket's object versioning configuration.

Status Codes

If you make a GET request that's scoped to a bucket that doesn't exist, you will get a 404 Not Found status code and the body of the error response will contain NoSuchBucket in the Code element.

Sample Request and Response

The following sample lists the objects in a bucket named travel-maps.

Sample Request

GET / HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Wed, 17 Feb 2010 15:31:56 GMT
Content-Length: 0
Content-Type: text/plain
Authorization: <authentication string>

Sample Response

HTTP/1.1 200 OK
 Content-Length: 4061
 Content-Type: application/xml
 Date: Wed, 17 Feb 2010 23:31:57 GMT
 Expires: Wed, 17 Feb 2010 23:31:57 GMT

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>travel-maps</Name>
  <Prefix></Prefix>
  <Marker></Marker>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/france/cannes.pdf</Key>
    <Generation>1360887759327000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T22:11:12.487Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>europe/france/paris.pdf</Key>
    <Generation>1360887759329000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T22:09:57.457Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>

The following sample lists the objects in travel-maps, but it restricts the list to 25 objects that begin with the letter "t" and come after "test".

Sample Request

GET /?prefix=t&marker=test&max-keys=25 HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Mon, 16 Feb 2010 22:58:38 GMT
Content-Length: 0
Authorization: <authentication string>

Sample Response

HTTP/1.1 200 OK
Date: Mon, 15 Feb 2010 12:30:40 GMT
Content-Length: 2705
Content-Type: application/xml

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>travel-maps</Name>
  <Prefix>t</Prefix>
  <Marker>test</Marker>
  <MaxKeys>25</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>test_a.jpg</Key>
    <Generation>1360887659329000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:55.561Z</LastModified>
    <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
    <Size>328</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>test_b.jpg</Key>
    <Generation>1360887659323000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:54.606Z</LastModified>
    <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
    <Size>328</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>test_c.jpg</Key>
    <LastModified>2010-02-17T03:12:53.734Z</LastModified>
    <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
    <Size>328</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>

The following example uses a prefix and a delimiter to return a list of objects that are named using a directory-like schema. The prefix and delimiter restrict the list of objects so that only those objects that are in the europe directory are returned. Objects that are in subdirectories of the europe directory are not listed.The sample assumes that the following objects are contained in a bucket named travel-maps:

• africa/ghana.jpg
• africa/egypt/cairo.jpg
• europe/finland.jpg
• europe/norway.jpg
• europe/france/paris.jpg
• europe/italy/rome.jpg
• europe/sweden/stockholm.jpg
• europe/sweden/stockholm/nordic_museum.jpg

The sample request returns an XML document that lists the following two objects in the Contents element:

• europe/finland.jpg
• europe/norway.jpg

The following europe subdirectories are listed in the CommonPrefixes element:

• europe/france/
• europe/italy/
• europe/sweden/

Sample Request

GET /travel-maps?delimiter=/&prefix=europe/ HTTP/1.1
Host: storage.googleapis.com
Date: Mon, 16 Feb 2010 22:58:38 GMT
Content-Length: 0
Authorization: <authentication string>

Sample Response

HTTP/1.1 200 OK
Date: Mon, 15 Feb 2010 12:30:40 GMT
Content-Length: 1200
Content-Type: application/xml

<?xml version="1.0"?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>mybucket</Name>
  <Prefix>europe/</Prefix>
  <Marker />
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/finland.jpg</Key>
    <Generation>1360887659323000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:55.561Z</LastModified>
    <ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag>
    <Size>10</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
    </Owner>
  </Contents>
  <Contents>
    <Key>europe/norway.jpg</Key>
    <Generation>1360887659323000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:55.561Z</LastModified>
    <ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag>
    <Size>10</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
    </Owner>
  </Contents>
  <CommonPrefixes>
    <Prefix>europe/france/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>europe/italy/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>europe/sweden/</Prefix>
  </CommonPrefixes>
</ListBucketResult>

Comments

You can use the GET Bucket method to list the objects that are contained in a bucket; or to display a bucket's ACLs, CORS configuration, lifecycle configuration, logging configuration, or versioning configuration.

• To list the objects in a bucket you make a GET request that is scoped to a bucket. You can also use query string parameters to further scope the request. The request returns the list of objects in an XML document in the response body.
• To list a bucket's ACLs you make a GET request that is scoped to a bucket and you use the acl query string parameter. The ACLs are returned in an XML document in the response body.
• To display a bucket's CORS configuration you make a GET request that is scoped to a bucket and you use the cors query string parameter. The CORS configuration is returned in an XML document in the response body.
• To list a bucket's lifecycle configuration you make a GET request that is scoped to a bucket and you use the lifecycle query string parameter. The lifecycle configuration is returned in an XML document in the response body.
• To list a bucket's logging configuration you make a GET request that is scoped to a bucket and you use the logging query string parameter. The logging configuration is returned in an XML document in the response body.
• To list a bucket's versioning configuration you make a GET request that is scoped to a bucket and you use the versioning query string parameter. The versioning configuration is returned in an XML document in the response body.

You must have bucket READ permission to get the list of objects that are in a bucket, and you must have bucket FULL_CONTROL permission to list a bucket's ACLs or CORS.

You can restrict and organize the list of objects that is returned in a GET Bucket request by using the delimiter , marker , max-keys , and prefix query string parameters. The marker query string parameter is a string of Unicode characters that specifies the object after which you want to start listing objects. Any objects whose names are lexicographically greater than the marker are returned in the list of objects. The max-keys query string parameter is an integer that specifies the maximum number of objects you want returned in the list of objects. If a request can return more objects than max-keys allows, the IsTruncated response element contains a True value and the NextMarker response element returns the name of the last object in the list. The returned NextMarker value can then be used as the new marker in another request.

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.

The delimiter is a single character or multiple characters and is used to simplify a list of objects that use a directory-like naming scheme. For more information about using a delimiter , see delimiter .

Google Cloud Storage does not return lists longer than 1,000 objects.

Back to top

HEAD Bucket

Indicates if a bucket exists and whether the requester has READ access to it.

Request Details

Query String Parameters

This request does not include query string parameters.

Request Headers

Request Body Elements

This request does not include an XML document in the request body.

Request Syntax

HEAD / HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: 0
Authorization: <authentication string>

Response Details

Response Headers

The request returns standard response headers.

Response Body Elements

The response does not include an XML document in the response body. Error responses to HEAD requests also do not contain a response body.

Status Codes

If the bucket does not exist, Google Cloud Storage returns a 404 Not Found status code.

Sample Request and Response

The following sample shows a HEAD request for a bucket named travel-maps.

Sample Request

HEAD / HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Fri, 19 Feb 2010 22:04:21 GMT
Authorization: <authentication string>
Content-Length: 0

Sample Response

HTTP/1.1 200 OK
Last-Modified: Fri, 19 Feb 2010 22:04:23 GMT
Date: Fri, 19 Feb 2010 22:13:49 GMT

Comments

None.

Back to top

PUT Bucket

Creates a bucket in a specified project and optionally applies ACLs, CORS, Lifecycle, Logging, or Versioning configuration to a bucket. (You can only apply one of ACLs, CORS, Lifecycle, Logging, or Versioning configuration in a single request, however.)

You can specify the geographic location for your bucket by providing a location constraint. This tells Google Cloud Storage to store the bucket and its contents on a server in the specified location. For more information, see Specifying Bucket Locations .

Request Details

Query String Parameters

Request Headers

Request Body Elements for ACL

Note: To see how these elements are nested, see the ACL syntax diagram .

The following request body elements are applicable only if you use the acl query string parameter to apply ACLs to an existing bucket.

Request Body Elements for CORS

The following diagram shows the nesting of XML elements in the CORS configuration. See the table below the diagram for additional details.

The following request body elements are applicable only if you use the cors query string parameter to specify CORS for an existing bucket.

Request Body Elements for Lifecycle

The following request body elements are applicable only if you use the lifecycle query string parameter to specify the lifecycle configuration for an existing bucket.

Request Body Elements for Logging

The following request body elements are applicable only if you use the logging query string parameter to specify logging configuration for an existing bucket.

Request Body Elements for Versioning

The following request body elements are applicable only if you use the versioning query string parameter to specify versioning configuration for an existing bucket.

Request Body Elements for Website Configuration

The following request body elements are applicable only if you use the websiteConfig query string parameter to specify a website configuration for an existing bucket.

Request Syntax

The following syntax applies to PUT Bucket requests that don't use the acl , cors , logging , versioning , or websiteConfig query string parameter.

PUT / HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>
x-goog-project-id: <project id>
x-goog-acl: <predefined ACL>

The following syntax applies to PUT Bucket requests that use the acl query string parameter.

PUT /?acl HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date and time of the request>
Content-Length: <request body length>
Content-Type: <MIME type of the body>
Authorization: <authentication string>
x-goog-project-id: <project id>

<xml_document_defining_acls>

The following syntax applies to PUT Bucket requests that use the cors query string parameter.

PUT /?cors HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date and time of the request>
Content-Length: <request body length>
Content-Type: <MIME type of the body>
Authorization: <authentication string>
x-goog-project-id: <project id>

<xml_document_defining_cors>

The following syntax applies to PUT Bucket requests that use the lifecycle query string parameter.

PUT /?lifecycle HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date and time of the request>
Content-Length: <request body length>
Content-Type: <MIME type of the body>
Authorization: <authentication string>
x-goog-project-id: <project id>

<xml_document_defining_lifecycle_configuration>

The following syntax applies to PUT Bucket requests that use the logging query string parameter.

PUT /?logging HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date and time of the request>
Content-Length: <request body length>
Content-Type: <MIME type of the body>
Authorization: <authentication string>
x-goog-project-id: <project id>

<xml_document_defining_logging>

The following syntax applies to PUT Bucket requests that use the versioning query string parameter.

PUT /?versioning HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date and time of the request>
Content-Length: <request body length>
Content-Type: <MIME type of the body>
Authorization: <authentication string>
x-goog-project-id: <project id>

<xml_document_defining_versioning>

The following syntax applies to PUT Bucket requests that use the websiteConfig query string parameter.

PUT /?websiteConfig HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date and time of the request>
Content-Length: <request body length
Content-Type: <MIME type of the body
Authorization: <authentication string
x-goog-project-id: <project id>

<xml_document_defining_website_config>

Note: Optionally, when you create a bucket, you can specify a geographical location where your bucket is stored by providing a location constraint. For more information, see Specifying Bucket Locations .

Response Details

Response Headers

The request can return a variety of response headers depending on the request headers you use.

Response Body Elements

The response does not include an XML document in the response body.

Status Codes

If you try to create a bucket with an invalid name you will get a 400 Bad Request status code and the body of the error response will have InvalidBucketName in the Code element.

Also, because the bucket namespace is global, your bucket name must be unique across the entire Google Cloud Storage namespace. If your bucket name is in use, you will get a 409 Conflict status code and the bucket creation request will fail. The body of the error response will contain BucketAlreadyExists in the Code element if the bucket already exists in the namespace or it will contain a BucketAlreadyOwnedByYou in the Code element if the bucket is owned by you. For more information about bucket and object naming, see Bucket and Object Naming Guidelines .

Sample Request and Response

The following sample creates a bucket named acme-pets in the specified project.

Sample Request

PUT / HTTP/1.1
Host: acme-pets.storage.googleapis.com
Date: Mon, 15 Feb  2008 21:30:39 GMT
Content-Length: 0
x-goog-project-id: 123456789123
Authorization: <authentication string>

Sample Response

HTTP/1.1 200 OK
Date: Mon, 15 Feb 2010 12:30:40 GMT
Content-Length: 0

The following sample applies ACLs to a bucket named acme-pets. The ACLs grant WRITE permission to members of the Google Storage (a Google group). Granting WRITE permission to the group lets each group member upload objects to the acme-pets bucket, delete objects in the acme-pets bucket, and list objects in the acme-pets bucket. The ACLs also grant [email protected] FULL_CONTROL of the acme-pets bucket, which lets Jane upload objects, delete objects, list objects, and modify ACLs on the acme-pets bucket.

Sample Request

PUT /?acl HTTP/1.1
Host: acme-pets.storage.googleapis.com
Date: Thu, 10 Jun 2010 03:38:42 GMT
Content-Length: 705
Authorization: <authentication string>

<?xml version="1.0" encoding="UTF-8"?>
<AccessControlList>
  <Owner>
  <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
    <Name></Name>
  </Owner>
  <Entries>
    <Entry>
      <Scope type="UserById">
        <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
        <Name></Name>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="UserByEmail">
        <EmailAddress>[email protected]</EmailAddress>
        <Name></Name>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupByEmail">
        <EmailAddress>[email protected]</EmailAddress>
      </Scope>
      <Permission>WRITE</Permission>
    </Entry>
  </Entries>
</AccessControlList>

The following sample sets a CORS configuration on a bucket named acme-pets. This CORS configuration sets two origins and the HTTP methods allowed for those origins. In this example, all of the available HTTP methods are allowed.

Sample Request

PUT /?cors HTTP/1.1
Host: acme-pets.storage.googleapis.com
Date: Thu, 12 Mar 2012 03:38:42 GMT
Content-Length: 1320
Authorization: <authentication string>

<?xml version="1.0" encoding="UTF-8"?>
<CorsConfig>
  <Cors>
    <Origins>
      <Origin>http://origin1.example.com</Origin>
      <Origin>http://origin2.example.com</Origin>
    </Origins>
    <Methods>
      <Method>GET</Method>
      <Method>HEAD</Method>
      <Method>PUT</Method>
      <Method>POST</Method>
      <Method>DELETE</Method>
    </Methods>
    <ResponseHeaders>
      <ResponseHeader>x-goog-meta-foo1</ResponseHeader>
      <ResponseHeader>x-goog-meta-foo2</ResponseHeader>
    </ResponseHeaders>
    <MaxAgeSec>1800</MaxAgeSec>
  </Cors>
</CorsConfig>

Sample Response

HTTP/1.1 200 OK
Date: Thu, 12 Mar 2012 03:38:42 GMT
Expires: Fri, 01 Jan 1990 00:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 0
Content-Type: text/html

The following sample enables lifecycle management for a bucket named example.com.

Sample Request

PUT /example.com?lifecycle HTTP/1.1
Host: storage.googleapis.com
Content-Length: 220
Authorization: <authentication string>

<?xml version="1.0" ?>
<LifecycleConfiguration>
    <Rule>
        <Action>
            <Delete/>
        </Action>
        <Condition>
            <Age>30</Age>
        </Condition>
    </Rule>
</LifecycleConfiguration>

Sample Response

HTTP/1.1 200 OK
Date: Thu, 12 Mar 2012 03:38:42 GMT
Expires: Fri, 01 Jan 1990 00:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 0
Content-Type: text/html

The following sample enables Logging for a bucket named example.com.

Sample Request

PUT /example.com?logging HTTP/1.1
Host: storage.googleapis.com
Content-Length: 131
Authorization: <authentication string>

<Logging>
    <LogBucket>
        logs-bucket
    </LogBucket>
    <LogObjectPrefix>
        my-logs-enabled-bucket
    </LogObjectPrefix>
</Logging>

Sample Response

HTTP/1.1 200 OK
Date: Thu, 12 Mar 2012 03:38:42 GMT
Expires: Fri, 01 Jan 1990 00:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 0
Content-Type: text/html

The following sample turns on Object Versioning on a bucket named acme-pets.

Sample Request

PUT /?versioning HTTP/1.1
Host: acme-pets.storage.googleapis.com
Date: Thu, 12 Mar 2012 03:38:42 GMT
Content-Length: 1320
Authorization: <authentication string>

<?xml version="1.0" encoding="UTF-8"?>
<VersioningConfiguration><Status>Enabled</Status></VersioningConfiguration>

Sample Response

HTTP/1.1 200 OK
Date: Thu, 12 Mar 2012 03:38:42 GMT
Expires: Fri, 01 Jan 1990 00:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 0
Content-Type: text/html

Comments

You can use the PUT Bucket method to

• Create a bucket .
• Set or modify ACLs on an existing bucket.
• Set or modify CORS on an existing bucket.
• Set or modify lifecycle configuration on an existing bucket.
• Set or modify logging on an existing bucket.
• Set or modify versioning on an existing bucket.

Create a Bucket

To create a bucket, you make a PUT request that is scoped with the new bucket's name.

Set or Modify an ACL On a Bucket

To set or modify the ACLs on an existing bucket you make a PUT request that is scoped to the bucket and you use the acl query string parameter. You must include an XML document in the request body that contains the ACL settings you want to apply. Notice that you cannot set the ACLs on a new bucket you are creating. (When you create a new bucket, the default ACL (project-private) is automatically applied to the bucket.)

You must have FULL_CONTROL permission to apply ACLs to an existing bucket. Also, you must be authenticated to use the PUT Bucket method. Anonymous bucket creation requests will fail.

Note: You can also set the ACLs on an existing bucket to a predefined (canned) ACL by using the x-goog-acl request header in conjunction with the acl query string parameter. You must include an XML document with the request and you must specify a predefined ACL in the request. When you do this, the x-goog-acl header takes precedence over the acl query string parameter and the predefined ACL is applied to the bucket.

Set or Modify CORS

By default, buckets do not have any CORS configuration set. To set or modify CORS for an existing bucket you make a PUT request that is scoped to the bucket and you use the cors query string parameter. You must include an XML document in the request body that contains one or more CORS configurations that you want to apply. Notice that you cannot set CORS configuration on a new bucket that you are creating.

You must have FULL_CONTROL permission to apply a CORS configuration to an existing bucket. Also, you must be authenticated to use the PUT Bucket method.

Set or Modify Lifecycle Configuration

By default, buckets do not have lifecycle management enabled. To set or modify lifecycle configuration for an existing bucket you make a PUT request that is scoped to the bucket and you use the lifecycle query string parameter. You must include an XML document in the request body that contains the lifecycle configuration. Notice that you cannot set lifecycle configuration on a new bucket that you are creating.

You must have FULL_CONTROL permission to set or modify lifecycle configuration for an existing bucket. Also, you must be authenticated to use the PUT Bucket method.

Set or Modify Logging

By default, buckets do not have logging enabled. To set or modify logging configuration for an existing bucket you make a PUT request that is scoped to the bucket and you use the logging query string parameter. You must include an XML document in the request body that contains the logging configuration. Notice that you cannot set logging configuration on a new bucket that you are creating.

You must have FULL_CONTROL permission to set or modify logging configuration for an existing bucket. Also, you must be authenticated to use the PUT Bucket method.

Set or Modify Versioning

By default, buckets do not have versioning enabled. To set or modify versioning configuration for an existing bucket you make a PUT request that is scoped to the bucket and you use the versioning query string parameter. You must include an XML document in the request body that contains the versioning configuration that you want to apply. Notice that you cannot set versioning configuration on a new bucket that you are creating.

You must have FULL_CONTROL permission to set or modify versioning configuration for an existing bucket. Also, you must be authenticated to use the PUT Bucket method.

Back to top

DELETE Object

Deletes an object.

Request Details

Query String Parameters

Request Headers

Request Body Elements

This request does not include an XML document in the request body.

Request Syntax

DELETE /object HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>

Response Details

Response Headers

The request can return a variety of response headers depending on the request headers you use.

Response Body Elements

The response does not include an XML document in the response body.

Status Code Details

If you successfully delete an object, Google Cloud Storage returns a 204 No Content status code. If you attempt to delete a nonexistent object, Google Cloud Storage returns a 404 Not Found status code

Sample Request and Response

The following sample deletes an object named paris.jpg.

Sample Request

DELETE /paris.jpg HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Mon, 15 Feb  2010 11:00:00 GMT
Content-Length: 0
Authorization: <authentication string>

Sample Response

HTTP/1.1 204 No Content
Date: Mon, 15 Feb  2010 11:00:01 GMT

Comments

The DELETE Object method is a simple DELETE request with bucket and object scope. To delete an object, you must have WRITE permission for the bucket in which the object is stored. Anonymous users can delete an object without authenticating if the bucket ACLs grant them WRITE or FULL_CONTROL permission. All other DELETE requests must be authenticated.

For more information about using the DELETE Object method, see the API Overview .

Back to top

GET Object

Downloads an object or lists an object's ACLs.

Request Details

Query String Parameters

Request Headers

Request Body Elements

This request does not include an XML document in the request body.

Request Syntax

The following syntax applies to GET Object requests that don't use the acl query string parameter.

GET /object HTTP/1.1
Host: bucket.storage.googleapis.com
Content-Length: <request body length>
Authorization: <authentication string>
Range: <bytes=byte range>
If-Match: <entity tag>
If-Modified-Since: <date>
If-None-Match: <entity tag>
If-Unmodified-Since: <date>

The following syntax applies to GET Object requests that use the acl query string parameter.

GET /object?acl HTTP/1.1
Host: bucket.storage.googleapis.com
Content-Length: <request body length>
Content-Type: <type>
Authorization: <authentication string>

Response Details

Response Headers

The request can return a variety of response headers depending on the request headers you use, including: Cache-Control , Content-Length , Content-Type , Content-Disposition , ETag , and Last-Modified.

Response Elements

The following response body elements are applicable only if you use the acl query string parameter to list an object's ACLs.

Status Codes

If the object does not exist you will get a 404 Not Found status code and the body of the error response will have NoSuchKey in the Code element.

Sample Request and Response

The following sample lists the ACLs for an object named paris.jpg that is in a bucket named travel-maps. In this sample, every user account that is in the example.com domain has READ permission on the object, which means any user who can sign in with an @example.com email address can download the paris.jpg object. To specify a domain as a scope, the domain must be associated with a Google Apps account. The ACL also grants a user FULL_CONTROL permission on the paris.jpg object, which lets that user download the object and change the ACLs on the object. The user is represented by their Google Storage ID.

Sample Request

GET /paris.jpg?acl HTTP/1.1
Host: travel-maps.storage.googleapis.com
Content-Length: 0
Authorization: <authentication string>

Sample Response

HTTP/1.1 200 OK
Content-Length: 485
Content-Type: application/xml
Date: Fri, 19 Feb 2010 14:05:08 GMT

<?xml version="1.0" encoding="UTF-8"?>
<AccessControlList>
  <Owner>
    <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
    <Name></Name>
  </Owner>
  <Entries>
    <Entry>
      <Scope type="UserById">
        <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
        <Name></Name>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="UserById">
        <ID>76fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da79</ID>
        <Name>[email protected]</Name>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupByDomain">
        <Domain>example.com</Domain>
      </Scope>
      <Permission>READ</Permission>
    </Entry>
    </Entries>
  </AccessControlList>

The following sample downloads an object named paris.jpg that's in a bucket named travel-maps.

Sample Request

GET /paris.jpg HTTP/1.1
Host: travel-maps.storage.googleapis.com
Content-Length: 0
Authorization: <authentication string>

Sample Response

HTTP/1.1 200 OK
Content-Type: image/jpg
Last-Modified: Fri, 19 Feb 2010 22:13:49 GMT
ETag: "2281880ef78388266ecd7d4c1b472a0e"
Content-Length: 328
Date: Fri, 19 Feb 2010 22:13:49 GMT

328 bytes of data...

Comments

You can use the GET Object method to download an object or list an object's ACLs. To download an object you make a GET request that is scoped to a bucket and object. You can also use various request headers to further scope the request. The request returns the object's contents in the response body. To list an object's ACLs you make a GET request that is scoped to a bucket and object and you use the acl query string parameter. The ACLs are returned in an XML document in the response body.

You must have READ permission to download an object, and you must have FULL_CONTROL permission to retrieve an object's ACLs.

GET requests for objects can include a Range header as defined in the HTTP 1.1 RFC to limit the scope of the returned data within the object. Requests can also include If-Modified-Since or If-Unmodified-Since headers, causing the response to omit the body if the object has not been modified, or has been modified, since a specified timestamp. If the object does not meet an If-Modified-Since header condition, the response is a 304 Not Modified, and if the object fails to meet an If-Unmodified-Since header condition, the response is 412 Precondition Failed. Similarly, requests can include If-Match and If-None-Match headers with an ETag to match. If the object does not match an If-Match header condition, the response is 412 Precondition Failed, and if the object matches the given hash in an If-None-Match header, the response is 304 Not Modified.

For more information about using the Get Object method, see the API Overview .

Back to top

HEAD Object

Lists metadata for an object.

Request Details

Query String Parameters

Request Headers

Request Body Elements

This request does not include an XML document in the request body.

Request Syntax

HEAD /object HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>
Range: <bytes=byte range>
If-Match: <entity tag>
If-Modified-Since: <date>
If-None-Match: <entity tag>
If-Unmodified-Since: <date>

Response Details

Response Headers

The request can return a variety of response headers depending on the request headers you use, including: Cache-Control , Content-Length , Content-Type , Content-Disposition , ETag , and Last-Modified.

Response Body Elements

The response does not include an XML document in the response body. Error responses to HEAD requests also do not contain a response body.

Status Codes

If the object does not exist, Google Cloud Storage returns a 404 Not Found status code.

Sample Request and Response

The following sample gets metadata for an object named paris.jpg that's in a bucket named travel-maps.

Sample Request

HEAD /paris.jpg HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Fri, 19 Feb 2010 22:04:21 GMT
Authorization: <authentication string>
Content-Length: 0

Sample Response

HTTP/1.1 200 OK
Content-Type: application/rtf
Last-Modified: Fri, 19 Feb 2010 22:04:23 GMT
ETag: "2281880ef78388266ecd7d4c1b472a0e"
Content-Length: 328
Date: Fri, 19 Feb 2010 22:13:49 GMT

Comments

None.

Back to top

POST Object

Uploads objects by using HTML forms.

Note: Unless you need to use HTML forms (usually through a web browser) to upload objects, we strongly recommend using PUT object instead of POST.

Request Details

Query String Parameters

This request does not use query string parameters.

Form Fields

Response Details

Response Body Elements

The following response body elements are returned in an XML document only if you set success_action_redirect to 201.

Status Codes

There are no special status codes associated with this request method.

Comments

The form must be UTF-8 encoded. You can specify form encoding in the form's HTML head tag or by using the Content-Type request header.

Your form tag must specify the following three items:

• An action.

  The action attribute specifies the bucket that you want the form to upload an object to.

• A method.

  The method attribute specifies the method that you are using to submit the form. It must be post .

• An enclosure type.

  The enctype attribute specifies the enclosure type you are using and must always be multipart/form-data .

Policy Document

A policy document defines what a user can upload with a form POST and provides authorization to ensure that the form can upload files into the target bucket. You do not need to include a policy document in a form if your form uploads files to a bucket that grants anonymous users WRITE permission.

A policy document is constructed in JavaScript Object Notation (JSON) and contains the following sections:

The conditions section must include a condition statement for every field in your HTML form except the GoogleAccessId (the email form of the client ID, as described in the section on Signed URLs ), signature , file , and policy fields. It is possible to express three types of conditions in your conditions section:

• Exact Matching

  Performs exact matching for a field. The value of the input field's value must match the specified expected value. You can specify this condition using either of the following syntax styles:

  {"<field>" : "<value>"}
  ["eq", "<field>", "<value>"]

  All valid policy document fields specified in the table below can use exact matching.

• Starts With

  If a value of a field must start with a certain value, you can use the starts-with condition. You can specify this condition using the following syntax:

  ["starts-with", "<field>", "<value>"]

  All valid policy document fields specified in the table below can use the starts-with condition.

• Content Length Range

  Specifies that uploaded files can only be between a certain size range in bytes. You can specify this condition using the following syntax:

  ["content-length-range", <min_range>, <max_range>]

You can express the following fields in the conditions section, using exact matching, content-length-range or starts-with conditions:

The following is an example of a typical policy document:

{"expiration": "2010-06-16T11:11:11Z",
 "conditions": [
  ["starts-with", "key", "" ],
  {"acl": "bucket-owner-read" },
  {"bucket": "travel-maps"},
  {"success_action_redirect": "http://www.example.com/success_notification.html" },
  ["eq", "Content-Type", "image/jpeg" ],
  ["content-length-range", 0, 1000000]
  ]
}

The previous policy document defines the following conditions:

• The form expires on June 16, 2010 at 11:11:11 UTC.
• The file name can start with any valid character. To specify this, you use the starts-with condition modifier and the empty string ("").
• The bucket-owner-read ACL is applied to the file.
• If the upload is successful, the user is redirected to http://www.example.com/success_notification.html .
• The form allows only images to be uploaded.
• A user cannot upload a file larger than 1 MB.

Note: The date and time in the expiration field must be represented in ISO 8601 format.

If you are including a policy document in your form, you must include a signature in the signature form field. The following procedure shows you how to create the signature:

1. Create a policy document for your form and make sure it is UTF-8 encoded.
2. Encode the policy document as a Base64 representation.
3. Sign your policy document using RSA with SHA256 using the secret key provided to you by the Google API Console.
4. Encode the message digest as a Base64 representation.

The following pseudocode combines the steps above to create your signature:

Policy = Base-64-Encoding-Of(PolicyDocument)
MessageDigest = SHA256withRSA(SecretKey, Policy)
Signature = Base64-Encoding-Of(MessageDigest)

The following is an example HTML using the policy document above:

<form action="http://travel-maps.storage.googleapis.com" method="post" enctype="multipart/form-data">
<input type="text" name="key" value="">
<input type="hidden" name="bucket" value="travel-maps">
<input type="hidden" name="Content-Type" value="image/jpeg">
<input type="hidden" name="GoogleAccessId" value="[email protected]">
<input type="hidden" name="acl" value="bucket-owner-read">
<input type="hidden" name="success_action_redirect" value="http://www.example.com/success_notification.html">
<input type="hidden" name="policy" value="eyJleHBpcmF0aW9uIjogIjIwMTAtMDYtMTZUMTE6MTE6MTFaIiwNCiAiY29uZGl0aW9ucyI6IFsNCiAgWyJzdGFydHMtd2l0aCIsICJrZXkiLCAiIiBdLA0KICB7ImFjbCI6ICJidWNrZXQtb3duZXItcmVhZCIgfSwNCiAgeyJidWNrZXQiOiAidHJhdmVsLW1hcHMifSwNCiAgeyJzdWNjZXNzX2FjdGlvbl9yZWRpcmVjdCI6ICJodHRwOi8vd3d3LmV4YW1wbGUuY29tL3N1Y2Nlc3Nfbm90aWZpY2F0aW9uLmh0bWwiIH0sDQogIFsiZXEiLCAiQ29udGVudC1UeXBlIiwgImltYWdlL2pwZWciIF0sDQogIFsiY29udGVudC1sZW5ndGgtcmFuZ2UiLCAwLCAxMDAwMDAwXQ0KICBdDQp9">
<input type="hidden" name="signature" value="BSAMPLEaASAMPLE6SAMPLE+SAMPPLEqSAMPLEPSAMPLE+SAMPLEgSAMPLEzCPlgWREeF7oPGowkeKk7J4WApzkzxERdOQmAdrvshKSzUHg8Jqp1lw9tbiJfE2ExdOOIoJVmGLoDeAGnfzCd4fTsWcLbal9sFpqXsQI8IQi1493mw=">

<input name="file" type="file">
<input type="submit" value="Upload">
</form>

As a best practice you should use the Expect: 100-continue header with POST requests. This allows you to verify that the server will handle the request before you send the object. If you receive a status code 100 Continue you should proceed with the request. If you receive a status code 417 Expectation Failed then you should not send the object.

Back to top

PUT Object

Creates a new object (via upload, copy, or compose), or applies object ACLs.

Request Details

Query String Parameters

Request Headers

Request Body Elements

The following request body elements are applicable only if you use the acl query string parameter to apply ACLs to an existing object.

The following request body elements are applicable only if you use the compose query string parameter to issue a compose request .

Request Syntax

The following syntax applies to PUT Object requests that don't use any query string parameters and exclude the x-goog-copy-source request header.

PUT /object HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Content-Type: <MIME type>
Content-MD5: <MD5 digest>
Authorization: <authentication string>
x-goog-acl: <predefined ACL>

The following syntax applies to PUT Object requests that use the x-goog-copy-source request header and the related conditional copy request headers.

PUT /object HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Content-Type: <MIME type>
Authorization: <authentication string>
x-goog-copy-source: </bucket/object>
x-goog-copy-source-if-match: <ETag>
x-goog-copy-source-if-none-match: <ETag>
x-goog-copy-source-if-unmodified-since: <date>
x-goog-copy-source-if-modified-since: <date>
x-goog-metadata-directive: <COPY | REPLACE>

The following syntax applies to PUT Object requests that use the acl query string parameter.

PUT /object?acl HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Content-Type: <MIME type>
Authorization: <authentication string>

<xml_document_defining_acls>

The following syntax applies to conditional PUT Object requests that use the acl query string parameter as well as generation and metageneration .

PUT /object?acl HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Content-Type: <MIME type>
Authorization: <authentication string>
x-goog-if-generation: <generation number>
x-goog-if-metageneration: <meta-generation number>

<xml_document_defining_acls>

The following syntax applies to conditional PUT Object for a history object that use the acl query string parameter as well as generation and metageneration .

PUT /object?acl&generation;=136088769710500 HTTP/1.1
Host: bucket.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Content-Type: <MIME type>
Authorization: <authentication string>
x-goog-if-metageneration: <meta-generation number>

<xml_document_defining_acls>

Response Details

Response Headers

The request can return a variety of response headers depending on the request headers you use.

Response Body Elements

The following response elements are returned when you use the x-goog-copy-source request header or any of the related conditional copy request headers.

Status Codes

If you try to upload an object into a bucket that does not exist you will get a 404 Not Found status code and the body of the error response will have NoSuchBucket in the Code element.

If the supplied MD5 digest is malformed you will get a 400 Bad Request status code and the body of the error response will have InvalidDigest in the Code element.

If the digest does not match the digest we compute from the body you will get a 400 Bad Request status code and the body of the error response will have BadDigest in the Code element.

If any of the conditional copy headers fail to match the condition you specify you will get a 412 Precondition Failed status code and the body of the error response will have PreconditionFailed in the Code element.

Sample Request and Response

The following sample uploads an object named paris.jpg to a bucket named travel-maps.

Sample Request

PUT /paris.jpg HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Sat, 20 Feb 2010 16:31:08 GMT
Content-Type: image/jpg
Content-MD5: iB94gawbwUSiZy5FuruIOQ==
Content-Length: 554
Authorization: <authentication string>

Sample Response

HTTP/1.1 200 OK
ETag: "881f7881ac1bc144a2672e45babb8839"
Date: Sat, 20 Feb 2010 16:31:09 GMT
Content-Length: 0
Content-Type: text/html

The following sample applies ACLs to the london.jpg object, which is stored in the travel-maps bucket. The ACLs grant [email protected] FULL_CONTROL permission, which lets Jane download london.jpg and change the ACLs on london.jpg. The ACLs also grant members of the Google Cloud Storage group READ permission to london.jpg, which lets each member of the group download london.jpg.

Sample Request

PUT /london.jpg?acl HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Sat, 20 Feb 2010 17:08:44 GMT
Content-Length: 682
Content-Type=application/xml; charset=UTF-8
Authorization: <authentication string>

<?xml version="1.0" encoding="UTF-8"?>
<AccessControlList>
  <Owner>
    <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
    <Name></Name>
  </Owner>
  <Entries>
    <Entry>
      <Scope type="UserById">
        <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
        <Name></Name>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="UserByEmail">
        <EmailAddress>[email protected]</EmailAddress>
        <Name></Name>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupByEmail">
        <EmailAddress>[email protected]</EmailAddress>
      </Scope>
      <Permission>READ</Permission>
    </Entry>
  </Entries>
</AccessControlList>

Sample Response

HTTP/1.1 200 OK
Date: Sat, 20 Feb 2010 17:08:45 GMT
Content-Length: 0
Content-Type: text/html

The following sample uses the x-goog-copy-source request header to copy an object named paris.jpg from a bucket named travel-maps to a bucket named city-maps.

Sample Request

PUT /paris.jpg HTTP/1.1
Host: city-maps.storage.googleapis.com
Date: Fri, 23 Jul 2010 21:27:36 GMT
Content-Length: 0
x-goog-copy-source: travel-maps/paris.jpg
Authorization: <authentication string>

Sample Response

HTTP/1.1 200 OK
ETag: "9930c6204b2f14e1a4496569dc200186"
Date: Fri, 23 Jul 2010 21:27:37 GMT
Expires: Fri, 01 Jan 1990 00:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 175
Content-Type: text/html

<?xml version='1.0' encoding='UTF-8'?>
<CopyObjectResult>
  <LastModified>2010-06-17T16:18:08.291Z</LastModified>
  <ETag>"9930c6204b2f14e1a4496569dc200186"</ETag>
</CopyObjectResult>

Comments

You can use the PUT Object method to upload an object, copy an object from one bucket to another bucket, or change the ACLs on an object. To upload an object, you make a PUT request that is scoped with a bucket name and the object's name, and you put the object data into the request body. To copy an object, you make a PUT request that is scoped to the new bucket and object name and you specify the source object with the x-goog-copy-source request header. To change the ACLs on an object you make a PUT request that is scoped to the bucket and object and you use the acl query string parameter. You must also include an XML document in the request body that contains the ACL settings you want to apply.

You can also specify ACLs when you upload an object. To do this you can use the x-goog-acl request header. When you use the x-goog-acl request header you can apply one of the predefined ACLs. If you don't use the x-goog-acl request header when you upload an object, the default ACL (private) is applied to the object.

Keep in mind, a bucket's ACLs determines whether a user has permission to upload objects into the bucket. If a bucket grants WRITE permission to anonymous users, then users can upload objects without authenticating. Otherwise, all upload requests must be authenticated and only those users with WRITE permission can upload objects into a bucket.

You must have FULL_CONTROL permission to apply ACLs to an existing object.

Note: You can also set the ACLs on an existing object to a predefined (canned) ACL by using the x-goog-acl request header in conjunction with the acl query string parameter. You must not include an XML document with the request and you must specify a predefined ACL in the request. When you do this, the x-goog-acl header takes precedence over the acl query string parameter and the predefined ACL is applied to the object.

The PUT Object request uses several standard HTTP headers. Content-Length specifies the object's size in bytes and is required unless you are using chunked transfer encoding. Optional headers include Cache-Control, Content-Type, Content-Disposition, Content-MD5, x-goog-acl, and metadata headers. Cache-Control, Content-Type, and Content-Disposition determine what Google Cloud Storage will set in response headers when users download the object. Content-MD5 validates that the uploaded data matches the user's data.

If you are using the PUT Object method to copy an object, you must have READ permission on the source object and you must have WRITE or FULL_CONTROL permission on the bucket to which you are copying the object. To copy an object to itself you must use the x-goog-metadata-directive header and you must specify REPLACE , which replaces all of the source object's metadata with whatever metadata you specify in the request. The x-goog-metadata-directive header also lets you copy the source object's metadata to the newly-created object as part of the copy operation. If you copy the metadata, 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. Also, during a copy operation the request body must be empty.

Back to top