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.

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>