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. For more information, see Request URIs.	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. For more information, see Request URIs.	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 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, NEARLINE 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. For more information, see Request URIs.	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 the object metadata 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 (if the bucket has versioning enabled).
ETag	An HTTP 1.1 entity tag for the object.
Size	Size of the object in bytes.
StorageClass	STANDARD, NEARLINE 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.
Origins	Container for the origins permitted for cross origin resource sharing with this Google Cloud Storage.
Origin	An Origin permitted for cross origin resource sharing with this Google Cloud Storage bucket. For example, http://origin1.example.com.
Methods	Container for one or more HTTP Method elements, specifying the methods supported by this CORS configuration.
Method	An HTTP method supported in this configuration. Valid values are GET, HEAD, PUT, POST, and DELETE.
ResponseHeaders	Optional container for one or more ResponseHeader elements.
ResponseHeader	Specifies a response header that the user agent is permitted to share across origins.
MaxAgeSec	A value indicating the number of seconds that the user agent is permitted to cache the response. This element is optional; if omitted, the service uses a default value. If specified more than once, the last element is silently accepted. The value is returned in the Access-Control-Max-Age header in responses to preflight requests.

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

Element	Description
LifecycleConfiguration	Defines the lifecycle management policies for the bucket, which contains 0 or more (up to 100) rules. An empty element (for example <LifecycleConfiguration/>) means lifecycle management is not enabled for the bucket.
Rule	Defines a lifecycle management rule, which is made of an action and the condition under which the action will be taken.
Action	Defines the action to be taken, which must contain one and only one specific action element.
Delete	Action element to delete objects in the bucket.
Condition	Defines the condition under which the action will be taken, which must contain at least one specific condition element.
Age	Condition element that matches objects over the specified age (in days).
CreatedBefore	Condition element that matches objects created before midnight of the specified date in UTC. The value is an ISO date string without a time zone, e.g. "2013-01-15".
NumberOfNewerVersions	Condition element relevant only for versioned objects. If the value is N, the condition is satisfied when there are at least N versions (including the live version) newer than this version of the object.
IsLive	Condition element relevant only for versioned objects. Matches live objects if the value is true, or archived objects if the value is false.

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

Element	Description
LocationConstraint	The location of the bucket. For a list of locations, see Bucket Locations.

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

Element	Description
Logging	Container for logging configuration. Empty element if logging is disabled for the bucket.
LogBucket	The bucket that will receive log objects.
LogObjectPrefix	The object prefix for log objects.

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.

Element	Description
StorageClass	The storage class of the bucket, STANDARD, NEARLINE or DURABLE_REDUCED_AVAILABILITY.

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

Element	Description
VersioningConfiguration	Container for versioning configuration. Empty element if versioning has not been enabled for the bucket.
Status	Status of versioning for this bucket. Currently either Enabled or Suspended.

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

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. For more information, see Request URIs.	Yes

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 Bucket Locations.

Request Details

Query String Parameters

