042d662c58
With the moving of the Object Storage API content from a long-form dev guide to a specification, some topics needed To be added to the End User Guide. Change-Id: I2b6179bec34e1ebaa7f4678f43f69385691c615b Partial-bug: 1392382
172 lines
8.8 KiB
XML
172 lines
8.8 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section [
|
|
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
|
|
%openstack;
|
|
]>
|
|
<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>We 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>
|
|
<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>
|
|
<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 you 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>
|