VMware vSphere SDKs and Tools 8.0

8.0 7.0 6.7 6.5

RequestSpec Data Structure in Data Service Queries

A Data Services client sends a request in the form of a
RequestSpec
 object, which contains a list of
QuerySpec
 objects.

QuerySpec Structure

The
name
 field of a
QuerySpec
 is optional. You can assign a name of your choosing, to help you identify the corresponding results. The
name
 field is also useful to troubleshoot custom data providers.
A
QuerySpec
 also contains a
ResourceSpec
 and a
ResultSpec
.

ResourceSpec

The
ResourceSpec
 specifies what properties and what objects are to be returned. It contains a list of
PropertySpec
 objects and a tree of
Constraint
 objects. The
PropertySpec
 objects select resources and their properties, while the
Constraint
 objects enable you to construct Boolean combinations of conditions to filter the set of resources from which properties are returned.

ResultSpec

The
ResultSpec
, which is optional, enables you to sort the results and to specify a chunk length and a starting index for the
ResultSet
.
The
OrderingCriteria
 is a list of
OrderingPropertySpec
. Each list entry specifies the name of a sortable property and whether to sort the values in ascending or descending order.
OrderingPropertySpec
 is a subclass of
PropertySpec
. The subclass adds a
SortType
 field.
Sorting on custom properties can degrade performance in the client.

PropertySpec

A
PropertySpec
 object is used to identify the properties to return in the
ResultSet
, or the properties used for sorting the results. In the latter usage, you can specify an optional sort order for the property by supplying an instance of
OrderingPropertySpec
, which is a subclass of
PropertySpec
. A
PropertySpec
 is required in the
ResourceSpec
, but
OrderingPropertySpec
 is optional.
A
PropertySpec
 begins with a
type
 field which contains the name of a resource type. This is typically the URI of a custom resource type, or the name of a managed object type in the case of a query that joins data across vCenter Servers. For example, to request properties of a
VirtualMachine
 managed object, you must set the
type
 field of a
PropertySpec
 object to
"VirtualMachine"
.
A
PropertySpec
 contains an array of strings identifying properties to be returned in the
ResultSet
. To identify nested properties, such as properties of nested data objects, use a period as delimiter. For example, the name of a virtual machine config file is a property of the
files
 data object, which is a property of the
config
 data object, which is a property of the
VirtualMachine
 managed object, so you identify the chosen property with the string
"config.files.vmPathName"
.
To access properties of related resources or managed objects, such as the name of the host on which a virtual machine is currently running, use a
Constraint
 object to do a join operation between the two managed object types.
The
relation
 field and the
ParameterSpec
 array contained in the
propertySpec
 object are reserved for internal use.

Constraint

Constraint
 objects enable you to specify arbitrary Boolean expressions that filter the results of your query. You can limit the results by placing conditions on property values and object identities. Your query must include a
Constraint
 object.
Constraint
 is an abstract class with four subclasses. You can supply a simple constraint of object identity or property value by using an
ObjectIdentityConstraint
 object or a
PropertyConstraint
 object. You can use a
RelationalConstraint
 object to join data across resource types.
You can use a
CompositeConstraint
 wherever a
Constraint
 object is allowed. A
CompositeConstraint
 enables you to combine a list of other constraint objects, joined by a Boolean operator. You can nest a
CompositeConstraint
 within another
CompositeConstraint
, which enables you to create arbitrarily complex Boolean expressions.
A query can contain the following types of constraints, each of which is a subclass of the base
Constraint
 class.
  • ObjectIdentityConstraint
     - Queries based on this constraint retrieve the properties of a known target object. For example, a query might retrieve the powered-on state of a given virtual machine. The object identifier can be a managed object type or any custom type that implements the
    IResourceReference
     interface. The identifier in this constraint includes the server GUID.
  • PropertyConstraint
     - Queries based on this constraint retrieve all objects with a given property value. For example, a query might retrieve all virtual machine objects with a power state of on. This constraint accepts the property name and comparator as strings, and the property value as an
    Object
    . This constraint is not bound to a specific server, and can be used to retrieve results from all vCenter Servers known to the client.
  • RelationalConstraint
     - Queries based on this constraint retrieve all objects that match the specified relationship with a given object. For example, a query might retrieve all virtual machine objects related to a given host object. The identifier in this constraint includes the server GUID.
  • CompositeConstraint
     - Composite queries allow the combination of multiple constraints using the
    and
     or
    or
     operator, passed as a string. The combined subconstraints in
    CompositeConstraint
     are contained in an array of
    Constraint
     objects.
Each constraint operates relative to a resource type that you specify in its
targetType
 field. For instance, if you want to query the names of all virtual machines running on a given host, one way is to create a
PropertyConstraint
 that specifies a
targetType
 of
"HostSystem"
 and a value for the
name
 property, then nest that
PropertyConstraint
 in the
Constraint
 field of a
RelationalConstraint
 that specifies a
targetType
 of
"VirtualMachine"
 and a
relation
 field of
"runtime.host"
.

Content feedback and comments