# Using OpenStack Object Store

Before working with the Object Store service, you’ll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the `conn` variable used in the examples below.

The primary resources of the Object Store service are containers and objects.

## Working with Containers

### Listing Containers

To list existing containers, use the `containers()` method.

    >>> for cont in conn.object_store.containers():
    ...     print cont
    ...
    openstack.object_store.v1.container.Container: {u'count': 5,
    u'bytes': 500, u'name': u'my container'}
    openstack.object_store.v1.container.Container: {u'count': 0,
    u'bytes': 0, u'name': u'empty container'}
    openstack.object_store.v1.container.Container: {u'count': 100,
    u'bytes': 1000000, u'name': u'another container'}

The `containers` method returns a generator which yields `Container` objects. It handles pagination for you, which can be adjusted via the `limit` argument. By default, the `containers` method will yield as many containers as the service will return, and it will continue requesting until it receives no more.

    >>> for cont in conn.object_store.containers(limit=500):
    ...     print(cont)
    ...
    <500 Containers>
    ... another request transparently made to the Object Store service
    <500 more Containers>
    ...

### Creating Containers

To create a container, use the `create_container()` method.

    >>> cont = conn.object_store.create_container(name="new container")
    >>> cont
    openstack.object_store.v1.container.Container: {'name': u'new container'}

### Working with Container Metadata

To get the metadata for a container, use the `get_container_metadata()` method. This method either takes the name of a container, or a `Container` object, and it returns a Container object with all of its metadata attributes set.

    >>> cont = conn.object_store.get_container_metadata("new container")
    openstack.object_store.v1.container.Container: {'content-length': '0',
    'x-container-object-count': '0', 'name': u'new container',
    'accept-ranges': 'bytes',
    'x-trans-id': 'tx22c5de63466e4c05bb104-0054740c39',
    'date': 'Tue, 25 Nov 2014 04:57:29 GMT',
    'x-timestamp': '1416889793.23520', 'x-container-read': '.r:mysite.com',
    'x-container-bytes-used': '0', 'content-type': 'text/plain; charset=utf-8'}

To set the metadata for a container, use the `set_container_metadata()` method. This method takes a `Container` object. For example, to grant another user write access to this container, you can call set_container_metadata passing it the Container to update and keyward argument key/value pairs representing the metadata name and value to set.

    >>> acl = "big_project:another_user"
    >>> conn.object_store.set_container_metadata(cont, write_ACL=acl)
    openstack.object_store.v1.container.Container: {'content-length': '0',
    'x-container-object-count': '0',
    'name': u'my new container', 'accept-ranges': 'bytes',
    'x-trans-id': 'txc3ee751f971d41de9e9f4-0054740ec1',
    'date': 'Tue, 25 Nov 2014 05:08:17 GMT',
    'x-timestamp': '1416889793.23520', 'x-container-read': '.r:mysite.com',
    'x-container-bytes-used': '0', 'content-type': 'text/plain; charset=utf-8',
    'x-container-write': 'big_project:another_user'}

## Working with Objects

Objects are held in containers. From an API standpoint, you work with them using similarly named methods, typically with an additional argument to specify their container.

### Listing Objects

To list the objects that exist in a container, use the `objects()` method.

If you have a `Container` object, you can pass it to `objects`.

    >>> print cont.name
    pictures
    >>> for obj in conn.object_store.objects(cont):
    ...     print obj
    ...
    openstack.object_store.v1.container.Object:
    {u'hash': u'0522d4ccdf9956badcb15c4087a0c4cb',
    u'name': u'pictures/selfie.jpg', u'bytes': 15744,
    'last-modified': u'2014-10-31T06:33:36.618640',
    u'last_modified': u'2014-10-31T06:33:36.618640',
    u'content_type': u'image/jpeg', 'container': u'pictures',
    'content-type': u'image/jpeg'}
    ...

Similar to the `containers()` method, `objects` returns a generator which yields `Object` objects stored in the container. It also handles pagination for you, which you can adjust with the `limit` parameter, otherwise making each request for the maximum that your Object Store will return.

If you have the name of a container instead of an object, you can also pass that to the `objects` method.

    >>> for obj in conn.object_store.objects("pictures".decode("utf8"),
                                             limit=100):
    ...     print obj
    ...
    <100 Objects>
    ... another request transparently made to the Object Store service
    <100 more Objects>

### Getting Object Data

Once you have an `Object`, you get the data stored inside of it with the `get_object_data()` method.

    >>> print ob.name
    message.txt
    >>> data = conn.object_store.get_object_data(ob)
    >>> print data
    Hello, world!

Additionally, if you want to save the object to disk, the `download_object()` convenience method takes an `Object` and a `path` to write the contents to.

    >>> conn.object_store.download_object(ob, "the_message.txt")

### Uploading Objects

Once you have data you’d like to store in the Object Store service, you use the `upload_object()` method. This method takes the `data` to be stored, along with at least an object `name` and the `container` it is to be stored in.

    >>> hello = conn.object_store.upload_object(container="messages",
                                                name="helloworld.txt",
                                                data="Hello, world!")
    >>> print hello
    openstack.object_store.v1.container.Object: {'content-length': '0',
    'container': u'messages', 'name': u'helloworld.txt',
    'last-modified': 'Tue, 25 Nov 2014 17:39:29 GMT',
    'etag': '5eb63bbbe01eeed093cb22bb8f5acdc3',
    'x-trans-id': 'tx3035d41b03334aeaaf3dd-005474bed0',
    'date': 'Tue, 25 Nov 2014 17:39:28 GMT',
    'content-type': 'text/html; charset=UTF-8'}

### Working with Object Metadata

Working with metadata on objects is identical to how it’s done with containers. You use the `get_object_metadata()` and `set_object_metadata()` methods.

The metadata attributes to be set can be found on the `Object` object.

    >>> secret.delete_after = 300
    >>> secret = conn.object_store.set_object_metadata(secret)

We set the `delete_after` value to 500 seconds, causing the object to be deleted in 300 seconds, or five minutes. That attribute corresponds to the `X-Delete-After` header value, which you can see is returned when we retrieve the updated metadata.

    >>> conn.object_store.get_object_metadata(ob)
    openstack.object_store.v1.container.Object: {'content-length': '11',
    'container': u'Secret Container',
    'name': u'selfdestruct.txt', 'x-delete-after': 300,
    'accept-ranges': 'bytes', 'last-modified': 'Tue, 25 Nov 2014 17:50:45 GMT',
    'etag': '5eb63bbbe01eeed093cb22bb8f5acdc3',
    'x-timestamp': '1416937844.36805',
    'x-trans-id': 'tx5c3fd94adf7c4e1b8f334-005474c17b',
    'date': 'Tue, 25 Nov 2014 17:50:51 GMT', 'content-type': 'text/plain'}

this page last updated: 2026-01-16 23:06:19

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.