 | Documentation Feedback |  |
The PUT request operation adds an object to a bucket.
The response indicates that the object has been successfully stored. Amazon S3 never stores partial objects: if you receive a successful response, then you can be confident that the entire object was stored.
To ensure data is not corrupted over the network, use the Content-MD5 header. When you use the Content-MD5 header, Amazon S3 checks the object against the provided MD5 value. If they do not match, Amazon S3 returns an error. Additionally, you can calculate the MD5 while putting an object to Amazon S3 and compare the returned Etag to the calculated MD5 value.
If an object already exists in a bucket, the new object will overwrite it because Amazon S3 stores the last write request. However, Amazon S3 is a distributed system. If Amazon S3 receives multiple write requests for the same object nearly simultaneously, all of the objects might be stored, even though only one wins in the end. Amazon S3 does not provide object locking; if you need this, make sure to build it into your application layer.
If you specify a location constraint when creating a bucket, all objects added to the bucket are stored in the bucket's location. For example, if you specify a Europe (EU) location constraint for a bucket, all of that bucket's objects are stored in Europe. For more information on location constraints, see Location Selection.
![[Note]](images/note.png) | Note |
|---|---|
To configure your application to send the request headers prior to sending the request body, use 100-continue. For PUT operations, this helps you avoid sending the message body if the message is rejected based on the headers (e.g., authentication failure or redirect). For more information on 100-continue, go to Section 8.2.3 of http://www.ietf.org/rfc/rfc2616.txt. You must have |
PUT /destinationObjectHTTP/1.1 Host:destinationBucket.s3.amazonaws.com Content-Length:lengthContent-MD5:md5_digestContent-Type:typeContent-Disposition:object_informationContent-Encoding:encodingCache-Control:cachingExpires:expiration<request metadata> Authorization:signatureDate:date
| Name | Description | Required |
|---|---|---|
Cache-Control
|
Can be used to specify caching behavior along the request/reply chain. Go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9. Type: String Default: None Constraints: None | No |
Content-Type
|
A standard MIME type describing the format of the contents. If none is provided, the default is binary/octet-stream. Go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17. Type: String Default: None Constraints: None | No |
Content-Length
|
The size of the object, in bytes. This is required. Go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.13. Type: String Default: None Constraints: None | No |
Content-MD5
|
The base64 encoded 128-bit MD5 digest of the message (without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the data is the same data that was originally sent. Although it is optional, we recommend using the Content-MD5 mechanism as an end-to-end integrity check. For more information about REST request authentication, see Authenticating REST Requests. Type: String Default: None Constraints: None | No |
Content-Disposition
|
Specifies presentational information for the object. Go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1. Type: String Default: None Constraints: None | No |
Content-Encoding
|
Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied in order to obtain the media-type referenced by the Content-Type header field. Go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11. Type: String Default: None Constraints: None | No |
x-amz-acl
|
The canned ACL to apply to the object. Options include private, public-read, public-read-write, and authenticated-read. For more information, see REST Access Control Policy. Type: String Default: None Constraints: None | No |
x-amz-meta-
|
Any header starting with this prefix is considered user metadata. It will be stored with the object and returned when you retrieve the object. The total size of the HTTP request, not including the body, must be less than 8 KB. Type: String Default: None Constraints: None | No |
HTTP/1.1 200 OK x-amz-id-2: id x-amz-request-id: request_id Date: date Content-Length: 0 Content-Type: application/xml ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f" Transfer-Encoding: chunked Connection: close Server: AmazonS3
| Name | Description |
|---|---|
Etag
|
Returns the Etag of the new object. Type: String Ancestor: CopyObjectResult |
There are no special errors for this operation. For information about general Amazon S3 errors, see List of Error Codes.
This example writes some text and metadata into the "Neo" object in the "quotes" bucket.
PUT /Neo HTTP/1.1 Content-Length: 4 Host: quotes.s3.amazonaws.com Date: Wed, 01 Mar 2006 12:00:00 GMT Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE= Content-Type: text/plain Expect: 100-continue woah
HTTP/1.1 100 Continue HTTP/1.1 200 OK x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7 x-amz-request-id: 0A49CE4060975EAC Date: Wed, 01 Mar 2006 12:00:00 GMT ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f" Content-Length: 0 Connection: close Server: AmazonS3
