From 37b1c2901ec29b43feb42d842413b2cbd3ffadde Mon Sep 17 00:00:00 2001 From: "jaypipes@gmail.com" <> Date: Wed, 25 May 2011 11:03:16 -0400 Subject: [PATCH] Documentation for new results filtering in the API and client. --- doc/source/client.rst | 52 ++++++++++++++++++++++++++++++++++++++- doc/source/glanceapi.rst | 36 +++++++++++++++++++++++++++ doc/source/registries.rst | 37 ++++++++++++++++++++++++++++ 3 files changed, 124 insertions(+), 1 deletion(-) diff --git a/doc/source/client.rst b/doc/source/client.rst index 9a4182cb94..2b4132c8d4 100644 --- a/doc/source/client.rst +++ b/doc/source/client.rst @@ -63,6 +63,57 @@ Using Glance's Client, we can do this using the following code print c.get_images_detailed() +Filtering Images Returned via ``get_images()`` and ``get_images_detailed()`` +---------------------------------------------------------------------------- + +Both the ``get_images()`` and ``get_images_detailed()`` methods take query +parameters that serve to filter the returned list of images. + +When calling, simple pass an optional dictionary to the method containing +the filters by which you wish to limit results, with the filter keys being one +or more of the below: + +* ``name: NAME`` + + Filters images having a ``name`` attribute matching ``NAME``. + +* ``container_format: FORMAT`` + + Filters images having a ``container_format`` attribute matching ``FORMAT`` + + For more information, see :doc:`About Disk and Container Formats ` + +* ``disk_format: FORMAT`` + + Filters images having a ``disk_format`` attribute matching ``FORMAT`` + + For more information, see :doc:`About Disk and Container Formats ` + +* ``status: STATUS`` + + Filters images having a ``status`` attribute matching ``STATUS`` + + For more information, see :doc:`About Image Statuses ` + +* ``size_min: BYTES`` + + Filters images having a ``size`` attribute greater than or equal to ``BYTES`` + +* ``size_max: BYTES`` + + Filters images having a ``size`` attribute less than or equal to ``BYTES`` + +Here's a quick example that will return all images less than or equal to 5G +in size and in the `saving` status. + +.. code-block:: python + + from glance.client import Client + + c = Client("glance.example.com", 9292) + + filters = {'status': 'saving', 'size_max': (5 * 1024 * 1024 * 1024)} + print c.get_images_detailed(filters) Requesting Detailed Metadata on a Specific Image ------------------------------------------------ @@ -86,7 +137,6 @@ first public image returned, we can use the following code print c.get_image_meta("http://glance.example.com/images/1") - Retrieving a Virtual Machine Image ---------------------------------- diff --git a/doc/source/glanceapi.rst b/doc/source/glanceapi.rst index 48e7c10aec..eff6f91164 100644 --- a/doc/source/glanceapi.rst +++ b/doc/source/glanceapi.rst @@ -92,6 +92,42 @@ JSON-encoded mapping in the following format:: The `checksum` field is an MD5 checksum of the image file data +Filtering Images Returned via ``GET /images`` and ``GET /images/detail`` +------------------------------------------------------------------------ + +Both the ``GET /images`` and ``GET /images/detail`` requests take query +parameters that serve to filter the returned list of images. The following +list details these query parameters. + +* ``name=NAME`` + + Filters images having a ``name`` attribute matching ``NAME``. + +* ``container_format=FORMAT`` + + Filters images having a ``container_format`` attribute matching ``FORMAT`` + + For more information, see :doc:`About Disk and Container Formats ` + +* ``disk_format=FORMAT`` + + Filters images having a ``disk_format`` attribute matching ``FORMAT`` + + For more information, see :doc:`About Disk and Container Formats ` + +* ``status=STATUS`` + + Filters images having a ``status`` attribute matching ``STATUS`` + + For more information, see :doc:`About Image Statuses ` + +* ``size_min=BYTES`` + + Filters images having a ``size`` attribute greater than or equal to ``BYTES`` + +* ``size_max=BYTES`` + + Filters images having a ``size`` attribute less than or equal to ``BYTES`` Requesting Detailed Metadata on a Specific Image ------------------------------------------------ diff --git a/doc/source/registries.rst b/doc/source/registries.rst index 6aafcbc6cb..c53010f7e5 100644 --- a/doc/source/registries.rst +++ b/doc/source/registries.rst @@ -46,6 +46,43 @@ The following is a brief description of the Glance API:: PUT /images/ Update metadata about an existing image DELETE /images/ Remove an image's metadata from the registry +Filtering Images Returned via ``GET /images`` and ``GET /images/detail`` +------------------------------------------------------------------------ + +Both the ``GET /images`` and ``GET /images/detail`` requests take query +parameters that serve to filter the returned list of images. The following +list details these query parameters. + +* ``name=NAME`` + + Filters images having a ``name`` attribute matching ``NAME``. + +* ``container_format=FORMAT`` + + Filters images having a ``container_format`` attribute matching ``FORMAT`` + + For more information, see :doc:`About Disk and Container Formats ` + +* ``disk_format=FORMAT`` + + Filters images having a ``disk_format`` attribute matching ``FORMAT`` + + For more information, see :doc:`About Disk and Container Formats ` + +* ``status=STATUS`` + + Filters images having a ``status`` attribute matching ``STATUS`` + + For more information, see :doc:`About Image Statuses ` + +* ``size_min=BYTES`` + + Filters images having a ``size`` attribute greater than or equal to ``BYTES`` + +* ``size_max=BYTES`` + + Filters images having a ``size`` attribute less than or equal to ``BYTES`` + ``POST /images`` ----------------