Typed queries require you to construct a request URL that specifies an object type and optional parameters. Use this URL with a GET request to return query results.
Query Syntax
Typed queries have the following syntax:
API-URL/query?type=name[¶m][¶m ... ][&filter]
- API-URL is a URL of the form https://vcloud.example.com/api.
- name is the name of a query type. Type names are case-sensitive.
- param is an optional query parameter. Zero or more parameters are allowed. See Query Parameters.
- filter is an optional filter expression. At most one filter expression is allowed. See Filter Expressions.
Query Types
Each query type returns its result set as an XML document in which objects are represented as elements and object properties are represented as attributes, pairing the name of the property with its value at the time the request was made. By default, result sets are returned in the records format, which shows all database records for each object. Most queries also support the references format, which returns a set of object references, including name, type, and href attributes. All queries that support the records format also support the idrecords format. For more information about the format parameter, see Query Parameters.
Query Reference
The VMware Cloud Director API schema reference includes reference material for all queries. The schema reference is available at https://code.vmware.com.
Listing All Queries
You can retrieve a summary list of all typed queries types accessible to the currently authenticated user by making a request like this one:
GET https://vcloud.example.com/api/query
The response is a QueryList element that contains a Link for every query. The href value of each Link is a URL you can GET to run the query specifying the default format.
<?xml version="1.0" encoding="UTF-8"?>
<QueryList
type="application/vnd.vmware.vcloud.query.queryList+xml"
href="https://vcloud.example.com/api/query"
... >
<Link
rel="down"
type="application/vnd.vmware.vcloud.query.references+xml"
name="organization"
href="https://vcloud.example.com/api/query?type=organization&format=references" />
<Link
rel="down"
type="application/vnd.vmware.vcloud.query.records+xml"
name="organization"
href="https://vcloud.example.com/api/query?type=organization&format=records" />
<Link
rel="down"
type="application/vnd.vmware.vcloud.query.idrecords+xml"
name="organization"
href="https://vcloud.example.com/api/query?type=organization&format=idrecords" />
<Link
rel="down"
type="application/vnd.vmware.vcloud.query.references+xml"
name="adminOrgNetwork"
href="https://vcloud.example.com/api/query?type=adminOrgNetwork&format=references" />
...
</QueryList>
If you make a query whose result set you do not have rights to view, a response code of ACCESS_TO_RESOURCE_IS_FORBIDDEN (403) is returned.
Simple Typed Query
This simple typed query retrieves a list of all users in your organization and returns a response in the default (records) format.
GET https://vcloud.example.com/api/query?type=user
Response:
<QueryResultRecords
xmlns="http://www.vmware.com/vcloud/v1.5"
total="3"
pageSize="25"
page="1"
name="user"
type="application/vnd.vmware.vcloud.query.records+xml"
href="https://vcloud.example.com/api/query?type=user&page=1&pageSize=25&format=records"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 http://vcloud.example.com/api/v1.5/schema/master.xsd">
<Link
rel="alternate"
type="application/vnd.vmware.vcloud.query.references+xml"
href="https://vcloud.example.com/api/query?type=user&page=1&pageSize=25&format=references"/>
<UserRecord
deployedVMQuota="0"
fullName="User One"
identityProviderType="INTEGRATED"
isEnabled="true"
isLdapUser="false"
name="bob"
numberOfDeployedVMs="0"
numberOfStoredVMs="0"
storedVMQuota="0"
href="https://vcloud.example.com/api/admin/user/39"
storedVMQuotaRank="-1"
deployedVMQuotaRank="-1"/>
<UserRecord
deployedVMQuota="0"
fullName="User Two"
identityProviderType="INTEGRATED"
isEnabled="true"
isLdapUser="false"
name="zorro"
numberOfDeployedVMs="0"
numberOfStoredVMs="0"
storedVMQuota="0"
href="https://vcloud.example.com/api/admin/user/24"
storedVMQuotaRank="-1"
deployedVMQuotaRank="-1"/>
<UserRecord
deployedVMQuota="0"
fullName="Example User"
identityProviderType="INTEGRATED"
isEnabled="true"
isLdapUser="false"
name="nobody"
numberOfDeployedVMs="0"
numberOfStoredVMs="0"
storedVMQuota="0"
href="https://vcloud.example.com/api/admin/user/58"
storedVMQuotaRank="-1"
deployedVMQuotaRank="-1"/>
</QueryResultRecords>
This simple typed query retrieves the same list of all users in your organization and returns a response in the references format.
GET https://vcloud.example.com/api/query?type=user&format=references
Response:
<UserReferences
xmlns="http://www.vmware.com/vcloud/v1.5"
total="3"
pageSize="25"
page="1"
name="user"
type="application/vnd.vmware.vcloud.query.references+xml"
href="https://vcloud.example.com/api/query?type=user&page=1&pageSize=25&format=references"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ...
<Link
rel="alternate"
type="application/vnd.vmware.vcloud.query.records+xml"
href="https://vcloud.example.com/api/query?type=user&page=1&pageSize=25&format=records" />
<UserReference
type="application/vnd.vmware.admin.user+xml"
name="bob"
href="https://vcloud.example.com/api/admin/user/39" />
<UserReference
type="application/vnd.vmware.admin.user+xml"
name="zorro"
href="https://vcloud.example.com/api/admin/user/24" />
<UserReference
type="application/vnd.vmware.admin.user+xml"
name="nobody"
href="https://vcloud.example.com/api/admin/user/58" />
</UserReferences>
Query With Parameters
This query retrieves a list of all users in your organization and returns a response in the records format. The query includes a
sortAsc=name parameter, so the result set is sorted by object name.
GET https://vcloud.example.com/api/query?type=user&format=references&sortAsc=name
Response:
<UserReferences
xmlns="http://www.vmware.com/vcloud/v1.5"
total="3"
pageSize="25"
page="1"
name="user"
type="application/vnd.vmware.vcloud.query.references+xml"
href="https://vcloud.example.com/api/query?type=user&page=1&pageSize=25&format=references"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
<Link
rel="alternate"
type="application/vnd.vmware.vcloud.query.records+xml"
href="https://vcloud.example.com/api/query?type=user&page=1&pageSize=25&format=records" />
<UserReference
type="application/vnd.vmware.admin.user+xml"
name="bob"
href="https://vcloud.example.com/api/admin/user/39" />
<UserReference
type="application/vnd.vmware.admin.user+xml"
name="nobody"
href="https://vcloud.example.com/api/admin/user/58" />
<UserReference
type="application/vnd.vmware.admin.user+xml"
name="zorro"
href="https://vcloud.example.com/api/admin/user/24" />
</UserReferences>
This query retrieves a list of all users in your organization and returns a response in the records format. The query includes a
filter=ldapUser==true parameter, so the result set lists the subset of users who are imported from LDAP. Note that you can filter on a record (attribute) value even though you specify the references format.
GET https://vcloud.example.com/api/query?type=adminUser&format=references&filter=ldapUser==true
Response:
<?xml version="1.0" encoding="UTF-8"?>
<UserReferences
xmlns="http://www.vmware.com/vcloud/v1.5"
total="2"
pageSize="25"
page="1"
name="user"
type="application/vnd.vmware.vcloud.query.references+xml"
href="https://vcloud.example.com/api/query?type=adminUser&page=1&pageSize=25&format=references&filter=ldapUser==true"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
<Link
rel="alternate"
type="application/vnd.vmware.vcloud.query.records+xml"
href="https://vcloud.example.com/api/querytype=adminUser&page=1&pageSize=25&format=records&filter=ldapUser==true" />
<UserReference
type="application/vnd.vmware.admin.user+xml"
name="bob"
href="https://vcloud.example.com/api/admin/user/39" />
<UserReference
type="application/vnd.vmware.admin.user+xml"
name="zorro"
href="https://vcloud.example.com/api/admin/user/58" />
</UserReferences>
