d80560cf95
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
108 lines
5.2 KiB
XML
108 lines
5.2 KiB
XML
<?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;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;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>
|