Home > Blogs > VMware vSphere Blog


Using the Entity Resolver in the vCloud API

By William Lam, Sr. Technical Marketing Engineer

I recently received a question about whether it was possible to look up a vCloud Director Object with just knowing the object’s unique identifier (URN format) using the vCloud API? The use case for this was to store the vCloud Director’s unique object ID in an external system and be able to quickly access the objects without having to traverse the vCloud Director Inventory each time. The Query Service API can easily service this request, but currently today it does not support filtering by the HREF or ID property.


However, it is still possible to lookup a vCloud Director Object using its ID and leveraging the Entity Resolver which is part of the vCloud API. The Entity Resolver provides a mechanism to transform a unique vCloud Director Object ID (URN format) to all possible href representations and allows you to quickly access the object in question. I thought this might be a good opportunity to share some information about the Entity Resolver as it may not be very well known.

When you first login to a vCloud Director instance using the vCloud API, you will see several links such as: query (Query Service), org (All Organizations you  have access to), admin/extension (if you are logging in as a System Admin) and entity which provides the Entity Resolver functionality.

Entity-1

To use the Entity Resolver, you just need to perform a GET operation on the entity URL with the appended vCloud Director Object ID. Let’s say our entity URL is https://vcd/api/entity and our object ID is urn:vcloud:vm:515f973b-ceac-4bd9-b1ba-3d8355334c18, then the final URL would be:

https://vcd/api/entity/urn:vcloud:vm:515f973b-ceac-4bd9-b1ba-3d8355334c18

As you can see from the screenshot below, an object reference is returned to us in the form of an href and in this case the vCloud Director object is a Virtual Machine.

Entity-2

You can use the Entity Resolver for all objects in vCloud Director, it is not limited to just Virtual Machines. Here is another example with looking up an object ID for Catalog.

Entity-3

Note: The Entity Resolver will return both non-admin and admin hrefs if applicable.

In general, if you need to cache vCloud Director Objects, make sure you are using the unique identifier (URN format) and not the href property. You should also ensure that as changes are made in vCloud Director that you also update your cache to ensure consistency. If you just need to quickly search for an object in vCloud Director, you should use the Query Service API which will be the most efficient method for searching and it allows for advanced property filtering.

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

This entry was posted in Automation, vCloud Director on by .
William Lam

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 “Using the Entity Resolver in the vCloud API

Comments are closed.