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
163 lines
7.6 KiB
XML
163 lines
7.6 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>'>
|
|
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</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="bulk-delete">
|
|
<title>Bulk delete</title>
|
|
<para>To discover whether your Object Storage system supports
|
|
this feature, see <xref linkend="discoverability"
|
|
/>. Alternatively, check with your service provider.</para>
|
|
<para>With bulk delete, you can delete up to 10,000 (configurable)
|
|
objects or containers in one request. The objects to be
|
|
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">
|
|
<title>Bulk delete request body</title>
|
|
<para>To perform a bulk delete operation, add the
|
|
<parameter>bulk-delete</parameter> query parameter to
|
|
the path. The path should be the account, such as
|
|
<literal>/v1/12345678912345</literal>), that contains
|
|
the objects and containers. You must set the
|
|
<literal>Content-Type</literal> request header to
|
|
<literal>text/plain</literal>.</para>
|
|
<para>In the request body, specify a list of objects or
|
|
containers names that are separated by a newline
|
|
character.</para>
|
|
<para>In addition:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>You must 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></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>A container must be empty. If it contains
|
|
objects, Object Storage does not delete the
|
|
container.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>You can include a maximum of 10,000 items in the
|
|
list. You can configure the maximum number of
|
|
items value.</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. You must examine the response body to determine
|
|
which members failed to result in an object
|
|
deletion.</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="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
|
|
information:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The number of files actually deleted or created,
|
|
depending on context.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The number of not found objects. For bulk delete
|
|
only.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Errors. A list of object names and associated
|
|
error statuses for the objects that failed to
|
|
create or delete. The format depends on the value
|
|
you set in the <literal>Accept</literal>
|
|
header.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<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. 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
|
|
example, the <literal>mycontainer</literal> container is
|
|
not empty, so it cannot be deleted.</para>
|
|
<programlisting language="xml"><xi:include parse="text" href="samples/bulk-delete-response.xml"/></programlisting>
|
|
</section>
|
|
</section>
|