openstack/openstack-manuals
Code Issues Proposed changes

Adds bulk delete information to End User Guide

Browse Source 
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: I78c69ba22a61df7d9cbff17bf7381ecb904ac18b
Partial-bug: 1392382
This commit is contained in:
Erik Wilson 2015-01-20 13:14:12 -06:00
parent 663f5d2c7a
commit 72de76c851
2 changed files with 116 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/user-guide/section_cli_swift_howto.xml
View File

@ -135,4 +135,5 @@ X-Timestamp: 1392684036.33306</computeroutput></screen>
<xi:include href="section_object-api-large-lists.xml"/>
<xi:include href="section_object-api-archive-auto-extract.xml"/>
<xi:include href="section_object-api-pseudo-hier-folders.xml"/>
<xi:include href="section_object-api-bulk-delete.xml"/>
</section>

115
doc/user-guide/section_object-api-bulk-delete.xml Normal file
View File

@ -0,0 +1,115 @@
<?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="bulk-delete">
<?dbhtml stop-chunking?>
<title>Bulk delete</title>
<para>With bulk delete, you can delete up to 10,000 objects or
containers (configurable) in one request.</para>
<section xml:id="bulk-delete-request">
<title>Bulk delete request</title>
<para>To perform a bulk delete operation, add the
<parameter>bulk-delete</parameter> query parameter to
the path of a &POST; or &DELETE; operation.</para>
<note>
<para>The &DELETE; operation is supported for backwards
compatibility.</para>
</note>
<para>The path is the account, such as
<literal>/v1/12345678912345</literal>, that contains
the objects and containers.</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>
<listitem>
<para>UTF-8-encode and then URL-encode the
names.</para>
</listitem>
<listitem>
<para>To indicate an object, specify the container and
object name as:
<literal><replaceable>CONTAINER_NAME</replaceable>/<replaceable>OBJECT_NAME</replaceable></literal>.</para>
</listitem>
<listitem>
<para>To indicate a container, specify the container
name as:
<literal><replaceable>CONTAINER_NAME</replaceable></literal>.
Make sure that the container is empty. If it
contains objects, Object Storage cannot delete the
container.</para>
</listitem>
<listitem>
<para>Set the <literal>Content-Type</literal> request
header to <literal>text/plain</literal>.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="bulk-delete-response">
<title>Bulk delete 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>200</returnvalue>
status. The bulk operation returns a response body that
contains details that indicate which sub-operations have
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
to one of the following values to define 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>The response body contains the following
information:</para>
<itemizedlist>
<listitem>
<para>The number of files actually deleted.</para>
</listitem>
<listitem>
<para>The number of not found objects.</para>
</listitem>
<listitem>
<para>Errors. A list of object names and associated
error statuses for the objects that failed to
delete. The format depends on the value that you
set in the <literal>Accept</literal>
header.</para>
</listitem>
</itemizedlist>
<para>The following bulk delete response is in
<literal>application/xml</literal> format. In this
example, the <literal>mycontainer</literal> container is
not empty, so it cannot be deleted.</para>
<screen><computeroutput>&lt;delete>
&lt;number_deleted>2&lt;/number_deleted>
&lt;number_not_found>4&lt;/number_not_found>
&lt;errors>
&lt;object>
&lt;name>/v1/12345678912345/mycontainer&lt;/name>
&lt;status>409 Conflict&lt;/status>
&lt;/object>
&lt;/errors>
&lt;/delete></computeroutput></screen>
</section>
</section>