`entity`

Provides a list of entities and their properties for a resource type and search conditions.

This API queries and retrieves information from the aggregated tables in DiamondDB and Cassandra.

URL

https://<dashboard_route>/insight/service/dataset/metric/entity

https://<dashboard_hostname>:<dashboard_port>/insight/service/dataset/metric/entity

https://<myserver.ibm.com>:31443/insight/service/dataset/metric/entity

Method

The supported request type.

https GET

URL parameters

Name	Required	Default value	Description
`entityResourceTypes`	No	N/A	Comma-separated list of entity IDs
`all`	No	false	Comma-separated list of entity names
`properties`	No	N/A	Comma-separated list of properties to output. Note: `properties` is not applicable for NetFlow resource types.
`searchByProperties`	No	N/A	Properties filter in this format, `"<propertyName>"<ops>' <propertyValue>'` Note: Property name and value are case-sensitive. For example: `"IFTYPESTRING"='ethernet-csmacd'` Note: `searchByProperties` is not applicable for NetFlow resource types.
`scope`	true	`flow`	Scope must be set to true for ART and QoS resource types. Note: For all the performance data that is collected and analyzed from your Cacti deployment scenario, scope is set to `cacti`.
`flowEnabled`	No	false	If set to true, the result must contain the flow enabled entities.
`interfaceEnabled`	No	false	This parameter is applicable for resource type interface only. If set to true, it returns a list of interfaces for which data collection is enabled.
`parentChildRelation`	No	union	Set operation between result from parent ID search and entity ID search. For example, intersection, union.
`site`	No	ALL	Configured site name.
`bizHour`	No	ALL	Configured business hours for a site. Expected values are OFF, ON and ALL.

Sample URLs

/insight/service/dataset/metric/entity?entityResourceTypes=device
/insight/service/dataset/metric/entity?entityResourceTypes=interface&flowEnabled=true
/insight/service/dataset/metric/entity?entityResourceTypes=device&all=true
/insight/service/dataset/metric/entity?entityResourceTypes=interface&flowEnabled=true
/insight/service/dataset/metric/entity?parentNames=10.53.17.207,10.53.12.200&entityResourceTypes=interface&scope=flow&interfaceEnabled=true

Note:

At least one or more of the following parameters must be provided,
- entities
- parents
- entityNames
- parentNames
- searchByProperties
- entityResourceTypes

Supported operators for properties filter are as follows,

For example,

searchByProperties="sysName"='"10.55.239.40"' AND "If"='897'
searchByProperties="sysName"='"10.55.239.40"' AND "If" IN ('897','898')
searchByProperties="sysName" like '"10.55.239.%25"' AND "If"='897'

Note: % is reserved keyword. It must be encoded with %25.

Error response

For example,

{"errorMesg":"Either entities, parents, entityNames, parentNames, entityResourceTypes, or serachByProperties should be provided"}

Response

The results are returned as JSON data that contains an array of the following fields:

Name	Data type	Description
`entityId`	number	An entity ID
`entityName`	string	Name of the entity
`parentId`	number	Parent entity ID
`parentName`	string	Parent entity name
`properties`	map	Map of properties that are given in input parameters their values.
`inIfId`	number	Inbound interface IDs for the entities if they are enriched.
`outIfId`	number	Outbound interface IDs for the entities if they are enriched.

JSON code without flowEnabled flag set is as follows:

[
   {
      "entityId":-1,
      "entityName":"ALL",
      "parentId":-1,
      "parentName":"ALL"
   },
   {
      "entityId":5,
      "entityName":"10.55.239.202",
      "parentId":5,
      "parentName":"10.55.239.202"
   },
   {
      "entityId":1,
      "entityName":"10.55.239.201",
      "parentId":1,
      "parentName":"10.55.239.201"
   },
   {
      "entityId":6,
      "entityName":"10.55.239.4",
      "parentId":6,
      "parentName":"10.55.239.4"
   },
   {
      "entityId":9,
      "entityName":"10.55.239.221",
      "parentId":9,
      "parentName":"10.55.239.221"
   },
   {
      "entityId":7,
      "entityName":"10.55.239.249",
      "parentId":7,
      "parentName":"10.55.239.249"
   },
   {
      "entityId":3,
      "entityName":"10.55.239.3",
      "parentId":3,
      "parentName":"10.55.239.3"
   },
   {
      "entityId":8,
      "entityName":"10.55.239.250",
      "parentId":8,
      "parentName":"10.55.239.250"
   },
   {
      "entityId":4,
      "entityName":"10.55.239.203",
      "parentId":4,
      "parentName":"10.55.239.203"
   }
]

JSON code with flowEnabled flag set is as follows:

[
   {
      "entityId":995,
      "inIfId":8589936607,
      "entityName":"Se1/0:0",
      "parentName":"10.55.239.250",
      "outIfId":8589936606,
      "parentId":960
   }
]