Quickly Finding Objects Using the vCloud API Query Service

In earlier releases of vCloud Director (1.0), to find a particular vCloud object using the vCloud API, you always had start at the root of your vCloud instance and traverse through the links to find the object in question. This meant that users were required to make multiple API requests to vCloud Director to discover the various links to a given set of objects such a Virtual Machine or Catalog.

With the release of vCloud Director 1.5, a new feature was introduced called the Query Service that provides a quick and efficient way of searching for objects in vCloud Director. If we take a look at a very simple query such as finding all Virtual Machines in an Organization, using the old method we require a minimum of 4 API requests. If we use the new Query Service, it is just a single API request to find all Virtual Machines within an Organization.

Here is pseudo REST API calls for both the old and new method for searching for all Virtual Machines in an Organization.

New Method:

As you can see from the above, with only a single request, we can quickly find all the Virtual Machines within our Organization without having to traverse multiple links to get to our results. Let’s take a look at how the Query Service works for searching for other objects in vCloud Director.

Typed Queries:

These queries require users to construct a query URL for a particular vCloud object type such as a vApp or catalog. When you first login to vCloud Director, you may have noticed several links that you can access, one of which is the “query” link.

To retrieve the list of the available query types that you have permission to access, you just need to perform a GET operation on the query URL. There are a total of 47 possible typed queries which are all documented in the vCloud API Programming Guide. To use one of the query types, you just need to specify the name of type using the following URL format: https://vcd/api/query?type=[NAME_TYPE]

Note: The query name type is case-sensitive, please refer to the vCloud API documentation for all types or via the GET operation.
Here is an example of our earlier task of finding all Virtual Machines within an Organization using a typed query:$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: HGh0Xmeez8samugDzmMHjRqU1YWIfcIno0b08+MNkxQ=” -X GET https://vcd/api/query?type=vm

Using typed queries is very straightforward and you can always check to see the available query types by performing the GET operation on the query URL, this is especially important as different queries will be available depending on your account privileges.

Packaged Queries:

These queries are provided through well-known URLs and categorized by user, admin and extension queries. There are currently 21 possible packaged queries which are also documented in the vCloud API Programming Guide. Package queries only contain a subset of the typed queries, and will be limited in its vCloud object search capabilities.

Here is an example of the same task of finding all Virtual Machines within an Organization using a packaged query:$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: HGh0Xmeez8samugDzmMHjRqU1YWIfcIno0b08+MNkxQ=” -X GET https://vcd/api/vms/query

The ability to quickly search for specific vCloud objects using the Query Service is a great feature, but the real power is when you can search based on specific properties of an object.

Query Parameters:

Built into the Query Service, there are a set of query parameters that can be used to augment and filter the search results. These include name of the query type, sort on a specific property in either ascending or descending order, specific page, page size, format, specific fields, offset or filter expressions (equals, not-equals, logical AND and logical OR). You may have noticed the filter expressions are currently limited to equals and not-equals and does not support other common comparators such as greater-than, less-than, greater-than equal to and less-than equal to. For more details about the query parameters, please refer to the Query Parameters documentation. The majority of the query parameters can be used with both typed and packaged queries.

Putting all this together, we can leverage the new Query Service to craft some complex queries provided out of the box by vCloud Director, whereas before, all this logic had to be written by the client to perform any type of search functionality.

Let’s expand on our earlier example and let’s find find all powered on Virtual Machines within the Organization that are not vAppTemplates using a typed query with the “fields” and “filter” query parameters.

There are a lot of useful typed queries that perform some complex relations, some that might come in handy for System administrators of a vCloud Director instance are the ones that end with “relation” such as datastoreProviderVdcRelation which provide a resource related entity mapping to to one of the vCloud constructs.

The query above provides a mapping of all datastore to their respective Provider vDC which can be extremely helpful for Administrators, especially when it comes to datastore maintenances and quickly identifying the vCenter Server that is required to perform the maintenance.

So the next time you want to find an object(s) in vCloud Director, be sure to leverage the powerful new Query Service for optimized and efficient searches.

Get notification of new blog postings and more by following lamw on Twitter: @lamw

About William Lam

William Lam works as a Staff Engineer in VMware R&D and focuses Automation, Integration and Operations. William also runs a personal blog at www.virtuallyghetto.com. Previous to VMware, he was a Systems Engineer managing large vSphere installations and UNIX/Linux systems.

One thought on “Quickly Finding Objects Using the vCloud API Query Service”

The Rolex Watches set all needs of people from different walks of life, be it students, professionals, businessmen or homemakers. Bear one of these at your operate open space and you do not have to try compact to print your boss. Very soon, you will be given all fruit of the plum-tree offers and your path for result will be paved. You will achieve result in all phases of life. These watches will become an whole part of your life and you will not be able to get apart from them. Since these are reasonably priced, you can have many of these without flaming a aperture in your pocket. This will ensure that you have different watches which set your made up of many apparel.