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
115 lines
5.3 KiB
XML
115 lines
5.3 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section [
|
|
<!-- Useful for describing APIs -->
|
|
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</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="archive-auto-extract">
|
|
<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(1)
|
|
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 PUT request</title>
|
|
<para>To upload an archive file, you make a &PUT; request. Add
|
|
the
|
|
<parameter>extract-archive=<replaceable>format</replaceable></parameter>
|
|
query parameter to indicate that you are uploading a
|
|
tar(1) 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 a prefix
|
|
for the resulting object names.</para>
|
|
<para>For example, if the first object in the tar(1) 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>
|
|
<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>
|
|
</section>
|
|
<section xml:id="archive-auto-extract-create">
|
|
<title>Create an archive for auto-extract</title>
|
|
<para>You must use the tar(1) utility to create the tar(1)
|
|
archive file.</para>
|
|
<para>You can upload regular files but you cannot upload other
|
|
items, such as empty directories, symbolic links, and so
|
|
on.</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(1) or bzip2(1) 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: JSON</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. You must examine the
|
|
response body to determine which members failed to result
|
|
in an object creation.</para>
|
|
<para>You can set the <literal>Accept</literal> request header
|
|
to one of these values, which defines the response format:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>text/plain</literal>. Formats response
|
|
as plain text. If you omit the
|
|
<literal>Accept</literal> header,
|
|
<literal>text/plain</literal> is the
|
|
default.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>application/json</literal>. Formats
|
|
response as JSON.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>application/xml</literal> or
|
|
<literal>text/xml</literal>. Formats response
|
|
as XML.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>For more information, see <xref
|
|
linkend="archive-auto-extract-response"/>.</para>
|
|
</section>
|
|
</section>
|