Parameter	Description	Required
acl	You use this to change ACLs on an existing bucket. You must provide the ACL XML document in the request body.	No
cors	You use this to change the CORS configuration on an existing bucket. You must provide the CORS XML document in the request body.	No
lifecycle	You use this to change the lifecycle configuration on an existing bucket. You must provide the LifecycleConfiguration document in the request body.	No
logging	You use this to change the logging configuration on an existing bucket. You must provide the Logging document in the request body.	No
versioning	You use this to change the versioning configuration on an existing bucket. You must provide the VersioningConfiguration document in the request body.	No
websiteConfig	You use this to change the website configuration on an existing bucket. You must provide the WebsiteConfiguration document in the request body.	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
Content-Type	The MIME type of the request body.	No
Date	The date and time of the request.	Yes
Host	The URI for Google Cloud Storage. For more information, see Request URIs.	Yes
x-goog-acl	The predefined access control list (ACL) that you want to apply to the bucket. Do not use if you are using the acl query string parameter to apply ACLs.	No
x-goog-project-id	The project ID of a project.	Yes

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.

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 are being applied.
Name	Comment field for GroupByEmail, GroupById, UserByEmail, and UserById. If you do not specify anything in Name when you apply an ACL, the Google Cloud Storage system populates this field with the email address you specified in EmailAddress.
AccessControlList	Container for the ACLs you are applying.
Entries	Container for the ACL entries you are applying.
Entry	The ACL entry you are applying.
Scope	The scope to which the ACLs apply.
Permission	The permission you are granting. 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.

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.

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.
Origins	Container for the origins permitted for cross origin resource sharing with this Google Cloud Storage bucket.
Origin	An Origin permitted for cross origin resource sharing with this Google Cloud Storage bucket. For example, http://origin1.example.com. You can use wildcards ("*"). However, if the host part of the Origin begins with a *, then any origin that ends with the same suffix will be considered a match. If you supply a value that consists of only the wildcard (<Origin>*</Origin>), this gives access to ALL origins.
Methods	Container for one or more HTTP Method elements, specifying the methods permitted in cross origin resource sharing with this Google Cloud Storage bucket.
Method	An HTTP method supported in this configuration. Valid values are GET, HEAD, PUT, POST, and DELETE.
ResponseHeaders	Optional container for one or more ResponseHeader elements.
ResponseHeader	Specifies a response header that the user agent is permitted to share across origins.
MaxAgeSec	This value is used to respond to preflight requests, indicating the number of seconds that the client (browser) is allowed to make requests before the client must repeat the preflight request. (Indicates cache expiry time.) Preflight requests are required if the request method contains non-simple headers or if the request method is not POST, GET, or HEAD. The value is returned in the Access-Control-Max-Age header in responses to preflight requests.

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.

Element	Description
LifecycleConfiguration	Defines the lifecycle management policies for the bucket, which contains 0 or more (up to 100) rules. Use an empty element (for example, <LifecycleConfiguration/>) to disable lifecycle management for the bucket.
Rule	Defines a lifecycle management rule, which is made of an action and the condition under which the action will be taken.
Action	Defines the action to be taken, which must contain one and only one specific action element. Required.
Delete	Action element to delete objects in the bucket.
Condition	Defines the condition under which the action will be taken, which must contain at least one specific condition element. Required.
Age	Condition element that matches objects over the specified age (in days).
CreatedBefore	Condition element that matches objects created before midnight of the specified date in UTC. The value is an ISO date string without a time zone, e.g. "2013-01-15".
NumberOfNewerVersions	Condition element relevant only for versioned objects. If the value is N, the condition is satisfied when there are at least N versions (including the live version) newer than this version of the object.
IsLive	Condition element relevant only for versioned objects. Matches live objects if the value is true, or archived objects if the value is false.

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.

Element	Description
Logging	Container for logging configuration. Use an empty element (for example, <Logging/>) to disable logging for the bucket.
LogBucket	The bucket that will receive log objects. Must be a valid bucket name. Required.
LogObjectPrefix	The object prefix for log objects. It can be at most 900 characters and must be a valid object name. Optional.

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.

Element	Description
VersioningConfiguration	Container for versioning configuration.
Status	Status of versioning for this bucket. Currently can be either Enabled or Suspended.

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.

Element	Description
WebsiteConfiguration	Container for website configuration.
MainPageSuffix	An object name suffix to simulate directory index behavior. Must be a valid object name. Optional.
NotFoundPage	Name of the object to return with 404 responses. Must be a valid object name. Optional.

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 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 jane@gmail.com 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>jane@gmail.com</EmailAddress>
        <Name></Name>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupByEmail">
        <EmailAddress>gs-discussion@googlegroups.com</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

Parameter	Description	Required
generation	You can use this if you want to delete a specific object generation. If this query parameter is used on a versioned bucket and the object is the current one, no archive of the object is made, but instead the object is deleted completely.	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. For more information, see Request URIs.	Yes
x-goog-if-generation-match	If the generation you specify is the same as the current object, then the object is deleted.	No

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

