openstack-manuals/doc/user-guide/section_object-api-archive-auto-extract.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="archive-auto-extract">
    <?dbhtml stop-chunking?>
    <title>Auto-extract archive files</title>
    <para>To discover whether your Object Storage system supports this
        feature, see <xref linkend="discoverability"/>. Alternatively,
        check with your service provider.</para>
    <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>