Packaged Queries

Packaged queries have well-known URLs and can accept most of the parameters used with typed queries.

Query Syntax

Packaged queries have the following syntax: 
API-URL/query-url[?param][&param ... ][&filter]
  • API-URL is a URL of the form https://vcloud.example.com/api.
  • query-url is the packaged query URL.
  • 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.

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.

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 Categories

Packaged queries are divided into the following categories:

User queries
The queries have the form API-URL/object-type/query. Any user can run these queries.
Administrator queries
The queries have the form API-URL/admin/object-type/query. An organization administrator can run these queries.
Extension queries
The queries have the form API-URL/admin/extension/object-type/query. A system administrator can run these queries.
Table 1. Packaged Queries
Query URL Result Set
API-URL/catalogs/query All catalogs in your organization that you have rights to view or modify
API-URL/mediaList/query All media that you can view or modify
API-URL/vAppTemplates/query All vApp templates that you can view or modify
API-URL/vApps/query All vApps that you can view or modify
API-URL/vms/query All virtual machines that you can view or modify
API-URL/admin/groups/query Groups in all organizations in the system
API-URL/admin/users/query Users in all organizations in the system
API-URL/admin/strandedUsers/query Stranded users in the organization. When you delete an LDAP group, users who were imported from that group become stranded and cannot log in.
API-URL/admin/roles/query All roles defined in the system
API-URL/admin/rights/query All rights defined in the system
API-URL/admin/orgs/query All organizations visible to you
API-URL/admin/vdcs/query All VDCs in the system
API-URL/admin/extension/hostReferences/query All hosts registered to the system
API-URL/admin/extension/datastores/query All datastores in the system
API-URL/admin/extension/externalNetworkReferences/query External networks in the system
API-URL/admin/extension/networkPoolReferences/query All network pools in the system
API-URL/admin/extension/providerVdcReferences/query All provider VDCs in the system
API-URL/admin/extension/vimServerReferences/query All vCenter servers registered to the system
API-URL/admin/extension/orgNetworks/query All organization networks in the system
API-URL/admin/extension/vapps/query All vApps in the system
API-URL/admin/extension/orgVdcs/query All VDCs in the system

Examples

Simple packaged query using the records format, which is the default. 
GET https://vcloud.example.com/api/catalogs/query
Response: 
<QueryResultRecords
   xmlns="http://www.vmware.com/vcloud/v1.5"
   total="15"
   pageSize="25"
   page="1"
   name="catalog"
   type="application/vnd.vmware.vcloud.query.records+xml"
   href="https://vcloud.example.com/api/catalogs/query?page=1&amp;pageSize=25&amp;format=records"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
   <Link
      rel="alternate"
      type="application/vnd.vmware.vcloud.query.references+xml"
      href="https://vcloud.example.com/api/catalogs/query?type=catalog&amp;page=1&amp;pageSize=25&amp;format=references" />
   <CatalogRecord
      ownerName="system"
      organizationName="VMware"
      numberOfTemplates="30"
      numberOfMedia="3"
      name="VAM"
      isShared="true"
      isPublished="true"
      description=""
      createdOn="2011-03-21T14:28:09.273-07:00"
      href="https://vcloud.example.com/api/catalog/150" />
   <CatalogRecord
      ownerName="system"
      organizationName="QA"
      numberOfTemplates="0"
      numberOfMedia="1"
      name="QA-Cat"
      isShared="false"
      isPublished="true"
      description=""
      createdOn="2011-03-24T16:37:11.130-07:00"
      href="https://vcloud.example.com/api/catalog/78" />
   <CatalogRecord
      ownerName="system"
      organizationName="Org-d5443f6b-85e"
      numberOfTemplates="0"
      numberOfMedia="1"
      name="Catalog-3f79780c-6b0"
      isShared="true"
      isPublished="true"
      description=""
      createdOn="2011-03-25T11:27:56.063-07:00"
      href="https://vcloud.example.com/api/catalog/99" />
   <CatalogRecord
      ownerName="system"
      organizationName="Engineering"
      numberOfTemplates="2"
      numberOfMedia="4"
      name="TestCat"
      isShared="true"
      isPublished="true"
      description="New Catalog"
      createdOn="2011-03-22T17:10:10.067-07:00"
      href="https://vcloud.example.com/api/catalog/43" />
   <CatalogRecord
      ownerName="system"
      organizationName="Engineering"
      numberOfTemplates="8"
      numberOfMedia="1"
      name="catalog1"
      isShared="true"
      isPublished="true"
      description=""
      createdOn="2011-03-22T16:14:06.360-07:00"
      href="https://vcloud.example.com/api/catalog/91" />
