Prev

Next

Writing an Object

Once you have a bucket, you can start storing objects in it. Objects are stored using the HTTP PUT method. Each object can hold up to 5 GB of data. When you store an object, Amazon S3 streams the data to multiple storage servers in multiple datacenters to ensure that the data remains available in the event of internal network or hardware failure.

When you write data to Amazon S3, you specify the destination bucket and a key for the object. The key may be any UTF-8 string you choose, but many developers will choose to maintain a key-naming scheme that lends itself to use of the prefix-based List operation. For example, you can store all of your beach pictures with keys that begin with the prefix "Pictures/Beach" (e.g. Pictures/Beach/BigWave.jpg, Pictures/Beach/Dune.png, etc.).

There is no distinction between overwriting an existing object and creating a new object. You simply send data to a bucket and key, and the object will be updated by the last write request received. If a write operation gets cut off during upload, the old data in the object (if any) will be maintained. If two write requests are sent simultaneously, then Amazon S3 will order the requests and store the one that arrived most recently.

In this release of Amazon S3, you cannot modify or append to an existing object. An existing object is always completely replaced or not modified at all.

By default, Amazon S3 stores objects with "private" access control grants that allow only the user that stored the object to read it back later. You can specify other access control instructions using the flexible access grants detailed in the Amazon Simple Storage Service Developer Guide. One of the most straightforward and common alternatives to the default access control is to set an object to be publicly readable. This means that any Internet user can download the object via a simple standard HTTP URL. For publicly readable objects, the owner of the bucket containing the object is still billed data transfer charges for all downloads. To make an object publicly readable, simply include the HTTP header "x-amz-acl: public-read" with your PUT request to store the object.

The following sample code snippets demonstrate storing an Amazon S3 object. To write an object, you must have write access to the bucket.

Java

To run the sample

Open the sample file.
Replace [bucket-name] with the name of your bucket and [key-name] with the name of the object.

Make any changes and run the sample.

// simple object put

S3Object simpleObject = new S3Object("this is a test".getBytes(), null);

Response response = conn.put("[bucket-name]", "[key-name]", simpleObject, null);



// put a more complex object with some metadata and http headers.

Map metadata = new TreeMap();

metadata.put("title", Arrays.asList(new String[] { "my title" }));

S3Object titledObject =

     new S3Object("this object has a title".getBytes(), metadata);



Map headers = new TreeMap();

headers.put("Content-Type", Arrays.asList(new String[] { "text/plain" }));



response = conn.put("[bucket-name]", "[key-name]", titledObject, headers);

C#

To run the sample

Open the sample file.
Replace [bucket-name] with the name of your bucket and [key-name] with the name of the object.

Make any changes and run the sample.

// simple object put

S3Object simpleObject = new S3Object("this is a test", null);

Response response = conn.put("[bucket-name]", "[key-name]", simpleObject, null);



// put a more complex object with some metadata and http headers.

SortedList metadata = new SortedList();

metadata.Add("title", "my title");

S3Object titledObject =

     new S3Object("this object has a title", metadata);



SortedList headers = new SortedList();

headers.Add("Content-Type", "text/plain");



response = conn.put("[bucket-name]", "[key-name]", titledObject, headers);

Perl

To run the sample

Open the sample file.
Replace [bucket-name] with the name of your bucket and [key-name] with the name of the object.

Make any changes and run the sample.

# simple object put

my $response =

    $conn->put("[bucket-name]", "[key-name]", S3Object->new("this is a test"));



# put a more complex object with some metadata and http headers.

$response =

     $conn->put(

        "[bucket-name]",

        "[key-name]",

        S3Object->new("this is a test", { title => "my title" }),

        { "Content-Type" => "text/plain" });

PHP

To run the sample

Open the sample file.
Replace [bucket-name] with the name of your bucket and [key-name] with the name of the object.

Make any changes and run the sample.

$req =& new HTTP_Request("http://s3.amazonaws.com/[bucket-name]/[object-name]");

$req->setMethod("PUT");

$req->setBody("this is a test");

$req->setHeader("Content-Type", "text/plain");

$req->setHeader("x-amz-meta-title", "my title");

setAuthorizationHeader($req);

$req->sendRequest();

Ruby

To run the sample

Open the sample file.
Replace [bucket-name] with the name of your bucket and [key-name] with the name of the object.

Make any changes and run the sample.

# simple object put

conn.put("[bucket-name]", "[key-name]", S3::S3Object.new("this is a test"));



# put a more complex object with some metadata and http headers.

$conn->put(

    "[bucket-name]",

    "[key-name]",

    S3::S3Object.new("this is a test", { "title" => "my title" }),

    { "Content-Type" => "text/plain" })

Python

To run the sample

Open the sample file.
Replace [bucket-name] with the name of your bucket and [key-name] with the name of the object.

Make any changes and run the sample.

# simple object put

conn.put("[bucket-name]", "[key-name]", S3.S3Object("this is a test"));



# put a more complex object with some metadata and http headers.

$conn->put(

    "[bucket-name]",

    "[key-name]",

    S3.S3Object("this is a test", { "title": "my title" })

    { "Content-Type": "text/plain" })

HTTP

The following is an example of an HTTP request.

# put object request



PUT /[bucket-name]/[key-name] HTTP/1.0

Date: Wed, 08 Mar 2006 04:06:16 GMT

Authorization: AWS [aws-access-key-id]:[header-signature]

Host: s3.amazonaws.com

Content-Length: 14

x-amz-meta-title: my title

Content-Type: text/plain



this is a test



# put object response



HTTP/1.1 200 OK

x-amz-id-2: wc15E1LUrjDZhNtT4QZtsbtadnOMKGjw5QTxkRDVO1owwbA6YoiqJJEuKShopufw

x-amz-request-id: 7487CD42C5CA7524

Date: Wed, 08 Mar 2006 04:06:16 GMT

ETag: "54b0c58c7ce9f2a8b551351102ee0938"

Content-Length: 0

Connection: keep-alive

Server: AmazonS3

	Copyright Information