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.
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.
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
