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. 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
, and
x-goog-meta-
. 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.
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.
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-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> 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>
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