Search

You can use this API to search for any of the following resources in vCenter Chargeback Manager:

Syntax

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

User Privileges

You must have a role with the Read privilege on the resource (hierarchy, report, or report schedule) that you want to retrieve.

URL Parameters

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

Request Body Parameters

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.

Search Query Filters

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.

Request XML

Click the following links for sample request XMLs:

API Response

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:

Response XML

Click the following links for sample response XMLs.

Search Hierarchy response

Search Hierarchy Relation response

Search Report response

Search Report Schedule response

Error 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.