Pseudo-hierarchical folders and directories¶
Although you cannot nest directories in OpenStack Object Storage, you
can simulate a hierarchical structure within a single container by
adding forward slash characters (/
) in the object name. To navigate
the pseudo-directory structure, you can use the delimiter
query
parameter. This example shows you how to use pseudo-hierarchical folders
and directories.
Note
In this example, the objects reside in a container called backups
.
Within that container, the objects are organized in a pseudo-directory
called photos
. 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 me.jpg
is
https://swift.example.com/v1/CF_xer7_343/backups/photos/me.jpg
.
List pseudo-hierarchical folders request: HTTP¶
To display a list of all the objects in the storage container, use
GET
without a delimiter
or prefix
.
$ curl -X GET -i -H "X-Auth-Token: $token" \
$publicurl/v1/AccountString/backups
The system returns status code 2xx (between 200 and 299, inclusive) and the requested list of the objects.
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
Use the delimiter parameter to limit the displayed results. To use
delimiter
with pseudo-directories, you must use the parameter slash
(/
).
$ curl -X GET -i -H "X-Auth-Token: $token" \
$publicurl/v1/AccountString/backups?delimiter=/
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 photos/
displays. The returned values from a slash
delimiter
query are not real objects. The value will refer to
a real object if it does not end with a slash. The pseudo-directories
have no content-type, rather, each pseudo-directory has
its own subdir
entry in the response of JSON and XML results.
For example:
[
{
"subdir": "photos/"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<container name="backups">
<subdir name="photos/">
<name>photos/</name>
</subdir>
</container>
Use the prefix
and delimiter
parameters to view the objects
inside a pseudo-directory, including further nested pseudo-directories.
$ curl -X GET -i -H "X-Auth-Token: $token" \
$publicurl/v1/AccountString/backups?prefix=photos/&delimiter=/
The system returns status code 2xx (between 200 and 299, inclusive) and the objects and pseudo-directories within the top level pseudo-directory.
photos/animals/
photos/me.jpg
photos/plants/
[
{
"subdir": "photos/animals/"
},
{
"hash": "b249a153f8f38b51e92916bbc6ea57ad",
"last_modified": "2015-12-03T17:31:28.187370",
"bytes": 2906,
"name": "photos/me.jpg",
"content_type": "image/jpeg"
},
{
"subdir": "photos/plants/"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<container name="backups">
<subdir name="photos/animals/">
<name>photos/animals/</name>
</subdir>
<object>
<name>photos/me.jpg</name>
<hash>b249a153f8f38b51e92916bbc6ea57ad</hash>
<bytes>2906</bytes>
<content_type>image/jpeg</content_type>
<last_modified>2015-12-03T17:31:28.187370</last_modified>
</object>
<subdir name="photos/plants/">
<name>photos/plants/</name>
</subdir>
</container>
You can create an unlimited number of nested pseudo-directories. To
navigate through them, use a longer prefix
parameter coupled with
the delimiter
parameter. In this sample output, there is a
pseudo-directory called dogs
within the pseudo-directory
animals
. To navigate directly to the files contained within
dogs
, enter the following command:
$ curl -X GET -i -H "X-Auth-Token: $token" \
$publicurl/v1/AccountString/backups?prefix=photos/animals/dogs/&delimiter=/
The system returns status code 2xx (between 200 and 299, inclusive) and the objects and pseudo-directories within the nested pseudo-directory.
photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg