openstack/openstack-manuals
Code Issues Proposed changes

Adds pseudo-hierarchical folders 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: Ic1616a970355707a48997e5b006e68164fa731f9
Partial-bug: 1392382
This commit is contained in:
Erik Wilson 2014-12-12 16:10:35 -06:00 committed by Gauvain Pocentek
parent dab1bf5a99
commit e0e443e89f
2 changed files with 81 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

@ -134,4 +134,5 @@ X-Timestamp: 1392684036.33306</computeroutput></screen>
<xi:include href="section_object-api-create-large-objects.xml"/>
<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"/>
</section>

80
doc/user-guide/section_object-api-pseudo-hier-folders.xml Normal file
View File

@ -0,0 +1,80 @@
<?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="pseudo-hierarchical-folders-directories">
<title>Pseudo-hierarchical folders and directories</title>
<para>Although you cannot nest directories in OpenStack Object
Storage, you can simulate a hierarchical structure within a
single container by adding forward slash characters
(<literal>/</literal>) in the object name. To navigate the
pseudo-directory structure, you can use the
<code>delimiter</code> query parameter. This example shows
you how to use pseudo-hierarchical folders and
directories.</para>
<note>
<para>In this example, the objects reside in a container
called <code>backups</code>. Within that container, the
objects are organized in a pseudo-directory called
<code>photos</code>. The container name is not
displayed in the example, but it is a part of the object
URLs. For instance, the URL of the picture
<code>me.jpg</code> is
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/backups/photos/me.jpg</uri>.</para>
</note>
<example>
<title>List pseudo-hierarchical folders request: HTTP</title>
<para>To display a list of all the objects in the storage
container, use &GET; without a <code>delimiter</code> or
<code>prefix</code>.</para>
<screen><prompt>$</prompt> <userinput>curl -X GET -i -H "X-Auth-Token: $token" $publicurl/v1/AccountString/backups</userinput></screen>
<para>The system returns status code 2xx (between 200 and 299,
inclusive) and the requested list of the objects.</para>
<screen><computeroutput>photos/animals/cats/persian.jpg
photos/animals/cats/siamese.jpg
photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg
photos/me.jpg
photos/plants/fern.jpg
photos/plants/rose.jpg</computeroutput></screen>
<para>Use the delimiter parameter to limit the displayed
results. To use <code>delimiter</code> with
pseudo-directories, you must use the parameter slash (<literal>/</literal>).</para>
<screen><prompt>$</prompt> <userinput>curl -X GET -i -H "X-Auth-Token: $token" $publicurl/v1/AccountString/backups?delimiter=/</userinput></screen>
<para>The system returns status code 2xx (between 200 and 299,
inclusive) and the requested matching objects. Because you
use the slash, only the pseudo-directory
<code>photos/</code> displays. The returned values
from a slash <code>delimiter</code> query are not real
objects. They have a content-type of
<literal>application/directory</literal> and are in
the <literal>subdir</literal> section of JSON and XML
results.</para>
<screen><computeroutput>photos/</computeroutput></screen>
<para>Use the <code>prefix</code> and <code>delimiter</code>
parameters to view the objects inside a pseudo-directory,
including further nested pseudo-directories.</para>
<screen><prompt>$</prompt> <userinput>curl -X GET -i -H "X-Auth-Token: $token" $publicurl/v1/AccountString/backups?prefix=photos/&#38;delimiter=/</userinput></screen>
<para>The system returns status code 2xx (between 200 and 299,
inclusive) and the objects and pseudo-directories within
the top level pseudo-directory.</para>
<screen><computeroutput>photos/animals/
photos/me.jpg
photos/plants/</computeroutput></screen>
<para>You can create an unlimited number of nested
pseudo-directories. To navigate through them, use a longer
<code>prefix</code> parameter coupled with the
<code>delimiter</code> parameter. In this sample
output, there is a pseudo-directory called
<code>dogs</code> within the pseudo-directory
<code>animals</code>. To navigate directly to the
files contained within <code>dogs</code>, enter the
following command:</para>
<screen><prompt>$</prompt> <userinput>curl -X GET -i -H "X-Auth-Token: $token" $publicurl/v1/AccountString/backups?prefix=photos/animals/dogs/&#38;delimiter=/</userinput></screen>
<para>The system returns status code 2xx (between 200 and 299,
inclusive) and the objects and pseudo-directories within
the nested pseudo-directory.</para>
<screen><computeroutput>photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg</computeroutput></screen>
</example>
</section>