Object upload

To upload an object with the XML API, 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. The uploaded object replaces any existing object with the same name. For tips on uploading to Cloud Storage, see Best Practices. For a quick guide to simple uploads using tools such as the XML API, see Uploading Objects.

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, x-goog-meta-, and x-goog-storage-class. Cloud Storage stores these headers as part of the object's metadata, except for Content-MD5, which Cloud Storage uses to check for data integrity. See Editing object metadata for information on changing metadata values for objects.

You also use a PUT Object request when you want to change the storage class of an existing object, because you must rewrite the existing object to do so. The request should contain the x-goog-storage-class request header, as well as the object in the request body.

Note: Resumable uploads and HTML forms use a POST Object request.

Query string parameters

Parameter	Description	Required
Expires	Used for Signed URLs.	No
GoogleAccessId	Used for Signed URLs.	No
Signature	Used for Signed URLs.	No

Request headers

In addition to common request headers, the following can be used.

Header	Description	Required
Content-Encoding	The compression algorithm that was used to compress the object you are uploading.	No
Content-Disposition	A header that specifies presentational information about how the object data is to be transmitted.	No
x-goog-acl	The predefined ACL that you want to apply to the object.	No
x-goog-custom-time	A user-specified date and time.	No
x-goog-encryption-kms-key-name	The customer-managed encryption key to use to encrypt the object.	No
x-goog-meta-	An extension header that can be used to store custom metadata.	No
x-goog-storage-class	A valid storage class.	No

To provide a customer-supplied encryption key along with the object upload, use the headers listed on the Customer-Supplied Encryption Key page in your request.

Request body elements

The request body contains the data.

Request syntax

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

PUT /OBJECT_NAME HTTP/1.1
Host: BUCKET_NAME.storage.googleapis.com
Date: DATE
Content-Length: REQUEST_BODY_LENGTH
Content-Type: MIME_TYPE
Content-MD5: MD5_DIGEST
Authorization: AUTHENTICATION_STRING
x-goog-storage-class: STORAGE_CLASS

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.

Example

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

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: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Response

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

Common error codes

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

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

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