Parameter	Description	Required
acl	You can use this only if you are using the GET Object method to list an object's ACLs.	No
generation	You can use this if you want to fetch a specific object version.	No
Expires	Used for Signed URLs.	No
GoogleAccessId	Used for Signed URLs.	No
Signature	Used for Signed URLs.	No

Request Headers

Header	Description	Required
Authorization	The authentication string for the request. Required for objects without public read access.	Maybe
Host	The URI for Google Cloud Storage. For more information, see Request URIs.	Yes
x-goog-if-generation-match	If the generation you specify is the same as the object you're fetching, then the object is downloaded. Typically most useful when only fetching the current object with a precondition. Also see generation query parameter.	No
If-Match	An entity tag (ETag). If the ETag you specify is the same as the ETag for the object, then the object is downloaded.	No
If-Modified-Since	A date and time. If the object has been modified later than the date and time you specify, then the object is downloaded.	No
If-None-Match	An entity tag (ETag). If the ETag you specify is different from the ETag for the object, then the object is downloaded.	No
If-Unmodified-Since	A date and time. If the object has not been modified later than the date you specify, then the object is downloaded.	No
Range	An object's range (in bytes) that you want to download.	Warning: The checksum(s) returned when downloading data from Google Cloud Storage cover the complete object content. Thus, if you specify a request range there's no way to detect data corruption for that byte range alone. We therefore recommend using range requests only for restarting the download of a full object after the last received offset, because in that case you can compute and validate the checksum when the full download completes.	No

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.

Element	Description
Owner	Container for object owner information.
ID	The Google Storage ID of the object 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.

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>joe@gmail.com</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

Parameter	Description	Required
generation	You can use this if you want to fetch a specific object generation.	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. For more information, see Request URIs.	Yes
If-Match	An entity tag (ETag). If the ETag you specify is the same as the ETag for the object, then the metadata is returned.	No
If-Modified-Since	A date and time. If the object has been modified later than the date and time you specify, then the metadata is returned.	No
If-None-Match	An entity tag (ETag). If the ETag you specify is different from the ETag for the object, then the metadata is returned.	No
If-Unmodified-Since	A date and time. If the object has not been modified later than the date you specify, then the metadata is returned.	No
Range	The range (in bytes) that you want returned.	No
x-goog-if-generation-match	If the generation you specify is the same as the generation for the object, then the metadata is returned.	No
x-goog-if-metageneration-match	If the metageneration you specify is the same as the metageneration for the object, then the metadata is returned.	No

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

Field	Description	Required
acl	The predefined ACL that you want to apply to the object that is being uploaded. If you do not specify this field the bucket's default ACL is applied.	No
bucket	The name of the bucket that you want to upload to. Alternatively, you can include the bucket name in the key field or in the URI (for example, storage.googleapis.com/<bucket>).	No
Cache-Control	The cache control for the object. You can only set cache control for an object that is accessible to all users. For instance, an object's ACL must be public-read or public-read-write to be able to set the cache-control.	No
Content-Disposition	Specifies how the object data should be transmitted. For example, a Content-Disposition value of inline means that the object should be displayed immediately.	No
Content-Encoding	The compression algorithm for the object, such as gzip.	No
Content-Length	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>].	No
Content-Type	The MIME type of the file you are uploading via the form. If you do not specify a content type, the Google Cloud Storage system defaults to binary/octet-stream when it serves the content.	No
Expires	An ISO8601 timestamp that specifies the date and time before an object is considered stale by the browser.	No
file	The file you are uploading. Must be the last field in the form. You can upload only one object per request.	Yes
GoogleAccessId	The Google Cloud Storage email form of the client ID, as described in the section on Signed URLs.	No (required only if you are specifying a policy).
key	The name of the object that you are uploading. If you specify the object name without the bucket name, you must append the bucket name to the URI (for example, storage.googleapis.com/<bucket>). If you specify the bucket name and object name (for example, bucket/object), you must specify only the URI (for example, storage.googleapis.com). You can also use the ${filename} variable if a user is providing a file name. Also, if you are using a bucket name that is a CNAME redirect, be sure that the bucket name is specified only once in your request.	Yes
policy	The security policy that describes what can and cannot be uploaded in the form. If you do not provide a security policy, requests are considered to be anonymous and will only work with buckets that have granted WRITE or FULL_CONTROL permission to anonymous users. The policy document must be Base64 encoded. See the policy document section for more information.	No
signature	The signature of the Base64-encoded policy document you are including in the request. Your signature must be signed with the secret key associated with the GoogleAccessID you specified. (This is the email form of the client ID, as described in the section on Signed URLs).	No
success_action_redirect	A URL that users are redirected to when an upload is successful. If you do not provide a URL, Google Cloud Storage responds with the status code that you specified in success_action_status.	No
success_action_status	The status code that you want Google Cloud Storage to respond with when an upload is successful. The default is 204, but you can change this to 200 or 201. If you choose 200 or 204, Google Cloud Storage returns an empty document with those status codes. If you choose 201, Google Cloud Storage returns an XML document with the elements that are described in Response Body Elements. Note: The Adobe Flash player might not handle responses with an empty document body. You should use status code 201 if this is the case.	No
x-goog-meta-*	A field for custom metadata. You can use this to specify any additional metadata that is not provided by the other form fields. For example, x-goog-meta-reviewer: jane or x-goog-meta-project-manager: john is custom metadata.	No

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.

