openstack/openstack-manuals
Code Issues Proposed changes

Adds retrieving large lists info 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: I0ee8366bc88985ba985518c8c014a03af6bdc05a
Partial-bug: 1392382
This commit is contained in:
Erik Wilson 2014-12-15 16:17:10 -06:00
parent bc24396c3c
commit d80560cf95
2 changed files with 108 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

@ -132,4 +132,5 @@ X-Timestamp: 1392684036.33306</computeroutput></screen>
<xi:include href="section_object-api-response-formats.xml"/>
<xi:include href="section_object-api-create-large-objects.xml"/>
<xi:include href="section_object-api-versioning.xml"/>
<xi:include href="section_object-api-large-lists.xml"/>
</section>

107
doc/user-guide/section_object-api-large-lists.xml Normal file
View File

@ -0,0 +1,107 @@
<?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="large-lists">
<title>Page through large lists of containers or objects</title>
<para>If you have a large number of containers or objects, you can
use the <parameter>marker</parameter>,
<parameter>limit</parameter>, and
<parameter>end_marker</parameter> parameters to control
how many items are returned in a list and where the list
starts or ends.</para>
<variablelist>
<varlistentry>
<term><parameter>marker</parameter></term>
<listitem>
<para>When you request a list of containers or
objects, Object Storage returns a maximum of
10,000 names for each request. To get subsequent
names, you must make another request with the
<parameter>marker</parameter> parameter. Set
the <literal>marker</literal> parameter to the
name of the last item returned in the previous
list. You must URL-encode the
<parameter>marker</parameter> value before you
send the HTTP request. Object Storage returns a
maximum of 10,000 names starting after the last
item returned.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>limit</parameter></term>
<listitem>
<para>To return fewer than 10,000 names, use the
<parameter>limit</parameter> parameter. If the
number of names returned equals the specified
<parameter>limit</parameter> (or 10,000 if you
omit the <parameter>limit</parameter> parameter),
you can assume there are more names to list. If
the number of names in the list is exactly
divisible by the <parameter>limit</parameter>
value, the last request has no content.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>end_marker</parameter></term>
<listitem>
<para>Limits the result set to names that are less
than the <parameter>end_marker</parameter>
parameter value. You must URL-encode the
<parameter>end_marker</parameter> value before
you send the HTTP request.</para>
</listitem>
</varlistentry>
</variablelist>
<procedure>
<title>To page through a large list of containers</title>
<para>Assume the following list of container names:</para>
<literallayout class="monospaced">apples
bananas
kiwis
oranges
pears</literallayout>
<step>
<para>Use a <parameter>limit</parameter> of two:</para>
<screen><userinput># curl -i $publicURL/?limit=2 -X GET -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>apples
bananas</computeroutput></screen>
<para>Because two container names are returned, there are
more names to list.</para>
</step>
<step>
<para>Make another request with a
<parameter>marker</parameter> parameter set to the
name of the last item returned:</para>
<screen><userinput># curl -i $publicURL/?limit=2&amp;amp;marker=bananas -X GET -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>kiwis
oranges</computeroutput></screen>
<para>Again, two items are returned, and there might be
more.</para>
</step>
<step>
<para>Make another request with a
<parameter>marker</parameter> of the last item
returned:</para>
<screen><userinput># curl -i $publicURL/?limit=2&amp;amp;marker=oranges -X GET -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>pears</computeroutput></screen>
<para>You receive a one-item response, which is fewer than
the <parameter>limit</parameter> number of names. This
indicates that this is the end of the list.</para>
</step>
<step>
<para>Use the <parameter>end_marker</parameter> parameter
to limit the result set to object names that are less
than the <parameter>end_marker</parameter> parameter
value:</para>
<screen><userinput># curl -i $publicURL/?end_marker=oranges -X GET -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>apples
bananas
kiwis</computeroutput></screen>
<para>You receive a result set of all container names
before the <parameter>end-marker</parameter>
value.</para>
</step>
</procedure>
</section>