Create or replace object

Request
Response

Method	URI	Description
PUT	`/v1/{account}/{container}/{object}{?multipart-manifest,signature,expires}`	Creates a new object with specified data content and metadata, or replaces an existing object with specified data content and metadata.

The PUT operation always creates a new object. If you use this operation on an existing object, you replace the existing object and metadata rather than modifying the object. Consequently, this operation returns a 201 Created status code.

If you use this operation to copy a manifest object, the new object is a normal object and not a copy of the manifest. Instead it is a concatenation of all the segment objects. This means that you cannot copy objects larger than 5 GB.

Example requests and responses:

Create object:
curl -i $publicURL/janeausten/helloworld.txt -X PUT -H "Content-Length: 1" -H "Content-Type: text/html; charset=UTF-8" -H "X-Auth-Token: $token"
```
HTTP/1.1 201 Created
Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT
Content-Length: 116
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
Date: Fri, 17 Jan 2014 17:28:35 GMT
```

Replace object:

curl -i $publicURL/janeausten/helloworld -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"

HTTP/1.1 201 Created
Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT
Content-Length: 116
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
Date: Fri, 17 Jan 2014 17:28:35 GMT

For a complete description of HTTP 1.1 header definitions, see Header Field Definitions.

The 201 Created status code indicates a successful write.

If the request times out, the operation returns the 408 Request Timeout error code.

The 411 Length Required error code indicates a missing Transfer-Encoding or Content-Length request header.

If the MD5 checksum of the data that is written to the object store does not match the optional ETag value, the operation returns the 422 Unprocessable Entity error code.

Normal response codes: 201

Error response codes: timeout (408), lengthRequired (411), unprocessableEntity (422)

Request

This table shows the header parameters for the create or replace object request:

Name	Type	Description
`X-Object-Manifest`	String (Optional)	Set to specify that this is a dynamic large object manifest object. The value is the container and object name prefix of the segment objects in the form `container/prefix`. You must UTF-8-encode and then URL-encode the names of the container and prefix before you include them in this header.
`X-Auth-Token`	String (Optional)	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
`Content-Length`	Int (Optional)	Set to the length of the object content. Do not set if chunked transfer encoding is being used.
`Transfer-Encoding`	String (Optional)	Set to `chunked` to enable chunked transfer encoding. If used, do not set the `Content-Length` header to a non-zero value.
`Content-Type`	String (Optional)	Changes the MIME type for the object.
`X-Detect-Content-Type`	Boolean (Optional)	If set to `true`, Object Storage guesses the content type based on the file extension and ignores the value sent in the `Content-Type` header, if present.
`X-Copy-From`	String (Optional)	If set, this is the name of an object used to create the new object by copying the `X-Copy-From` object. The value is in form `{container}/{object}`. You must UTF-8-encode and then URL-encode the names of the container and object before you include them in the header. Using PUT with `X-Copy-From` has the same effect as using the COPY operation to copy an object.
`ETag`	String (Optional)	The MD5 checksum value of the request body. For example, the MD5 checksum value of the object content. You are strongly recommended to compute the MD5 checksum value of object content and include it in the request. This enables the Object Storage API to check the integrity of the upload. The value is not quoted.
`Content-Disposition`	String (Optional)	If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default.
`Content-Encoding`	String (Optional)	If set, the value of the `Content-Encoding` metadata.
`X-Delete-At`	Int (Optional)	The certain date, in the format of a UNIX Epoch timestamp, when the object is removed.
`X-Delete-After`	Int (Optional)	Specifies the number of seconds after which the object is removed. Internally, the Object Storage system stores this value in the `X-Delete-At` metadata item.
`X-Object-Meta-name`	String (Optional)	The container metadata, where `{name}` is the name of the metadata item. You must specify a `X-Object-Meta-{name}` header for each metadata item (for each `{name}`) that you want to add or update.

This table shows the URI parameters for the create or replace object request:

Name	Type	Description
`{account}`	String	The unique name for the account. An account is also known as the project or tenant.
`{container}`	String	The unique name for the container.
`{object}`	String	The unique name for the object.

This table shows the query parameters for the create or replace object request:

Name Type Description

Name	Type	Description
`multipart-manifest`	String (Optional)	If `?multipart-manifest=put`, the object is a static large object manifest and the body contains the manifest.
`signature`	String (Optional)	Used with temporary URLs to sign the request. For more information about temporary URLs, see OpenStack Object Storage API v1 Reference .
`expires`	String (Optional)	Used with temporary URLs to specify the expiry time of the signature. For more information about temporary URLs, see OpenStack Object Storage API v1 Reference .

multipart-manifest

String

(Optional)

If ?multipart-manifest=put, the object is a static large object manifest and the body contains the manifest.

signature

String

(Optional)

Used with temporary URLs to sign the request. For more information about temporary URLs, see OpenStack Object Storage API v1 Reference .

expires

String

(Optional)

Used with temporary URLs to specify the expiry time of the signature. For more information about temporary URLs, see OpenStack Object Storage API v1 Reference .

Response

This table shows the header parameters for the create or replace object response:

Name	Type	Description
`Content-Length`	String (Required)	If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
`ETag`	String (Required)	For objects smaller than 5 GB, this value is the MD5 checksum of the uploaded object content. The value is not quoted. If you supplied an `ETag` request header and the operation was successful, the values are the same. If you did not supply an `ETag` request header, check the `ETag` response header value against the object content you have just uploaded. For static large objects, this value is the MD5 checksum of the concatenated string of MD5 checksums and ETags for each of the segments in the manifest, and not the MD5 checksum of the content that was uploaded. Also the value is enclosed in double-quotes. For dynamic large objects, the value is the MD5 checksum of the empty string.
`Content-Type`	String (Required)	The MIME type of the object.
`X-Trans-Id`	Uuid (Required)	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
`Date`	Datetime (Required)	The transaction date and time.

Questions? Discuss on ask.openstack.org
Found an error? Report a bug against this page

Legal notices

Prev	Up	Next
	Home