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

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 Account Administrator, Virtual Infrastructure Administrator, Network Administrator, or Read Only Administrator can run these queries.

Table 2. 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 your organization
`API-URL`/admin/users/query	Users in your organization
`API-URL`/admin/orgs/query	Your organization
`API-URL`/admin/vdcs/query	All VDCs in your organization

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>