Searching within vRealize Automation – Part 2 – REST API

In Part 1 of this article series, I wrote about using some of the more interesting queries possible through the vRealize Automation IaaS component.  Specifically, using the Model Manager calls from vRealize Orchestrator.  Here in Part 2, I will demonstrate yet another approach to searching – but this time from the new vRA REST API.

Getting into the API session

There are already a number of articles about getting into the REST API.  But in short, I used the Firefox plug-in “REST Client”.  See the screenshot below for the example of how to initiate the authenticated session in the REST Client.

URI: https://{vrahost}/identity/api/tokens

Notice the credentials being passed in the POST body?  This indicates the tenant as well, so the authentication URI is consistent across all tenants.

Another good step to complete is to validate your session.  See the screenshot below for the example of this being performed.

URI: https://{vrahost}/vcac/org/{tenant}/tokens/{tokenID}

Note that the “id” returned from the authentication call is now attached as an appendix to the URI call.  The successful validation is merely the HTTP 200 response code, to say that everything is OK.

Getting unfiltered content

The REST API is surprisingly easy to use, once you’ve done a little reading and poking around.  I was able to pickup some basic skills with just the regular documentation and playing with the running product.  I didn’t end up breaking anything, so I guess I did OK!

To get the entire list of currently provisioned items, those that I am entitled to see, it a simple API call as shown below.

URI: https://{vrahost}/catalog-service/api/consumer/resources

Note that the “id” token form the initial authentication is now being passed in a request header called “Authorization”.  This represents the current session, and seem to be valid for 24 hours (by default).

This API call will return ALL my items, and/or my group’s item.  However, my recent dealings with a customer were needing a way to efficiently lookup a specific item in vRA, if it existed at all.

Filtering by VM name – OData queries again!

As it turns out, the vRA REST API also supports some of the OData query syntax that was introduced in Part 1 of this blog.  In particular, you can use the $filter parameter to submit a query to the API call above.  See the below example for searching for a specific item (VM) by name.

URI: https://{vrahost}/catalog-service/api/consumer/resources?$filter=name eq ‘win042’

Pay attention!  In this query, I am actually passing spaces in my URI!  I presume this is being encoded for me by the REST Client plug-in, otherwise I assume planes would start falling out of the sky!  According to the Programming Guide, the query is happy to take encoded or non-encoded form.  The proper encoded call equivalent would look like one of the below.

URI: https://{vrahost}/catalog-service/api/consumer/resources?$filter=name+eq+%27win042%27

URI: https://{vrahost}/catalog-service/api/consumer/resources?$filter=name%20eq%20%27win042%27

As you can check for yourself, if the query succeeds, it will return only the items matching the query – success!  Please see below for an example of the query returning no matches.

As you might notice, the API call still succeeds and returns content – it just returns a JSON document with no members in the content section.

Other query parameters

As per the previous article, the vRA REST API supports a few more of the OData parameter types.  One parameter type - $select – is missing from the API, presumably because the structured JSON data returned is easier to navigate in full, rather than if it were teased apart into flat fields.

The table below is replicated from the in-built documentation within each vRealize Automation appliance, which is a copy of the online documentation.  Go ahead, check it out on your own appliance!

Appliance Source:  https://{vrahost}/catalog-service/api/docs/resource_Resource.html

Online source: http://pubs.vmware.com/vra-62/topic/com.vmware.vra.restapi.doc/catalog-service/api/docs/resource_Resource.html

name	description	type	default
managedOnly	if true, the returned requests are from User's managed subtenants.	query
page	Page Number	query	1
limit	Number of entries per page	query	20
$orderby	Multiple comma-separated properties sorted in ascending or descending order	query
$top	Sets the number of returned entries from the top of the response (total number per page in relation to skip)	query
$skip	Sets how many entries you would like to skip	query
$filter	Boolean expression for whether a particular entry should be included in the response	query

That concludes this series of articles on searching with vRealize Automation using both Orchestrator and the REST API.  Please let me know any feedback or comments below!