You can use this API to search for any of the following resources in vCenter Chargeback Manager:
The syntax for calling this API is:
POST <Base_URL>/search
A sample API call is as follows:
POST https://123.123.123.123/vCenter-CB/api/search
You must have a role with the Read privilege on the resource (hierarchy, report, or report schedule) that you want to retrieve.
Parameter |
Data Type |
Required/Optional |
Description |
Sample Value |
uuid |
String |
Optional |
Universally Unique Identifier (UUID) of the previously executed search request. The UUID is returned by the API. This can be used to get the next/paginated results. |
127524218244818350128 |
firstResultCount |
int |
Optional |
The index number starting from which the API should return the results. For example, if your search retrieves 100 results and if you want to view only 10 results starting from the 11th result, you should specify 11. |
11 |
maxResultCount |
int |
Optional |
Maximum number of results to be returned. |
100 |
The request XML for the API includes the following parameters.
XPath |
Data Type |
Min Occurs |
Max occurs |
Description |
SearchQueries/SearchQuery |
1 |
1 |
Represents the search query. |
|
SearchQueries/SearchQuery/@id |
xs:string |
1 |
1 |
Resource IDs on which you want to perform the search. The IDs that you can use to search for each resource is provided in the Search Query Filters table. |
SearchQueries/SearchQuery/Criteria |
1 |
1 |
Represents the search criteria. |
|
SearchQueries/SearchQuery/Criteria/@type |
xs:string |
1 |
1 |
Type of logical operator to be applied on given filters. The valid types are AND and OR. |
SearchQueries/SearchQuery/Criteria/Filter/@name |
xs:string |
0 |
unbounded |
Name of the filter. See the Search Query Filters table for a list of filter names that you can use with each resource. |
SearchQueries/SearchQuery/Criteria/Filter/@type |
xs:string |
0 |
unbounded |
Type of the filter. Mandatory, if the filter name is specified. EQUAL - Use this filter type to search for an exact value. Value can be a string, number or date. NOT_EQUAL - Use this filter type to search for filter value other than specified. BETWEEN - Use this filter type to search for a number in a specified range. Use the From and To values to specify the range. GT - Use this filter type to search for a number or date greater than a specified number or date. LT - Use this filter type to search for a number or date lower than a specified number or date. GT_EQUAL - Use this filter type to search for a number or date greater than or equal to a specified number or date. LT_EQUAL - Use this filter type to search for a number or date lower than or equal to a specified number or date. NULL - Use this filter type to search for an empty value. For example, you can search for hierarchies that do not have hierarchy description. NOT_NULL - Use this filter type to search for non-empty values. LIKE - Use this filter type to search filter values for the specified string. This filter type does not perform a case-sensitive search. The LIKE filter works similar to the LIKE operator of Structured Query Language (SQL). It supports the use of wild card characters such as the opening bracket ([), the percentage %, and the underscore (_). To escape these characters during a search, you can enclose them in brackets ([ ]). For example, [ _ ]. The following example filter retrieves reports, which has ‘myReport’ as a prefix in their names. <Filter name="name" type="LIKE" value="myReport%"/> NOT_LIKE - Use this filter type to search for filter values other than the specified string. |
SearchQueries/SearchQuery/Criteria/Filter/@value |
xs:string |
0 |
unbounded |
Value of the specified filter. For example, hierarchyName1. Mandatory for the filters EQUAL, NOT_EQUAL, GT, LT, GT_EQUAL, LT_EQUAL, LIKE, NOT_LIKE. |
SearchQueries/SearchQuery/Criteria/Filter/@from |
xs:string |
0 |
unbounded |
Start range of the specified filter. For example, 1275034498970. Mandatory only for the filter BETWEEN. |
SearchQueries/SearchQuery/Criteria/Filter/@to |
xs:string |
0 |
unbounded |
End range of the specified filter. For example, 1275054498970. Mandatory only for the filter BETWEEN.. |
SearchQueries/SearchQuery/SortBy |
1 |
1 |
Represents the sort details. |
|
SearchQueries/SearchQuery/SortBy/Params |
|
1 |
1 |
Represents the parameters for sorting the search results. |
SearchQueries/SearchQuery/SortBy/Params/Param |
xs:string |
0 |
unbounded |
Optional sorting parameter name. |
SearchQueries/SearchQuery/SortBy/Params/Param/@index |
xs:string |
0 |
unbounded |
Index of the sorting parameter. Index would be in the order in which the result needs to be sorted. Starts from 1. |
SearchQueries/SearchQuery/SortBy/Params/Param/@order |
xs:string |
0 |
unbounded |
Sorting order. Valid value is ASC or DESC. |
SearchQueries/SearchQuery/Pagination |
1 |
1 |
Represents how the search results are to be paginated. |
|
SearchQueries/SearchQuery/Pagination/FirstResultCount |
xs:int |
1 |
1 |
Mandatory parameter. Indicates the number from which the result is to be returned. You can specify a number between 0 and 299. |
SearchQueries/SearchQuery/Pagination/MaxResultCount |
xs:int |
1 |
1 |
Mandatory parameter. Indicates the maximum number of total results to be returned. Specify a number between 0 and 300. |
This table provides the search query IDs and filters that you can use for the resource on which you want to perform the search.
Resource |
Search Query ID |
Search Filter Name |
Hierarchy |
hierarchy |
name - Use this parameter to search on the name of the hierarchy. desc - Use this parameter to search on the description of the hierarchy. createdOn - Use this parameter to search on the time when the hierarchy was created. This value should be specified in milliseconds from January 1, 1970 GMT 00:00) . |
|
hierarchyRelation
|
createdOn - Use this parameter to search on the time when the entity is added to the hierarchy. This value should be specified in milliseconds. entityName - Use this parameter to search on the name of the hierarchy entity. For vCenter Server entities, this is the name specified in the vCenter Server. entityDisplayName - Use this parameter to search on the display name of the hierarchy entity. For vCenter server entities, this is the name explicitly specified by the user. For example, the name user specifies while provisioning virtual machines through VMware vCloud Director. This field is currently set for the virtual machines and media & template entities added to the vCloud Director hierarchies. For other entities, it is null. NOTE: The hierarchyRelation search API works only for entities that are directly added to the chargeback hierarchy. For example, if you add a host from vCenter Server hierarchy to a chargeback hierarchy, then you will be able to search for the host but not for the virtual machines created on this host. |
Report |
report |
name - Use this parameter to search on the name of the report. desc - Use this parameter to search on the description of the report. hierarchyName - Use this parameter to search on the specified hierarchy name for which the report was created. costModelName - - Use this parameter to search on the specified cost model name for which the report was created. totalCost - Use this parameter to search on the specified total cost. This parameter can be used only to search for Cost reports. |
Report Schedule |
reportSchedule |
name - Use this parameter to search on the name of the report schedule. desc - Use this parameter to search on the description of the report schedule. hierarchyName - Use this parameter to search on the specified hierarchy name for which the report schedule was created. costModelName - Use this parameter to search on the specified cost model name for which the report schedule was created. |
Click the following links for sample request XMLs:
The response XML contains two main elements:
The following table describes the SearchResults element.
XPath |
Type |
Min Occurs |
Max occurs |
Description |
SearchResults/SearchResult |
1 |
1 |
Represents the result of the search. |
|
SearchResults/SearchResult/@uuid |
xs:string |
1 |
1 |
Unique string ID for the given query. For example, 127524218244818350128. |
SearchResults/SearchResult/@firstResultCount |
xs:int |
1 |
1 |
Search result number from which results are returned. For example, 0 to 299 |
SearchResults/SearchResult/@maxResultCount |
xs:int |
1 |
1 |
Maximum number of results returned. |
SearchResults/SearchResult/@totalResultCount |
xs:int |
1 |
1 |
Actual number of results for the given query. |
Depending on the resource that you are searching, you can see one of the following sections for information on the appropriate response parameters:
Click the following links for sample response XMLs.
Search Hierarchy Relation response
Search Report Schedule response
The API displays the following error codes.
Error Code |
Description |
---|---|
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INVALID_INPUT_EMPTY_FILTER_FROM_TO |
From or to value of filter is empty. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INVALID_INPUT_EMPTY_FILTER_VALUE |
Filter value is empty. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INVALID_INPUT_EMPTY_FILTER_PROPERTY_NAME |
Filter name is empty. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INVALID_INPUT_EMPTY_FILTER_PROPERTY_TYPE |
Filter type is empty. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INVALID_INPUT_EMPTY_QUERY_CRITERIA |
Criteria name is empty. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INPUT_INVALID_DUPLICATE_SORTPARAM_NAME |
Duplicate sorting parameter |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INPUT_INVALID_FILTER_VALUE_FOR_FILTER_TYPE_LIKE |
Filter value for filter type LIKE is invalid. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INPUT_INVALID_FILTER_PROPERTY_NAME |
Filter name is invalid. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INPUT_INVALID_FILTER_TYPE |
Filter type is invalid. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INPUT_INVALID_FILTER_VALUE_TYPE |
Type of the given filter value is invalid. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INPUT_INVALID_ID |
Search query ID is invalid. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INPUT_INVALID_LOGICAL_OPERATOR |
Logical parameter is invalid. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INPUT_INVALID_PAGINATION_MAX_RESULTS |
The value specified for max results for pagination is invalid |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INPUT_INVALID_RESULT_COUNT |
The specified value of firstResultCount or maxResultCount is negative. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_INPUT_INVALID_SORTPARAM_ORDER |
Sorting order is invalid. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_SEARCH_UUID_EXPIRED |
Given UUID is not present or has expired. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_SEARCH_FAILED_CREATING_PARAM_INDEX_XPATH |
Indexing of sort parameter failed. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_SEARCH_FAILED_DAO_NOT_FOUND |
Not able to initialize classes. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_SEARCH_FAILED_READING_QUERY_DEF |
Failed reading the search configuration file. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_SEARCH_FAILED_RESULT_HANDLER_NEW_INSTANCE |
Failed to initialize configuration result class. |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_SEARCH_FAILED_TO_XML_NOT_IMPLEMENTED |
Failed getting the XML |
VCENTER_COMMON_ERR_SEARCH_FRAMEWORK_SEARCH_FAILED_EMPTY_XML_CONTAINER_NAME |
Configuration file has insufficient XML details. |