To obtain a resource representation of a specific virtual infrastructure object, the client can must construct a query string to the lookup service. The query string can be constructed in two ways:
- Using the object reference. With this type of query, you can get a resource representation of an object via its object reference.
- Using query parameters. With this type of query, you can get a list of references to objects that match the specified criteria.
Query String with Object Reference
If you have a reference to the virtual infrastructure object and want to get its resource representation, you can construct a query string of the following type:
http://localhost:9399/api/lookup?hierarchyRef={hierarchyRef} |
where &hierarchyRef={hierarchyRef} identifies a hierarchy object reference. The hierarchy object reference is a string that is constructed by specific rules. This parameter explicitly refers to the necessary virtual infrastructure object and lets retrieve its resource representation.
The example below returns a resource representation of the VM having the following object reference: urn:vCloud:Vm:fa099d3b-7376-49b1-884c-bb6fa47c7b1e.urn:vcloud:vm:6b2da27f-e653-495b-b515-2b18bbb4d3ec.
Request: GET http://localhost:9399/api/lookup?hierarchyRef=urn:vCloud:Vm:fa099d3b-7376-49b1-884c-bb6fa47c7b1e.urn:vcloud:vm:6b2da27f-e653-495b-b515-2b18bbb4d3ec
Response: 200 Success
Response Body: <HierarchyItems xmlns="http://www.veeam.com/ent/v1.0"> |
If you want to get object references for one or several virtual infrastructure objects that match a specific criterion, you can construct a query string of the following type:
http://localhost:9399/api/lookup?host={hostUID}&name=(objectName)&type=(objectType) |
where:
- ?host={hostUID} identifies a VMware vSphere or Microsoft Hyper-V host to which the virtual infrastructure object belongs, for example: 3afa099d3b-7376-49b1-884c-bb6fa47c7b1e
- name identifies a name of the object in the virtual infrastructure hierarchy, for example: DC-VM
- type identifies the object type, for example: VM
The client can use the following object types in the query string:
For the VMware virtual environments:
- VM
- Host
- Cluster
- Template
- VirtualApp
- Vc
- Datacenter
- Folder
- Datastore
- ComputeResource
- ResourcePool
- Tag
- Category
- StoragePod
For vCloud Director:
- VcdSystem
- Organization
- OrgVdc
- Vapp
- Vm
- VappTemplate
- VmTemplate
For the Hyper-V virtual environments:
- Vm
- Host
- Cluster
- Scvmm
- HostGroup
The example below returns a VM named DC that resides on the host having the following ID: fa099d3b-7376-49b1-884c-bb6fa47c7b1e.
Request: GET http://localhost:9399/api/lookup?host=urn:veeam:HierarchyRoot:fa099d3b-7376-49b1-884c-bb6fa47c7b1e&name=DC&type=Vm
Response: 200 Success
Response Body: <HierarchyItems xmlns="http://www.veeam.com/ent/v1.0"> |