Element	Description
Bucket	Bucket in which the object was stored.
ETag	HTTP 1.1 entity tag for the object.
Key	The object's name.
Location	The URI for the object.

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 (with our without a Google account) can upload with a form POST, and provides authorization to ensure that the form can upload files into the target bucket. You can use policy documents to allow visitors to a website to upload files to Google Cloud Storage. 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. For more information about configuring access to buckets and objects in Google Cloud Storage, see Access Control.

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

Entry	Description
expiration	The expiration time of the policy document. An expired policy document will cause the HTML form to break. This must be in ISO8601 format.
conditions	An array of conditions that every upload must satisfy.

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:

Element	Description
acl	ACL values for the object from possible predefined ACLs.
bucket	The bucket that will hold the object.
cache-control	Cache-control for the object.
content-disposition	Specifies how the object data should be transmitted.
content-encoding	The compression algorithm for the object.
content-length	The byte length of the request body.
content-type	The MIME type of the file that is being uploaded.
expires	An ISO8601 timestamp that specifies the data and time before an object is considered stale by the browser.
key	The name of the object you are uploading.
success_action_redirect	The URL the user's client is redirected to when the upload is successful.
success_action_status	The status code that you want Google Cloud Storage to respond with when an upload is successful.
x-goog-meta-*	An extension header that can be used to store additional metadata that is not provided by the other fields.

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 SHA-256 using the secret key provided to you in the Google Developers Console. If you are using interoperable access keys, sign instead using SHA-1.
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)

Below is the Python implementation of the code to create your signature. In the code, key.pem is your service account PKCS12 key converted into PKCS1 (PEM) format.

from base64 import b64encode
from M2Crypto import EVP
def Sign(pem_key, message):
    assert pem_key
    key = EVP.load_key_string(pem_key)
    key.reset_context(md='sha256')
    key.sign_init()
    key.sign_update(str(message))
    return key.sign_final()

SecretKey = open('key.pem', 'r').read()
Policy = b64encode(open('policy.txt', 'r').read())
Signature = b64encode(Sign(SecretKey, Policy))
print Policy
print
print Signature

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="1234567890123@developer.gserviceaccount.com">
<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

Parameter	Description	Required
acl	Scopes the request to ACL changes only. You can use this only if you are using the PUT Object method to change ACLs on an existing object. You must specify the ACLs in an XML document in the request body.	No
compose	Issues a compose request. Requires a ComposeRequest XML document in the request body.	No
generation	Specifies the generation to update ACLs for. You can use this only if you are using the PUT Object method to change ACLs on an existing object. You must specify the ACLs in an XML document in the request body.	No
Expires	Used for Signed URLs.	No
GoogleAccessId	Used for Signed URLs.	No
Signature	Used for Signed URLs.	No

