Performing Search

Search Request

Format of the Search Request body:

{
  "entity_type": "string",
  "filter": "string",
  "sort_by": {
    "field": "string",
    "order": "ASC"
  },
  "size": 0,
  "cursor": "string",
  "time_range": {
    "start_time": 0,
    "end_time": 0
  }
}

Entity Type

In the Entity Type field, use the entity types defined in AllEntityType enum in the API Reference.

Filter Expression

A filter expression defines search criteria in one of the following formats:

{field_name} {binary operator} {field_value}

{field_name} {unary_operator}

Optionally, complex expressions can be designed using {logical operators} and parenthesis (...).

{field_name}: The name of a field in an Object. For example, VirtualMachine has a field named
vendor_id
.
{binary operator}: Used to compare a field to a value creating an expression.
{unary_operator}: Unary operator is used to test the field_name against the operator check. For example, IS SET is used to determine if a field is non NULL.

{field_value}: Represents the value of a field and can either be a number, string , list of numbers or list of strings.
{logical operator}: Logical operators are used to create complex filters.; For example:; (name = 'my_vm') OR (vendor_id = 'vm-101')

parentheses (...): Parentheses are used to group expressions. They also determine the order in which the components of the expression are evaluated. For example:; ((name = 'my_vm') AND (default_gateway = '10.1.1.1'))

Considerations

You can use spaces in filter expressions.

Use quotes with strings. You need not use quotes with numbers.

Building Filter Expression

Components of a filter expression are: FIELD_NAMEOPERATORVALUE

FIELD_NAME

Field name can be a property defined in the model object as per the API Reference or it can be a property of a related object in the response. For example, a subset of the VirtualMachine object properties appears as follows:

{
  "entity_id": "18230:1:1158969162",
  "name": "NSX_Controller_9e80ec74-57ce-4671-8fd7-b5884a997535",
  "entity_type": "VirtualMachine",
  "ip_addresses": [
    {
      "ip_address": "10.197.17.74",
      "netmask": "255.255.255.0",
      "network_address": "10.197.17.0/24"
    }
  ],
  "default_gateway": "10.197.17.1",
  "cluster": {
    "entity_id": "18230:66:1293137396",
    "entity_type": "Cluster"
  },
  "host": {
    "entity_id": "18230:4:652218965",
    "entity_type": "Host"
  }
}

From the preceding model, you can use the following field names:

Direct primitive properties

name

default_gateway

Properties inside the structure.

For example:

ip_addresses.ip_address.

host.entity_id

Properties of a related object.

For example:

host.name

cluster.name

Aggregation Search API

Aggregation Search Request

Format of the aggregation search request body :

{
   "entity_type":"{ENTITY_TYPE}",
   "filter": "{FILTER}”,
   "aggregations": [
      {
         "field": "{FIELD}",
         "aggregation_type": "{AGGREGATION_TYPE}"
      }
    ],
   "time_range": {
     "start_time": {START_TIME_IN_SECONDS},
     "end_time": {END_TIME_IN_SECONDS}
   }
}

Aggregation search request contains following fields:

entity_type : Use the entity types defined in AllEntityType enum in the API Reference.

filter : Format of the filter expression is defined above.

aggregations: It contains array of elements. Each element consists of a field and aggregation type. Field should be a valid property of the entity. And aggregation type can be one of the following.

· SUM

· MAX

· MIN

· AVG

time_range: Time range consists of start_time and end_time. Both should be POSIX epochs (The number of seconds elapsed since Jan 1st 1970).

· start_time

· end_time

Finding total number of CPU cores and overall total memory of all the Virtual Machines

{
    "entity_type":"VirtualMachine",
    "aggregations": [
     {
      "field": "cpu_count",
      "aggregation_type": "SUM"
     },
    {
      "field": "memory",
      "aggregation_type": "SUM"
    }
  ]
}

Finding total memory of the Virtual Machines containing 'app' in their name

{
      "entity_type": "VirtualMachine",
      "filter": "name like 'app'",
      "aggregations": [
       {
         "field": "cpu_count",
         "aggregation_type": "SUM"
       },
       {
         "field": "memory",
         "aggregation_type": "SUM"
       }
    ]
}

Find sum of bytes of all flows from 10th Nov 2018 to 20th Nov 2018

{
"entity_type": "Flow",
"aggregations": [
{
"field": "flow.totalBytes.delta.summation.bytes",
"aggregation_type": "SUM"
}
],
"time_range": {
"start_time": 1541808000,
"end_time": 1542672000
}
}

Find sum of bytes of all flows from 1.1.1.1 to 2.2.2.2 from 10th Nov 2018 to 20th Nov 2018.

{
    "entity_type": "Flow",
    "filter": "source_ip.ip_address = '1.1.1.1' and    destination_ip.ip_address = '2.2.2.2'",
    "aggregations": [
   {
    "field": "flow.totalBytes.delta.summation.bytes",
    "aggregation_type": "SUM"
    }
   ],
    "time_range": {
    "start_time": 1541808000,
    "end_time": 1542672000
   }
}

Find max, min and sum memory of virtual machines

{
      "entity_type": "VirtualMachine",
      "aggregations": [
     {
      "field": "cpu_count",
      "aggregation_type": "MAX"
     },
    {
      "field": "cpu_count",
      "aggregation_type": "SUM"
     }
  ]
}

Group By

