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
95 lines
5.4 KiB
XML
95 lines
5.4 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section [
|
|
<!-- Useful for describing APIs -->
|
|
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
|
<!ENTITY HEAD '<command xmlns="http://docbook.org/ns/docbook">HEAD</command>'>
|
|
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
|
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
|
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</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="pseudo-hierarchical-folders-directories">
|
|
<title>Pseudo-hierarchical folders and directories</title>
|
|
<!-- reworked this section / as path and its elements / are not supported - dsh - 02-16-12 -->
|
|
<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 examples show
|
|
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>. Keep in mind that the container
|
|
name is not displayed in the example, but that 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>
|
|
<literallayout class="monospaced">GET /v1/AccountString/backups</literallayout>
|
|
<para>The system returns status code 2xx (between 200 and 299,
|
|
inclusive) and the requested list of the objects.</para>
|
|
<literallayout class="monospaced">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</literallayout>
|
|
<para>
|
|
<!-- The JIRA ticket / doc-97 subsumed / to this location - dsh - 02-03-12 -->Use
|
|
the delimiter parameter to limit the displayed results.
|
|
You can use any character as a delimiter. However, to use
|
|
<code>delimiter</code> with pseudo-directories, use
|
|
the parameter slash (<literal>/</literal>).</para>
|
|
<literallayout class="monospaced">GET /v1/AccountString/backups?delimiter=/</literallayout>
|
|
<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. Keep in mind that 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>
|
|
<literallayout class="monospaced">photos/</literallayout>
|
|
<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>
|
|
<literallayout class="monospaced">GET /v1/AccountString/backups?prefix=photos/&delimiter=/</literallayout>
|
|
<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>
|
|
<literallayout class="monospaced">photos/animals/
|
|
photos/me.jpg
|
|
photos/plants/</literallayout>
|
|
<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>
|
|
<literallayout class="monospaced">GET /v1/AccountString/backups?prefix=photos/animals/dogs/&delimiter=/ </literallayout>
|
|
<para>The system returns status code <returnvalue>2<replaceable>nn</replaceable></returnvalue> (between 200 and 299,
|
|
inclusive) and the objects and pseudo-directories within
|
|
the nested pseudo-directory.</para>
|
|
<literallayout class="monospaced">photos/animals/dogs/corgi.jpg
|
|
photos/animals/dogs/poodle.jpg
|
|
photos/animals/dogs/terrier.jpg</literallayout>
|
|
</example>
|
|
</section>
|