RequestSpec Data
Structure in Data Service Queries
A Data Services
client sends a request in the form of a
object, which contains a list
of
RequestSpec
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 theIResourceReferenceinterface. 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 anObject. 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 theandororoperator, passed as a string. The combined subconstraints inCompositeConstraintare contained in an array ofConstraintobjects.
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"
.