URL: /api/ni/search/groupby

{
    "entity_type": "{ENTITY_TYPE}",
    "filter": "{FILTER}”,
    "aggregations": [
       {
            "field": "{FIELD}",
            "aggregation_type": "{AGGREGATION_TYPE}"
        }
    ],
    “group_by”: [String],
    “sort_by”: [
        {
            "field": "{FIELD}",
            "aggregation_type": "{AGGREGATION_TYPE}",
            “order”: {ASC}
        }
    ],
    "time_range": {
      "start_time": {START_TIME_IN_SECONDS},
      "end_time": {END_TIME_IN_SECONDS},
    },
      “size”: 0,
      “cursor”: string
 }

Group By Request contains following fields:

entity_type: Use the entity types defined in AllEntityType enum in the API Reference.

filter: Format of the filter is same as above.

aggregations: It contains array of elements. Each element consists of a field and aggregation type. Field should be a valid property of the entity and aggregation type can be one of the following.

. SUM
. MAX
. MIN
. AVG

group_by: It contains array of elements. Each element is field which is valid property of entity.

sort_by: It contains array of elements. Each element consists of field, aggregation type and optional order (ASC / DESC).

time_range: Time range consist of start_time and end_time. Both should be POSIX epohcs (The number of seconds elaspsed since JAN 1st 1970).

. start_time
. end_time

Examples:

Find avg of CPU cores group by sum of CPU cores in ascending order

{
    "entity_type": "VirtualMachine",
     "aggregations": [{
          "field": "cpu_count",
          "aggregation_type": "AVG"
      }],
      "group_by": ["cpu_count"],
      "sort_by": [{
          "field": "cpu_count",
          "aggregation_type": "SUM",
          "order": "ASC"
      }],
    "time_range": {
      "start_time": 1570612016,
      "end_time": 1570612016  
    }
  }

Find sum of bytes of all flows from 1.1.1.1 to 2.2.2.2 from 10th Nov 2018 to 20th Nov 2018 group by source ip and destination ip order by maximum of flow in ascending order

{
    "entity_type": "Flow",
    "filter": "source_ip.ip_address = '1.1.1.1' and destination_ip.ip_address = '2.2.2.2'",
    "aggregations": [
      {
        "field": "flow.totalBytes.delta.summation.bytes",
        "aggregation_type": "SUM"
      }
    ],
    "sort_by": [{
            "field": "flow.totalBytes.delta.summation.bytes",
            "aggregation_type": "MAX",
            "order": "ASC"
    }],
    "group_by": ["destination_ip", "source_ip"],
    "time_range": {
      "start_time": 1541808000 ,
      "end_time": 1542672000  
    }
  }

Operators
Operator	Description
=	Equals
!=	Not Equals
>	Greater Than
<	Less Than
>=	Greater Than OR Equals
<=	Less Than OR Equals
LIKE	Value contains the the field value
IN	Value matches one of the field values in list
NOT IN	Value does not match any field value in list
SET	Value is not null
NOT SET	Value is null

FIELD_VALUE

The search value can be a string, integer, list of strings or list of integers.

For example:

String: 'securitygroup-10'

Integer : 211

Examples of Search

Sample Search Requests

Find VMs with a specific ip_address, such as 192.168.10.1:

	Request 
		POST https://operations-for-networks.example.com/api/ni/search
	Request Body
		{
  			"entity_type": "VirtualMachine",
  			"filter": "ip_addresses.ip_address = '192.168.10.1'",
		}

Find all VMs on a host with name 'host-a'

	Request 
		POST https://operations-for-networks.example.com/api/ni/search
	Request Body
		{
  			"entity_type": "VirtualMachine",
  			"filter": "host.name = 'host-a'",
		}

Find all VMs in the NSX security group with moref 'securitygroup-10'


	Request 
		POST https://operations-for-networks.example.com/api/ni/search
	Request Body
		{
  			"entity_type": "VirtualMachine",
  			"filter": "security_groups.vendor_id = 'securitygroup-10'",
		}

Find all VMs where the name is 'vm-a' or 'vm-b' or 'vm-c'

	Request 
		POST https://operations-for-networks.example.com/api/ni/search
	Request Body
		{
  			"entity_type": "VirtualMachine",
  			"filter": "name IN ('vm-a', 'vm-b', 'vm-c')",
		}

Find all VMs where the default gateway is set

	Request 
		POST https://operations-for-networks.example.com/api/ni/search
	Request Body
		{
  			"entity_type": "VirtualMachine",
  			"filter": "default_gateway is set",
		}

Find all VMs in host 'host-a' and security group 'sg-1'

	Request 
		POST https://operations-for-networks.example.com/api/ni/search
	Request Body
		{
  			"entity_type": "VirtualMachine",
  			"filter": "((security_groups.name = 'sg-1') and (host.name = 'host-a'))",
		}

Find all VMs in security group sg-1 and that do not have network address '192.168.10.0/24'

	Request 
		POST https://operations-for-networks.example.com/api/ni/search
	Request Body
		{
  			"entity_type": "VirtualMachine",
  			"filter": "((security_groups.name = 'sg-1') and (ip_addresses.network_address != '192.168.10.0/24'))",
		}

VMware Aria Operations for Networks 6.14

Performing Search

Search Request

Entity Type

Filter Expression

Considerations

Building Filter Expression

Aggregation Search API

Group By

Examples of Search