Changed bulk-delete to DELETE from POST
Also, moved information about auto-archive to that chapter. Made some small edits to reduce redundancy and improve clarity. Closes-Bug: #1288327 Change-Id: I53731cf895e3e28aa19d92be27d3d4f9c81678e1 author: diane fleming (diane.fleming@rackspace.com)
This commit is contained in:
Diane Fleming
parent
befcd430c3
commit
9aaf74f0e4
|
|
@ -7,16 +7,17 @@
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||||
xml:id="archive-auto-extract">
|
xml:id="archive-auto-extract">
|
||||||
|
<?dbhtml stop-chunking?>
|
||||||
<title>Auto-extract archive files</title>
|
<title>Auto-extract archive files</title>
|
||||||
<para>To discover whether your Object Storage system supports
|
<para>To discover whether your Object Storage system supports this
|
||||||
this feature, see <xref linkend="discoverability"
|
feature, see <xref linkend="discoverability"/>. Alternatively,
|
||||||
/>. Alternatively, check with your service provider.</para>
|
check with your service provider.</para>
|
||||||
<para>Use the auto-extract archive feature to upload a tar(1)
|
<para>Use the auto-extract archive feature to upload a tar(1)
|
||||||
archive file.</para>
|
archive file.</para>
|
||||||
<para>The Object Storage system extracts files from the archive
|
<para>The Object Storage system extracts files from the archive
|
||||||
file and creates an object.</para>
|
file and creates an object.</para>
|
||||||
<section xml:id="archive-auto-extract-put">
|
<section xml:id="archive-auto-extract-put">
|
||||||
<title>Auto-extract archive PUT request</title>
|
<title>Auto-extract archive request</title>
|
||||||
<para>To upload an archive file, you make a &PUT; request. Add
|
<para>To upload an archive file, you make a &PUT; request. Add
|
||||||
the
|
the
|
||||||
<parameter>extract-archive=<replaceable>format</replaceable></parameter>
|
<parameter>extract-archive=<replaceable>format</replaceable></parameter>
|
||||||
|
|
@ -74,22 +75,25 @@
|
||||||
archive.</para>
|
archive.</para>
|
||||||
<para>Use the <parameter>extract-archive</parameter>
|
<para>Use the <parameter>extract-archive</parameter>
|
||||||
query parameter to specify the format. Valid
|
query parameter to specify the format. Valid
|
||||||
values for this parameter are <literal>tar</literal>,
|
values for this parameter are
|
||||||
|
<literal>tar</literal>,
|
||||||
<literal>tar.gz</literal>, or
|
<literal>tar.gz</literal>, or
|
||||||
<literal>tar.bz2</literal>.</para>
|
<literal>tar.bz2</literal>.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</section>
|
</section>
|
||||||
<section xml:id="archive-auto-extract-response">
|
<section xml:id="archive-auto-extract-response">
|
||||||
<title>Auto-extract archive response: JSON</title>
|
<title>Auto-extract archive response</title>
|
||||||
<para>When Object Storage processes the request, it performs
|
<para>When Object Storage processes the request, it performs
|
||||||
multiple sub-operations. Even if all sub-operations fail,
|
multiple sub-operations. Even if all sub-operations fail,
|
||||||
the operation returns a <returnvalue>201</returnvalue>
|
the operation returns a <returnvalue>201</returnvalue>
|
||||||
<literal>Created</literal> status. You must examine the
|
<literal>Created</literal> status. Some sub-operations
|
||||||
response body to determine which members failed to result
|
might succeed while others fail: Examine the response body
|
||||||
in an object creation.</para>
|
to determine the results of each auto-extract archive
|
||||||
|
sub-operation.</para>
|
||||||
<para>You can set the <literal>Accept</literal> request header
|
<para>You can set the <literal>Accept</literal> request header
|
||||||
to one of these values, which defines the response format:</para>
|
to one of these values to define the response
|
||||||
|
format:</para>
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para><literal>text/plain</literal>. Formats response
|
<para><literal>text/plain</literal>. Formats response
|
||||||
|
|
@ -108,7 +112,36 @@
|
||||||
as XML.</para>
|
as XML.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
<para>For more information, see <xref
|
<para>The following auto-extract archive files example shows a
|
||||||
linkend="archive-auto-extract-response"/>.</para>
|
<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>
|
||||||
</section>
|
</section>
|
||||||
|
|
|
||||||
|
|
@ -2,59 +2,58 @@
|
||||||
<!DOCTYPE section [
|
<!DOCTYPE section [
|
||||||
<!-- Useful for describing APIs -->
|
<!-- Useful for describing APIs -->
|
||||||
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
||||||
|
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
|
||||||
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
||||||
]>
|
]>
|
||||||
<section xmlns="http://docbook.org/ns/docbook"
|
<section xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||||
xml:id="bulk-delete">
|
xml:id="bulk-delete">
|
||||||
|
<?dbhtml stop-chunking?>
|
||||||
<title>Bulk delete</title>
|
<title>Bulk delete</title>
|
||||||
<para>To discover whether your Object Storage system supports
|
<para>To discover whether your Object Storage system supports this
|
||||||
this feature, see <xref linkend="discoverability"
|
feature, see <xref linkend="discoverability"/>. Alternatively,
|
||||||
/>. Alternatively, check with your service provider.</para>
|
check with your service provider.</para>
|
||||||
<para>With bulk delete, you can delete up to 10,000 (configurable)
|
<para>With bulk delete, you can delete up to 10,000 objects or
|
||||||
objects or containers in one request. The objects to be
|
containers (configurable) in one request.</para>
|
||||||
deleted are listed in the body of a &POST; operation. Use
|
|
||||||
the <parameter>bulk-delete</parameter> query parameter to
|
|
||||||
indicate that you are performing a bulk delete operation
|
|
||||||
instead of a normal delete.</para>
|
|
||||||
<section xml:id="bulk-delete-request">
|
<section xml:id="bulk-delete-request">
|
||||||
<title>Bulk delete request body</title>
|
<title>Bulk delete request</title>
|
||||||
<para>To perform a bulk delete operation, add the
|
<para>To perform a bulk delete operation, add the
|
||||||
<parameter>bulk-delete</parameter> query parameter to
|
<parameter>bulk-delete</parameter> query parameter to
|
||||||
the path. The path should be the account, such as
|
the path of a &POST; or &DELETE; operation.</para>
|
||||||
<literal>/v1/12345678912345</literal>), that contains
|
<note>
|
||||||
the objects and containers. You must set the
|
<para>The &DELETE; operation is supported for backwards
|
||||||
<literal>Content-Type</literal> request header to
|
compatibility.</para>
|
||||||
<literal>text/plain</literal>.</para>
|
</note>
|
||||||
<para>In the request body, specify a list of objects or
|
<para>The path is the account, such as
|
||||||
containers names that are separated by a newline
|
<literal>/v1/12345678912345</literal>, that contains
|
||||||
character.</para>
|
the objects and containers.</para>
|
||||||
<para>In addition:</para>
|
<para>In the request body of the &POST; or &DELETE; operation,
|
||||||
|
list the objects or containers to be deleted. Separate
|
||||||
|
each name with a newline character. You can include a
|
||||||
|
maximum of 10,000 items (configurable) in the list.</para>
|
||||||
|
<para>In addition, you must:</para>
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>You must UTF-8-encode and then URL-encode the
|
<para>UTF-8-encode and then URL-encode the
|
||||||
names.</para>
|
names.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>To indicate an object, specify the container and
|
<para>To indicate an object, specify the container and
|
||||||
object name as:
|
object name as:
|
||||||
<literal><replaceable>CONTAINER_NAME</replaceable>/<replaceable>OBJECT_NAME</replaceable></literal></para>
|
<literal><replaceable>CONTAINER_NAME</replaceable>/<replaceable>OBJECT_NAME</replaceable></literal>.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>To indicate a container, specify the container
|
<para>To indicate a container, specify the container
|
||||||
name as:
|
name as:
|
||||||
<literal><replaceable>CONTAINER_NAME</replaceable></literal></para>
|
<literal><replaceable>CONTAINER_NAME</replaceable></literal>.
|
||||||
</listitem>
|
Ensure that the container is empty. If it contains
|
||||||
<listitem>
|
objects, Object Storage cannot delete the
|
||||||
<para>A container must be empty. If it contains
|
|
||||||
objects, Object Storage does not delete the
|
|
||||||
container.</para>
|
container.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>You can include a maximum of 10,000 items in the
|
<para>Set the <literal>Content-Type</literal> request
|
||||||
list. You can configure the maximum number of
|
header to <literal>text/plain</literal>.</para>
|
||||||
items value.</para>
|
|
||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</section>
|
</section>
|
||||||
|
|
@ -63,11 +62,13 @@
|
||||||
<para>When Object Storage processes the request, it performs
|
<para>When Object Storage processes the request, it performs
|
||||||
multiple sub-operations. Even if all sub-operations fail,
|
multiple sub-operations. Even if all sub-operations fail,
|
||||||
the operation returns a <returnvalue>200</returnvalue>
|
the operation returns a <returnvalue>200</returnvalue>
|
||||||
status. You must examine the response body to determine
|
status. The bulk operation returns a response body that
|
||||||
which members failed to result in an object
|
contains details that indicate which sub-operations have
|
||||||
deletion.</para>
|
succeeded and failed. Some sub-operations might succeed
|
||||||
|
while others fail: Examine the response body to determine
|
||||||
|
the results of each delete sub-operation.</para>
|
||||||
<para>You can set the <literal>Accept</literal> request header
|
<para>You can set the <literal>Accept</literal> request header
|
||||||
to one of these values, which defines the response
|
to one of these values to define the response
|
||||||
format:</para>
|
format:</para>
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
|
|
@ -87,73 +88,24 @@
|
||||||
as XML.</para>
|
as XML.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
<para>For more information, see <xref
|
|
||||||
linkend="response-body-bulk-delete"/>.</para>
|
|
||||||
</section>
|
|
||||||
<section xml:id="response-body-bulk-delete">
|
|
||||||
<title>Response body for bulk operations</title>
|
|
||||||
<para>Some bulk operations, such as bulk delete and
|
|
||||||
auto-extract archive files, perform multiple
|
|
||||||
sub-operations. Some sub-operations might succeed while
|
|
||||||
others fail. The bulk operation returns a response body
|
|
||||||
that contains details that indicate which sub-operations
|
|
||||||
have succeeded and failed.</para>
|
|
||||||
<para>You can set the <literal>Accept</literal> request header
|
|
||||||
to define the response format.</para>
|
|
||||||
<para>The response body contains the following
|
<para>The response body contains the following
|
||||||
information:</para>
|
information:</para>
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>The number of files actually deleted or created,
|
<para>The number of files actually deleted.</para>
|
||||||
depending on context.</para>
|
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>The number of not found objects. For bulk delete
|
<para>The number of not found objects.</para>
|
||||||
only.</para>
|
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Errors. A list of object names and associated
|
<para>Errors. A list of object names and associated
|
||||||
error statuses for the objects that failed to
|
error statuses for the objects that failed to
|
||||||
create or delete. The format depends on the value
|
delete. The format depends on the value that you
|
||||||
you set in the <literal>Accept</literal>
|
set in the <literal>Accept</literal>
|
||||||
header.</para>
|
header.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
<para>The following auto-extract archive files example shows a
|
<para>The following bulk delete response is in
|
||||||
<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. This
|
|
||||||
example output has been reformatted with whitespace to
|
|
||||||
make it easier to read. The actual response has no such
|
|
||||||
whitespace.</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>
|
|
||||||
<para>The following bulk delete example response is in
|
|
||||||
<literal>application/xml</literal> format. In this
|
<literal>application/xml</literal> format. In this
|
||||||
example, the <literal>mycontainer</literal> container is
|
example, the <literal>mycontainer</literal> container is
|
||||||
not empty, so it cannot be deleted.</para>
|
not empty, so it cannot be deleted.</para>
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue