By adding query options to an API request, you control the amount of output returned by the server and make the response easier to interpret. The API service uses the options specified to transform the data by filtering or paginating before returning the results.
You can use the following query options in your API requests. The options do not apply to all endpoints.
$top |
Number of records to get. For more information, see Using Pagination and Count. |
$skip |
Number of records to skip. For more information, see Using Pagination and Count. |
$count |
If set to true, shows the total number of records. If used with a filter, shows the number of records matching the filter. For more information, see Using Pagination and Count. |
$select |
Names the subset of properties to list in the response. |
$filter |
Filters results by a predicate expression with operators such as, eq, ne, and, and or. For specialized filtering examples, see: |
Endpoints that support all query options
To query for any of the following endpoints, you can use all options. Examples show how to construct a request using the $filter option with a logical or operation.
Note:
Automation APIs do not support filtering for nested properties with a "." in the property name.
For example, you can filter for a property with the name
createdByEmail as in the following example:
$filter=customProperties.createdByEmail%20eq%20'[email protected]'However, API filtering does not support a property with the name my.createdByEmail as in the following example:
$filter=customProperties.my.createdByEmail%20eq%20'[email protected]'
| Endpoint | Example |
|---|---|
| Machine | $url/iaas/api/machines?$filter=name%20ne%20'example-name'%20or%20customProperties.osType%20eq%20'example-os' |
| Cloud Account | $url/iaas/api/cloud-accounts?$filter=name%20ne%20'example-cloud-account'%20or%20customProperties.isExternal%20eq%20'false' |
| Fabric Azure Storage Account | $url/iaas/api/fabric-azure-storage-accounts/?$filter=name%20ne%20'example-name'%20or%20type%20eq%20'example-type |
| Fabric Compute | $url/iaas/api/fabric-computes?$filter=name%20ne%20'example-name'%20or%20customProperties.isExternal%20eq%20'false' |
| Fabric Image | $url/iaas/api/fabric-images?$filter=name%20ne%20'example-name'%20or%20osFamily%20eq%20'example-os' |
| Fabric Network | $url/iaas/api/fabric-networks?$filter=name%20ne%20'example-name'%20or%20externalId%20eq%20'example-id' |
| Fabric Network (vSphere) | $url/iaas/api/fabric-networks-vsphere?$filter=name%20ne%20'example-name'%20or%20externalId%20eq%20'example-id' |
| Fabric vSphere Datastores | $url/iaas/api/fabric-vsphere-datastores?$filter=name%20ne%20'example-name'%20or%20externalId%20eq%20'example-id' |
| Fabric vSphere Storage Policies | $url/iaas/api/fabric-vsphere-storage-policies?$filter=name%20ne%20'example-name'%20or%20externalId%20eq%20'example-id' |
Querying for endpoints with a specified ID
To query for an endpoint with specified ID, you can only use the $select option. Examples show how to construct a request.
| Endpoint | Example |
|---|---|
| Cloud Account by ID | $url/iaas/api/cloud-account/{id}?$select=name |
| Machine by ID | $url/iaas/api/machines/{id}?$select=name |
| Fabric Azure Storage Account by ID | $url/iaas/api/fabric-azure-storage-accounts/{id}?$select=name |
| Fabric Image by ID | $url/iaas/api/fabric-images/{id}?$select=name |
| Fabric Network by ID | $url/iaas/api/fabric-networks/{id}?$select=name |
| Fabric Network (vSphere) by ID | $url/iaas/api/fabric-networks-vsphere/{id}?$select=name |
| Fabric vSphere Datastores by ID | $url/iaas/api/fabric-vsphere-datastores/{id}?$select=name |
| Fabric vSphere Storage Policies by ID | $url/iaas/api/fabric-vsphere-storage-policies/{id}?$select=name |
Querying for a partial match
To query for the partial match of a name that starts with, ends with, or is contained within another name, the
$filter options are the same for most IaaS endpoints but are different for
iaas/api/projects and
iaas/api/deployments endpoints. Examples show how to construct the partial match filters for the different endpoint types.
| Filter Operation | Query with iaas/api/projects or iaas/api/deployments |
Query with most IaaS endpoints |
|---|---|---|
| Name starts with foo | ?$filterstartswith(name, 'foo') |
$filter=name%20eq%20'foo*' |
| Name ends with foo | ?$filter=endswith(name, 'foo') |
$filter=name%20eq%20'*foo' |
| foo contained within the name | ?$filter=substringof('foo', name) |
$filter=name%20eq%20'*foo*' |
Querying for deployments
To query for deployments, you can use all options except
$select. The following example shows how to use the
$filter option to list deployments that are not named
example-name or have
projectId='example-id'.
GET $url/iaas/api/deployments?$filter=name%20ne%20'example-name'%20or%20projectId%20eq%20'example-id'
