cis data legacy resource model: query

This method is deprecated! Use method {@link #retrieve(com.vmware.cis.data.QuerySpec)} instead. Retrieve a snapshot of the resource model data as specified in the provided query specification, i.e. QuerySpec instance.

Request:

HTTP request

POST https://{server}/rest/com/vmware/cis/data/legacy/resource-model?~action=query

Request Body Structure:

{
    "query_spec"{
        "compute_total_item_count"true,
        "limit"1,
        "offset"1,
        "property_spec"[
            "string",
            "string"
        ],
        "resource_filter"{
            "composite_filter"{
                "filters"[
                    {
                        "composite_filter"{
                            "filters"[
                                null,
                                null
                            ],
                            "operator""INTERSECT"
                        },
                        "filter_type""TYPE",
                        "property_filter"{
                            "comparable_boolean"true,
                            "comparable_double"1.5,
                            "comparable_id"{
                                "id""obj-103",
                                "type""string"
                            },
                            "comparable_long"1,
                            "comparable_string""string",
                            "comparable_type""LONG",
                            "operator""EQUAL",
                            "property""string"
                        },
                        "resource_id"{
                            "id""obj-103",
                            "type""string"
                        },
                        "resource_type""string"
                    },
                    {
                        "composite_filter"{
                            "filters"[
                                null,
                                null
                            ],
                            "operator""INTERSECT"
                        },
                        "filter_type""TYPE",
                        "property_filter"{
                            "comparable_boolean"true,
                            "comparable_double"1.5,
                            "comparable_id"{
                                "id""obj-103",
                                "type""string"
                            },
                            "comparable_long"1,
                            "comparable_string""string",
                            "comparable_type""LONG",
                            "operator""EQUAL",
                            "property""string"
                        },
                        "resource_id"{
                            "id""obj-103",
                            "type""string"
                        },
                        "resource_type""string"
                    }
                ],
                "operator""INTERSECT"
            },
            "filter_type""TYPE",
            "property_filter"{
                "comparable_boolean"true,
                "comparable_double"1.5,
                "comparable_id"{
                    "id""obj-103",
                    "type""string"
                },
                "comparable_long"1,
                "comparable_string""string",
                "comparable_type""LONG",
                "operator""EQUAL",
                "property""string"
            },
            "resource_id"{
                "id""obj-103",
                "type""string"
            },
            "resource_type""string"
        },
        "sort_criteria"[
            {
                "property""string",
                "sort_direction""ASCENDING"
            },
            {
                "property""string",
                "sort_direction""ASCENDING"
            }
        ]
    }
}
<?xml version="1.0" ?>
<ns0:Query-Input xmlns:ns0="http://vmware.com/cis/data/legacy/resource_model" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <query_spec>
    <limit>1</limit>
    <property_spec-array>
      <array-item>string</array-item>
      <array-item>string</array-item>
    </property_spec-array>
    <sort_criteria-array>
      <array-item>
        <sort_direction>ASCENDING</sort_direction>
        <property>string</property>
      </array-item>
      <array-item>
        <sort_direction>ASCENDING</sort_direction>
        <property>string</property>
      </array-item>
    </sort_criteria-array>
    <compute_total_item_count>true</compute_total_item_count>
    <resource_filter>
      <resource_id>
        <id>obj-103</id>
        <type>string</type>
      </resource_id>
      <composite_filter>
        <filters-array>
          <array-item>
            <resource_id>
              <id>obj-103</id>
              <type>string</type>
            </resource_id>
            <composite_filter>
              <filters-array>
                <array-item xsi:nil="true">
</array-item>
                <array-item xsi:nil="true">
</array-item>
              </filters-array>
              <operator>INTERSECT</operator>
            </composite_filter>
            <property_filter>
              <comparable_double>1.5</comparable_double>
              <comparable_string>string</comparable_string>
              <comparable_id>
                <id>obj-103</id>
                <type>string</type>
              </comparable_id>
              <comparable_boolean>true</comparable_boolean>
              <property>string</property>
              <comparable_type>LONG</comparable_type>
              <comparable_long>1</comparable_long>
              <operator>EQUAL</operator>
            </property_filter>
            <resource_type>string</resource_type>
            <filter_type>TYPE</filter_type>
          </array-item>
          <array-item>
            <resource_id>
              <id>obj-103</id>
              <type>string</type>
            </resource_id>
            <composite_filter>
              <filters-array>
                <array-item xsi:nil="true">
</array-item>
                <array-item xsi:nil="true">
</array-item>
              </filters-array>
              <operator>INTERSECT</operator>
            </composite_filter>
            <property_filter>
              <comparable_double>1.5</comparable_double>
              <comparable_string>string</comparable_string>
              <comparable_id>
                <id>obj-103</id>
                <type>string</type>
              </comparable_id>
              <comparable_boolean>true</comparable_boolean>
              <property>string</property>
              <comparable_type>LONG</comparable_type>
              <comparable_long>1</comparable_long>
              <operator>EQUAL</operator>
            </property_filter>
            <resource_type>string</resource_type>
            <filter_type>TYPE</filter_type>
          </array-item>
        </filters-array>
        <operator>INTERSECT</operator>
      </composite_filter>
      <property_filter>
        <comparable_double>1.5</comparable_double>
        <comparable_string>string</comparable_string>
        <comparable_id>
          <id>obj-103</id>
          <type>string</type>
        </comparable_id>
        <comparable_boolean>true</comparable_boolean>
        <property>string</property>
        <comparable_type>LONG</comparable_type>
        <comparable_long>1</comparable_long>
        <operator>EQUAL</operator>
      </property_filter>
      <resource_type>string</resource_type>
      <filter_type>TYPE</filter_type>
    </resource_filter>
    <offset>1</offset>
  </query_spec>
</ns0:Query-Input>

Request Body Parameters:

Name Type Description
bold = required
query_spec query_spec A query specification that defines the data to retrieve.
query_spec.resource_filter resource_filter Restricts (filters) the set of resources to be returned for the query. Corresponds to the WHERE clause in SQL. Provides abilities to specify comparison predicates on the properties of the resources to search for or even on properties of their related resources as well as arbitrary compositions of such predicates.

query_spec.resource_filter.filter_type string The type of the filter used.

The types of filters used to restrict the resources returned from a query. Value is one of:
TYPE: Filter by resource type.
ID: Filter by resource identifier.
PROPERTY: Filter by condition on a resource model property value.
COMPOSITE: A composition of multiple filters.

query_spec.resource_filter.resource_type string Limits the results returned for a query to resources with the specified resource type, e.g. com.acme.Person. TODO: Add reference to the documentation/API that clients can check in order to find out what types and properties they can query.

Optional. It is only relevant when filter_type has value TYPE. This field is optional and it is only relevant when the value of filter_type is TYPE.

query_spec.resource_filter.resource_id typed_ID The identifier of an individual resource that satisfies this filter criteria.

Optional. It is only relevant when filter_type has value ID. This field is optional and it is only relevant when the value of filter_type is ID.

query_spec.resource_filter.resource_id.type string The type of the resource being identified, e.g. com.acme.Person.

query_spec.resource_filter.resource_id.id string The resource's own identifier.

When clients pass a value of this structure as a parameter, the field type must contain the actual resource type. When operations return a value of this structure as a result, the field type will contain the actual resource type.

query_spec.resource_filter.property_filter property_filter Filters the resource set by evaluating conditions (predicates) on their own or related resource model properties.

For instance, it could be used to match all com.acme.Person resources which have property name starting with John or property gender equal to male.

Optional. It is only relevant when filter_type has value PROPERTY. This field is optional and it is only relevant when the value of filter_type is PROPERTY.

query_spec.resource_filter.property_filter.property string Specifies the resource model property to be compared.

Each property specification begins with the fully-qualified name of the resource model that declares the property, followed by the name of the property. The property name could be either a single property name, in case of an immediate property of the resource model or a property path, i.e. chain of property names, separated with / symbol to indicate a child property, e.g. com.acme.PersonModel/relatives/father.

In case the property filter needs to be defined on a property of a related resource, the path should be equal to the -> separated concatenation of the following:

  1. Specification of the property that holds the identifier (id) of the related resource in the target resource model.
  2. Specification of the desired property to compare in the related resource model.
For instance, if we need to search for all persons whose father's name is "Michael" the property path would be com.acme.PersonModel/relatives/father->com.acme.PersonModel/name, assuming both relatives/father and name properties are declared in com.acme.PersonModel resource model.

In case the property of a related entity of a related entity (i.e. multi-hop relationship) should be compared, another path could be added and so on. For instance: com.acme.PersonModel/relatives/father->com.acme.PersonModel/relatives/mother->com.acme.PersonModel/name.

query_spec.resource_filter.property_filter.operator string The operator to compare the property values with.

Defines the possible operators to use when comparing the values of individual resource model properties.

When comparing values of different types, one of the values can be promoted from one type to another (if needed in order to perform correct comparison) according to the following rules:

  • When comparing numeric values, a comparable of type long could be promoted (converted) to type double. The result value will be the same as the original value.
  • When comparing to a boolean value, a comparable of type string can be promoted to boolean if the value is parsable to boolean, i.e. either false or true in lower case.
Value is one of:
EQUAL: Equality operator
NOT_EQUAL: Inequality operator
GREATER: Greater than operator
GREATER_OR_EQUAL: Greater than or equal to operator
LESS: Less than operator
LESS_OR_EQUAL: Less than or equal to operator
STARTS_WITH: Operator that checks whether a string property value starts with the comparable string value.

For instance, the comparable value powered will match property whose value is poweredOn or poweredOff, but it will not match isPoweredOn.


ENDS_WITH: Operator that checks whether a string property value ends with the comparable string value.

For instance, the comparable value On will match property whose value is poweredOn, but it will not match poweredOff.


CONTAINS: Operator that checks whether a string property value contains the comparable string value anywhere in its content.

For instance, a property with value isPoweredOn will be matched by comparable values like powered, On or isPoweredOn.

query_spec.resource_filter.property_filter.comparable_type string Determines the type of the comparable property value.

The types of properties that can be used for comparison in a property filter. Value is one of:
LONG: Property value of long type.
DOUBLE: Property value of double type.
BOOLEAN: Property value of boolean type.
STRING: Property value of string type.
ID: Property value which represents a resource identifier

query_spec.resource_filter.property_filter.comparable_long long The long value to be compared against the specified property.

Optional. It is only relevant when comparable_type has value LONG. This field is optional and it is only relevant when the value of comparable_type is LONG.

query_spec.resource_filter.property_filter.comparable_double double The double value to be compared against the specified property.

Optional. It is only relevant when comparable_type has value DOUBLE. This field is optional and it is only relevant when the value of comparable_type is DOUBLE.

query_spec.resource_filter.property_filter.comparable_boolean boolean The boolean value to be compared against the specified property.

Optional. It is only relevant when comparable_type has value BOOLEAN. This field is optional and it is only relevant when the value of comparable_type is BOOLEAN.

query_spec.resource_filter.property_filter.comparable_string string The string value to be compared against the specified property.

Optional. It is only relevant when comparable_type has value STRING. This field is optional and it is only relevant when the value of comparable_type is STRING.

query_spec.resource_filter.property_filter.comparable_id typed_ID The string value to be compared against the specified property.

Optional. It is only relevant when comparable_type has value ID. This field is optional and it is only relevant when the value of comparable_type is ID.

query_spec.resource_filter.property_filter.comparable_id.type string The type of the resource being identified, e.g. com.acme.Person.

query_spec.resource_filter.property_filter.comparable_id.id string The resource's own identifier.

When clients pass a value of this structure as a parameter, the field type must contain the actual resource type. When operations return a value of this structure as a result, the field type will contain the actual resource type.

query_spec.resource_filter.composite_filter composite_filter Filters the resource set by evaluating a composition of multiple resource filters. Provides ability to build arbitrary trees of resource filter nodes and control their precedence.

Optional. It is only relevant when filter_type has value COMPOSITE. This field is optional and it is only relevant when the value of filter_type is COMPOSITE.

query_spec.resource_filter.composite_filter.operator string The operator to be used to join the resource sets identified by the constituent filters.

Defines the possible operators that can be used to combine multiple resource filters. Value is one of:
INTERSECT: Intersects the resource sets identified by the constituent filters.
UNION: Unions the resource sets identified by the constituent filters.

query_spec.resource_filter.composite_filter.filters resource_filter[] The list of resource filters that this composite is made of.

query_spec.property_spec string[] Specifies the properties of the filtered set of resources to be included in the result set for the query.

Each property specification begins with the fully-qualified name of the resource model that declares the property, followed by the name of the property. The property name could be either a single property name, in case of an immediate property of the resource model or a property path, i.e. chain of property names, separated with / symbol to indicate a child property, e.g. com.acme.PersonModel/relatives/father.

Optional. If unset, no properties will be returned but only the identifiers of the matched resources.

query_spec.sort_criteria sort_spec[] Defines how the final result set should be sorted by comparing the values of one or more properties of the items in the result set. Represents a list of one or more sorting specifications, where those with lower indices in the list takes precedence over the specs with higher indices.

Optional. If unset, no sorting will be applied.

query_spec.sort_criteria[].property string Specifies the resource model property whose value to compare when sorting the result items.

Each property specification begins with the fully-qualified name of the resource model that declares the property, followed by the name of the property. The property name could be either a single property name, in case of an immediate property of the resource model or a property path, i.e. chain of property names, separated with / symbol to indicate a child property, e.g. com.acme.PersonModel/relatives/father.

query_spec.sort_criteria[].sort_direction string Specifies the order direction to use when sorting the result items by the specified resource model property/properties. The default value is ASCENDING.

Optional. If unset, defaults to ASCENDING.

query_spec.offset long The offset into the result set. Must be non-negative number.

If the offset is N then items from N to N + limit - 1 will be returned.

Optional. If unset, defaults to 0.

query_spec.limit long The maximum number of result items to return.

Note that the service defines its own default limit that cannot be overriden here. If the specified value here is above that limit, an vapi.std.errors.invalid_argument error will be thrown for the particular query in order to indicate this violation.

Optional. If unset, a default limit will be automatically assigned.

query_spec.compute_total_item_count boolean Indicates whether the total number of resources that matched the query should be computed. This is meaningful only in cases where the number of resources that match the query could be more than the limit of result items to be returned as specified in cis.data.legacy.resource_model.query_spec.limit.

NOTE: Use this with particular caution and only when it's absolutely needed as the computation of this value could have noticeable performance overhead.

Optional. If unset, defaults to false.

Response:

HTTP Status Code: 200

Representations:

{
    "value"{
        "items"[
            {
                "property_values"[
                    {
                        "property""string",
                        "value""opaque_string_value"
                    },
                    {
                        "property""string",
                        "value""opaque_string_value"
                    }
                ],
                "resource_id"{
                    "id""obj-103",
                    "type""string"
                }
            },
            {
                "property_values"[
                    {
                        "property""string",
                        "value""opaque_string_value"
                    },
                    {
                        "property""string",
                        "value""opaque_string_value"
                    }
                ],
                "resource_id"{
                    "id""obj-103",
                    "type""string"
                }
            }
        ],
        "total_item_count"1
    }
}
<?xml version="1.0" ?>
<ns0:Query-Result xmlns:ns0="http://vmware.com/cis/data/legacy/resource_model" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <value>
    <total_item_count>1</total_item_count>
    <items-array>
      <array-item>
        <resource_id>
          <id>obj-103</id>
          <type>string</type>
        </resource_id>
        <property_values-array>
          <array-item>
            <value>opaque_string_value</value>
            <property>string</property>
          </array-item>
          <array-item>
            <value>opaque_string_value</value>
            <property>string</property>
          </array-item>
        </property_values-array>
      </array-item>
      <array-item>
        <resource_id>
          <id>obj-103</id>
          <type>string</type>
        </resource_id>
        <property_values-array>
          <array-item>
            <value>opaque_string_value</value>
            <property>string</property>
          </array-item>
          <array-item>
            <value>opaque_string_value</value>
            <property>string</property>
          </array-item>
        </property_values-array>
      </array-item>
    </items-array>
  </value>
</ns0:Query-Result>

Response Type:

Name Type Description
bold = required
value result_set The resource model data retrieved for the provided query.
value.items resource_item[] The list of result items. Each item corresponds to a particular resource that matched the conditions in the specified QuerySpec instance and containing the property data retrieved for that resource.

value.items[].resource_id typed_ID The identifier of the resource that this instance contains data for.

value.items[].resource_id.type string The type of the resource being identified, e.g. com.acme.Person.

value.items[].resource_id.id string The resource's own identifier.

When clients pass a value of this structure as a parameter, the field type must contain the actual resource type. When operations return a value of this structure as a result, the field type will contain the actual resource type.

value.items[].property_values property_value[] The retrieved values of the individual resource model properties.

value.items[].property_values[].property string Identifies the resource model property. Begins with the fully-qualified name of the resource model that declares the property, followed by the name of the property. The property name could be either a single property name, in case of an immediate property of the resource model or a property path, i.e. chain of property names, separated with / symbol to indicate a child property, e.g. com.acme.PersonModel/relatives/father.

value.items[].property_values[].value opaque A snapshot of the resource model property value.

value.total_item_count long The total number of resources that matched the given query, regardless of the actual number that is returned in cis.data.legacy.resource_model.result_set.items. This value is set only if it has been explicitly requested in the query.

Optional. Will be returned only if explicitly specified in the query.

Errors:

HTTP Status Code Type Description
400 invalid_argument If cis.data.legacy.resource_model.query_spec.limit value is above the default service limit.
401 unauthenticated If a session has not been created, has expired due to inactivity or explicit log out, or if a session the service itself has created with an underlying data provider has expired and cannot be reestablished. In all cases the client should login again and retry the query.