ed4f3c4db9
Point to WADL files that generate the API Reference
page so that the method descriptions and request
and response parameters are consistent between
these two docs:
http://api.openstack.org/api-ref-objectstorage.html
(API Reference page for Object Storage)
http://docs.openstack.org/api/openstack-object-storage/1.0/
(API Reference (or spec) for Object Storage)
Add descriptions of ACLs, FormPOST, TempURLs,
StaticWeb, Bulk Upload, Bulk Delete, the OPTIONS operation
(though this is implicit in CORS support)
Validate all code examples
Remove duplication.
Co-Author: Donagh McCabe
Closes-Bug: #1187119
Closes-Bug: #1214139
Closes-Bug: #1074198
Partial-Bug: #1255770
Change-Id: I94054b046a94260ba8825bdb42439adfcaf9fdce
author: diane fleming
185 lines
9.5 KiB
XML
185 lines
9.5 KiB
XML
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE section [
|
|
<!-- Some useful entities borrowed from HTML -->
|
|
<!ENTITY ndash "–">
|
|
<!ENTITY mdash "—">
|
|
<!ENTITY hellip "…">
|
|
|
|
<!-- Useful for describing APIs -->
|
|
<!ENTITY COPY '<command xmlns="http://docbook.org/ns/docbook">COPY</command>'>
|
|
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
|
<!ENTITY HEAD '<command xmlns="http://docbook.org/ns/docbook">HEAD</command>'>
|
|
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
|
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
|
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
|
|
]>
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
|
xml:id="set-object-versions">
|
|
<title>Object versioning</title>
|
|
<para>You can store multiple versions of your content so that you
|
|
can recover from unintended overwrites. Object versioning is
|
|
an easy way to implement version control, which you can use
|
|
with any type of content.</para>
|
|
<note>
|
|
<para>You cannot version a large-object manifest file, but the
|
|
large-object manifest file can point to versioned
|
|
segments.</para>
|
|
</note>
|
|
<para>It is strongly recommended that you put non-current objects
|
|
in a different container than the container where current
|
|
object versions reside.</para>
|
|
<procedure>
|
|
<title>To enable and use object versioning</title>
|
|
<step>
|
|
<para>To enable object versioning, ask your cloud provider
|
|
to set the <option>allow_versions</option> option to
|
|
<literal>TRUE</literal> in the container
|
|
configuration file.</para>
|
|
</step>
|
|
<step>
|
|
<para>Create an <literal>archive</literal> container to
|
|
store older versions of objects.</para>
|
|
<para>Create the <literal>archive</literal>
|
|
container:</para>
|
|
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/archive -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"</userinput></screen>
|
|
<screen><computeroutput>HTTP/1.1 201 Created
|
|
Content-Length: 0
|
|
Content-Type: text/html; charset=UTF-8
|
|
X-Trans-Id: tx46f8c29050834d88b8d7e-0052e1859d
|
|
Date: Thu, 23 Jan 2014 21:11:57 GMT</computeroutput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Create a <literal>current</literal> container to
|
|
store current versions of objects.</para>
|
|
<para>Include the <literal>X-Versions-Location</literal>
|
|
header. This header defines the container that holds
|
|
the non-current versions of your objects. You must
|
|
UTF-8-encode and then URL-encode the container name
|
|
before you include it in the
|
|
<code>X-Versions-Location</code> header. This
|
|
header enables object versioning for all objects in
|
|
the <literal>current</literal> container. Changes to
|
|
objects in the <literal>current</literal> container
|
|
automatically create non-current versions in the
|
|
<literal>archive</literal> container.</para>
|
|
<para>Create the <literal>current</literal>
|
|
container:</para>
|
|
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: archive"</userinput></screen>
|
|
<screen><computeroutput>HTTP/1.1 201 Created
|
|
Content-Length: 0
|
|
Content-Type: text/html; charset=UTF-8
|
|
X-Trans-Id: txb91810fb717347d09eec8-0052e18997
|
|
Date: Thu, 23 Jan 2014 21:28:55 GMT</computeroutput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Create the first version of an object in the
|
|
<literal>current</literal> container:</para>
|
|
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current/my_object --data-binary 1 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"</userinput></screen>
|
|
<screen><computeroutput>HTTP/1.1 201 Created
|
|
Last-Modified: Thu, 23 Jan 2014 21:31:22 GMT
|
|
Content-Length: 0
|
|
Etag: d41d8cd98f00b204e9800998ecf8427e
|
|
Content-Type: text/html; charset=UTF-8
|
|
X-Trans-Id: tx5992d536a4bd4fec973aa-0052e18a2a
|
|
Date: Thu, 23 Jan 2014 21:31:22 GMT</computeroutput></screen>
|
|
<para>Nothing is written to the non-current version
|
|
container when you initially &PUT; an object in the
|
|
<literal>current</literal> container. However,
|
|
subsequent &PUT; requests that edit an object trigger
|
|
the creation of a version of that object in the
|
|
<literal>archive</literal> container.</para>
|
|
<para>These non-current versions are named as
|
|
follows:</para>
|
|
<programlisting><length><object_name><timestamp></programlisting>
|
|
<para>Where <literal>length</literal> is the 3-character, zero-padded
|
|
hexadecimal character length of the object,
|
|
<literal><object_name></literal> is the object name, and
|
|
<literal><timestamp></literal> is the time when the object was
|
|
initially created as a current version.</para>
|
|
</step>
|
|
<step>
|
|
<para>Create a second version of the object in the
|
|
<literal>current</literal> container:</para>
|
|
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current/my_object --data-binary 2 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"</userinput></screen>
|
|
<screen><computeroutput>HTTP/1.1 201 Created
|
|
Last-Modified: Thu, 23 Jan 2014 21:41:32 GMT
|
|
Content-Length: 0
|
|
Etag: d41d8cd98f00b204e9800998ecf8427e
|
|
Content-Type: text/html; charset=UTF-8
|
|
X-Trans-Id: tx468287ce4fc94eada96ec-0052e18c8c
|
|
Date: Thu, 23 Jan 2014 21:41:32 GMT</computeroutput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Issue a &GET; request to a versioned object to get
|
|
the current version of the object. You do not have to
|
|
do any request redirects or metadata lookups.</para>
|
|
<para>List older versions of the object in the
|
|
<literal>archive</literal> container:</para>
|
|
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token"</userinput></screen>
|
|
<screen><computeroutput>HTTP/1.1 200 OK
|
|
Content-Length: 30
|
|
X-Container-Object-Count: 1
|
|
Accept-Ranges: bytes
|
|
X-Timestamp: 1390513280.79684
|
|
X-Container-Bytes-Used: 0
|
|
Content-Type: text/plain; charset=utf-8
|
|
X-Trans-Id: tx9a441884997542d3a5868-0052e18d8e
|
|
Date: Thu, 23 Jan 2014 21:45:50 GMT
|
|
|
|
009my_object/1390512682.92052</computeroutput></screen>
|
|
<note>
|
|
<para>A &POST; request to a versioned object updates
|
|
only the metadata for the object and does not
|
|
create a new version of the object. New versions
|
|
are created only when the content of the object
|
|
changes.</para>
|
|
</note>
|
|
</step>
|
|
<step>
|
|
<para>Issue a &DELETE; request to a versioned object to
|
|
remove the current version of the object and replace
|
|
it with the next-most current version in the
|
|
non-current container.</para>
|
|
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current/my_object -X DELETE -H "X-Auth-Token: $token"</userinput></screen>
|
|
<screen><computeroutput>HTTP/1.1 204 No Content
|
|
Content-Length: 0
|
|
Content-Type: text/html; charset=UTF-8
|
|
X-Trans-Id: tx006d944e02494e229b8ee-0052e18edd
|
|
Date: Thu, 23 Jan 2014 21:51:25 GMT</computeroutput></screen>
|
|
<para>List objects in the <literal>archive</literal>
|
|
container to show that the archived object was moved
|
|
back to the <literal>current</literal>
|
|
container:</para>
|
|
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token"</userinput></screen>
|
|
<screen><computeroutput>HTTP/1.1 204 No Content
|
|
Content-Length: 0
|
|
X-Container-Object-Count: 0
|
|
Accept-Ranges: bytes
|
|
X-Timestamp: 1390513280.79684
|
|
X-Container-Bytes-Used: 0
|
|
Content-Type: text/html; charset=UTF-8
|
|
X-Trans-Id: tx044f2a05f56f4997af737-0052e18eed
|
|
Date: Thu, 23 Jan 2014 21:51:41 GMT</computeroutput></screen>
|
|
<para>This next-most current version carries with it any
|
|
metadata last set on it. If want to completely remove
|
|
an object and you have five versions of it, you must
|
|
&DELETE; it five times.</para>
|
|
</step>
|
|
<step>
|
|
<para>To disable object versioning for the
|
|
<literal>current</literal> container, remove its
|
|
<literal>X-Versions-Location</literal> metadata
|
|
header by sending an empty key value.</para>
|
|
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: "</userinput></screen>
|
|
<screen><computeroutput>HTTP/1.1 202 Accepted
|
|
Content-Length: 76
|
|
Content-Type: text/html; charset=UTF-8
|
|
X-Trans-Id: txe2476de217134549996d0-0052e19038
|
|
Date: Thu, 23 Jan 2014 21:57:12 GMT
|
|
|
|
<html><h1>Accepted</h1><p>The request is accepted for processing.</p></html></computeroutput></screen>
|
|
</step>
|
|
</procedure>
|
|
</section>
|