</QueryResultRecords>
Packaged query using references format. 
GET https://vcloud.example.com/api/catalogs/query?format=references
Response: 
<CatalogReferences
   xmlns="http://www.vmware.com/vcloud/v1.5"
   total="15"
   pageSize="25"
   page="1"
   name="catalog"
   type="application/vnd.vmware.vcloud.query.references+xml"
   href="https://vcloud.example.com/api/catalogs/query?page=1&amp;pageSize=25&amp;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/catalogs/query?type=catalog&amp;page=1&amp;pageSize=25&amp;format=records" />
    <CatalogReference
      type="application/vnd.vmware.vcloud.catalog+xml"
      name="VAM"
      href="https://vcloud.example.com/api/catalog/150" />
   <CatalogReference
      type="application/vnd.vmware.vcloud.catalog+xml"
      name="QA-Cat"
      href="https://vcloud.example.com/api/catalog/78" />
   <CatalogReference
      type="application/vnd.vmware.vcloud.catalog+xml"
      name="Catalog-3f79780c-6b0"
      href="https://vcloud.example.com/api/catalog/99" />
   <CatalogReference
      type="application/vnd.vmware.vcloud.catalog+xml"
      name="TestCat"
      href="https://vcloud.example.com/api/catalog/43" />
   <CatalogReference
      type="application/vnd.vmware.vcloud.catalog+xml"
      name="catalog1"
      href="https://vcloud.example.com/api/catalog/91" />
</CatalogReferences>
Packaged query with sorting and filtering. This query adds parameters and a filter expression to produce a list of catalogs that contain one or more vApp templates. The query sorts the result set in ascending order by number of vApp templates: 
GET https://vcloud.example.com/api/catalogs/query?format=records&sortAsc=numberOfTemplates&filter=numberOfTemplates!=0
Response: 
<QueryResultRecords
   xmlns="http://www.vmware.com/vcloud/v1.5"
   total="3"
   pageSize="25"
   page="1"
   name="catalog"
   type="application/vnd.vmware.vcloud.query.records+xml"
   href="https://vcloud.example.com/api/catalogs/query?page=1&amp;pageSize=25&amp;format=records&amp;filter=numberOfTemplates!=0&amp;sortAsc=numberOfTemplates"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
   <Link
      rel="alternate"
      type="application/vnd.vmware.vcloud.query.references+xml"
      href="https://vcloud.example.com/api/catalogs/query?type=catalog&amp;page=1&amp;pageSize=25&amp;format=references&amp;filter=numberOfTemplates!=0&amp;sortAsc=numberOfTemplates" />
   <CatalogRecord
      ownerName="system"
      organizationName="Engineering"
      numberOfTemplates="2"
      numberOfMedia="4"
      name="TestCatalog"
      isShared="true"
      isPublished="true"
      description="New Catalog"
      createdOn="2011-03-22T17:10:10.067-07:00"
      href="https://vcloud.example.com/api/catalog/43" />
   <CatalogRecord
      ownerName="system"
      organizationName="Engineering"
      numberOfTemplates="8"
      numberOfMedia="1"
      name="catalog1"
      isShared="true"
      isPublished="true"
      description=""
      createdOn="2011-03-22T16:14:06.360-07:00"
      href="https://vcloud.example.com/api/catalog/91" />
   <CatalogRecord
      ownerName="system"
      organizationName="VMware"
      numberOfTemplates="30"
      numberOfMedia="3"
      name="VAM"
      isShared="true"
      isPublished="true"
      description=""
      createdOn="2011-03-21T14:28:09.273-07:00"
      href="https://vcloud.example.com/api/catalog/150" />
</QueryResultRecords>