Adds auto-extract archive file info to End User Guide
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: I5153b59ac89638d3765ef325867e56c5e2d82f99 Partial-bug: 1392382
This commit is contained in:
Erik Wilson
parent
c68cc28438
commit
daf73d3ac2
@ -129,8 +129,9 @@ X-Timestamp: 1392684036.33306</computeroutput></screen>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<xi:include href="section_object-api-env-vars.xml"/>
|
||||
<xi:include href="section_object-api-versioning.xml"/>
|
||||
<xi:include href="section_object-api-response-formats.xml"/>
|
||||
<xi:include href="section_object-api-create-large-objects.xml"/>
|
||||
<xi:include href="section_object-api-versioning.xml"/>
|
||||
<xi:include href="section_object-api-large-lists.xml"/>
|
||||
<xi:include href="section_object-api-archive-auto-extract.xml"/>
|
||||
</section>
|
||||
|
||||
156
doc/user-guide/section_object-api-archive-auto-extract.xml
Normal file
156
doc/user-guide/section_object-api-archive-auto-extract.xml
Normal file
@ -0,0 +1,156 @@
|
||||
<?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="archive-auto-extract">
|
||||
<?dbhtml stop-chunking?>
|
||||
<title>Auto-extract archive files</title>
|
||||
<para>Use the auto-extract archive feature to upload a tar archive
|
||||
file.</para>
|
||||
<para>The Object Storage system extracts files from the archive
|
||||
file and creates an object.</para>
|
||||
<section xml:id="archive-auto-extract-put">
|
||||
<title>Auto-extract archive request</title>
|
||||
<para>To upload an archive file, make a &PUT; request. Add the
|
||||
<parameter>extract-archive=<replaceable>format</replaceable></parameter>
|
||||
query parameter to indicate that you are uploading a tar
|
||||
archive file instead of normal content.</para>
|
||||
<para>Valid values for the <replaceable>format</replaceable>
|
||||
variable are <literal>tar</literal>,
|
||||
<literal>tar.gz</literal>, or
|
||||
<literal>tar.bz2</literal>.</para>
|
||||
<para>The path you specify in the &PUT; request is used for
|
||||
the location of the object and the prefix for the
|
||||
resulting object names.</para>
|
||||
<para>In the &PUT; request, you can specify the path
|
||||
for:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>An account</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Optionally, a specific container</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Optionally, a specific object prefix</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>For example, if the first object in the tar archive is
|
||||
<filename>/home/file1.txt</filename> and you specify
|
||||
the
|
||||
<filename>/v1/12345678912345/mybackup/castor/</filename>
|
||||
path, the operation creates the
|
||||
<filename>castor/home/file1.txt</filename> object in
|
||||
the <literal>mybackup</literal> container in the
|
||||
<literal>12345678912345</literal> account.</para>
|
||||
</section>
|
||||
<section xml:id="archive-auto-extract-create">
|
||||
<title>Create an archive for auto-extract</title>
|
||||
<para>You must use the tar utility to create the tar archive
|
||||
file.</para>
|
||||
<para>You can upload regular files but you cannot upload other
|
||||
items (for example, empty directories or symbolic
|
||||
links).</para>
|
||||
<para>You must UTF-8-encode the member names.</para>
|
||||
<para>The archive auto-extract feature supports these
|
||||
formats:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>The POSIX.1-1988 Ustar format.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The GNU tar format. Includes the long name, long
|
||||
link, and sparse extensions.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The POSIX.1-2001 pax format.</para>
|
||||
<para>Use gzip or bzip2 to compress the
|
||||
archive.</para>
|
||||
<para>Use the <parameter>extract-archive</parameter>
|
||||
query parameter to specify the format. Valid
|
||||
values for this parameter are
|
||||
<literal>tar</literal>,
|
||||
<literal>tar.gz</literal>, or
|
||||
<literal>tar.bz2</literal>.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="archive-auto-extract-response">
|
||||
<title>Auto-extract archive response</title>
|
||||
<para>When Object Storage processes the request, it performs
|
||||
multiple sub-operations. Even if all sub-operations fail,
|
||||
the operation returns a <returnvalue>201</returnvalue>
|
||||
<literal>Created</literal> status. Some sub-operations
|
||||
might succeed while others fail: Examine the response body
|
||||
to determine the results of each auto-extract archive
|
||||
sub-operation.</para>
|
||||
<para>You can set the <literal>Accept</literal> request header
|
||||
to one of these values to define the response
|
||||
format:</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><literal>text/plain</literal></term>
|
||||
<listitem>
|
||||
<para>Formats response as plain text. If you omit
|
||||
the <literal>Accept</literal> header,
|
||||
<literal>text/plain</literal> is the
|
||||
default.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><literal>application/json</literal></term>
|
||||
<listitem>
|
||||
<para>Formats response as JSON.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><literal>application/xml</literal></term>
|
||||
<listitem>
|
||||
<para>Formats response as XML.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><literal>text/xml</literal></term>
|
||||
<listitem>
|
||||
<para>Formats response as XML.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<para>The following auto-extract archive files example shows a
|
||||
<literal>text/plain</literal> response body where no
|
||||
failures occurred:</para>
|
||||
<screen><computeroutput>Number Files Created: 10
|
||||
Errors:</computeroutput></screen>
|
||||
<para>The following auto-extract archive files example shows a
|
||||
<literal>text/plain</literal> response where some
|
||||
failures occurred. In this example, the Object Storage
|
||||
system is configured to reject certain character strings
|
||||
so that the <errorcode>400</errorcode>
|
||||
<errortext>Bad Request</errortext> error occurs for any
|
||||
objects that use the restricted strings.</para>
|
||||
<screen><computeroutput>Number Files Created: 8
|
||||
Errors:
|
||||
/v1/12345678912345/mycontainer/home/xx%3Cyy, 400 Bad Request
|
||||
/v1/12345678912345/mycontainer/../image.gif, 400 Bad Request</computeroutput></screen>
|
||||
<para>The following example shows the failure response in
|
||||
<literal>application/json</literal> format.</para>
|
||||
<programlisting language="json">{
|
||||
"Number Files Created":1,
|
||||
"Errors":[
|
||||
[
|
||||
"/v1/12345678912345/mycontainer/home/xx%3Cyy",
|
||||
"400 Bad Request"
|
||||
],
|
||||
[
|
||||
"/v1/12345678912345/mycontainer/../image.gif",
|
||||
"400 Bad Request"
|
||||
]
|
||||
]
|
||||
}</programlisting>
|
||||
</section>
|
||||
</section>
|
||||
Loading…
x
Reference in New Issue
Block a user