Request Headers

Header	Description	Required
Authorization	The authentication string for the request.	Yes
Content-Encoding	The compression algorithm that was used to compress the object you are uploading.	No
Content-Length	The length of the request body without headers (in bytes).	Yes (except requests that use chunked transfer encoding)
Content-Type	The MIME type of the request body. If you do not specify a content type, Google Cloud Storage defaults to binary/octet-stream when it serves the object.	No (recommended)
Content-Disposition	A header you can set on an object that specifies presentational information about how the object data is to be transmitted.	No
Date	The date and time of the request.	Yes
Host	The URI for Google Cloud Storage. For more information, see Request URIs.	Yes
Transfer-Encoding	Indicates if the message body was chunked.	No (except for requests that use chunked transfer encoding)
Content-MD5	The MD5 digest of the request message without headers.	No
x-goog-acl	The predefined ACL that you want to apply to the bucket. Do not use if you are using the acl query string parameter to apply ACLs.	No
x-goog-copy-source	The bucket/object path to the object you want to copy. For example, /travel-maps/paris.jpg.	No
x-goog-copy-source-if-match	An ETag. If the ETag you specify matches the ETag of the source object, then the source object is copied.	No
x-goog-copy-source-if-none-match	An ETag. If the ETag you specify does not match the Etag of the source object, then the object is copied.	No
x-goog-copy-source-if-modified-since	A date and time. If the date and time you specify is earlier than the Last-Modified date of the source object, then the object is copied.	No
x-goog-copy-source-if-unmodified-since	A date and time. If the date and time you specify is later than the Last-Modified date of the source object, then the object is copied.	No
x-goog-hash	A base64-encoded expected hash of the new object expressed as md5=<b64-encoded-md5> or crc32c=<b64-encoded-crc32c>.	No
x-goog-if-generation-match	If the generation you specify is the same as the object you're overwriting, then the object is overwritten. You can also specify 0 as a special value to indicate that the new object is only created if there is no existing object.	No
x-goog-if-metageneration-match	If the metageneration you specify is the same as the object you're trying to update, then the object metadata is updated. This is only allowed if x-goog-if-generation is specified. By combining these two generation properties, you can implement safe read-modify-write updates.	No
x-goog-metadata-directive	The instructions for handling metadata during a copy operation. Can be COPY or REPLACE. The default value is COPY.	No
x-goog-meta-	An extension header that can be used to store additional metadata that is not provided by the other fields.	No

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.

Element	Description
Owner	Container for object owner information.
ID	The Google Cloud Storage ID of the object owner or the Google Cloud Storage ID of the user or group for whom the ACLs are being applied.
Name	Comment field for GroupByEmail, GroupById, UserByEmail, and UserById. If you do not specify anything in Name when you apply an ACL, the Google Cloud Storage system populates this field with the email address you specified in EmailAddress.
AccessControlList	Container for the ACLs you are applying.
Entries	Container for the ACL entries you are applying.
Entry	The ACL entry you are applying.
Scope	The scope to which the ACLs apply.
Permission	The permission you are granting. 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 request body elements are applicable only if you use the compose query string parameter to issue a compose request.

Element	Description
ComposeRequest	Container for a compose request.
Component	Container for a compose request component argument.
Name	Object name for a compose request component.
Generation	Generation number for a compose request component.
IfGenerationMatch	Expected current generation number for a compose request component. The request will fail if the component object has a different generation.

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.

Element	Description
CopyObjectResult	Container for copy information.
ETag	The ETag of the newly-copied object.
LastModified	The date and time that the source object was last modified prior to the current copy operation.

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 jane@gmail.com 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>jane@gmail.com</EmailAddress>
        <Name></Name>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupByEmail">
        <EmailAddress>gs-discussion@googlegroups.com</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

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Last updated March 16, 2015.