Jump to

• Request
• Response
• Examples

Query Entities

post

/serviceapi/entityModel/uds/entities/query

Query Entities using a JSON payload containing tag criteria.

The query parameters given are optional. All entities are returned with an empty object in the body. This allows to query by entity type, by tag criteria, or both.

Refer to the example section for some complex criteria.

Request

Supported Media Types

• application/json

Query Parameters

• limit(optional): integer(int32)
  the number of entries in the result to be returend in one REST call

  Default Value: 2000
• offset(optional): integer(int32)
  the offset into the result list when doing a query with limit

  Default Value: 0

Body ()

The query criteria

Root Schema : UdsQueryEntitiesCriteria

Type: object

This model describes the criteria used to query Entities. The criteria consists of an entity type (optional) and a tag criteria (optional).

Show Source

• entityName(optional): string
  The entity name

  Example: my_entity_name
• entityType(optional): string
  The entity type

  Example: my_entity_type
• entityTypes(optional): array entityTypes
  The list of entity types
• tagCriteria(optional): string
  The tag criteria

  Example: tagKey=tagValue AND tagKey2 IN ('value1','value2)

{
    "type":"object",
    "properties":{
        "entityName":{
            "type":"string",
            "example":"my_entity_name",
            "description":"The entity name"
        },
        "entityType":{
            "type":"string",
            "example":"my_entity_type",
            "description":"The entity type"
        },
        "entityTypes":{
            "type":"array",
            "description":"The list of entity types",
            "items":{
                "type":"string"
            }
        },
        "tagCriteria":{
            "type":"string",
            "example":"tagKey=tagValue AND tagKey2 IN ('value1','value2)",
            "description":"The tag criteria"
        }
    },
    "description":"<p>\n    This model describes the criteria used to query Entities.\n    The criteria consists of an entity type (optional) and a tag criteria (optional).\n</p>"
}

Nested Schema : entityTypes

Type: array

The list of entity types

Show Source

• Array of: string

{
    "type":"array",
    "description":"The list of entity types",
    "items":{
        "type":"string"
    }
}

Back to Top

Response

Supported Media Types

• application/json

Default Response

successful operation

Back to Top

Examples

Query all entities which are of type myHostEntity and are located in Boston:

Payload:

{
  "entityType":"myHostEntity",
  "tagCriteria":"loc=bos"
}

curl -u ${OMC_USERNAME}:${PASSWORD} -X POST -H "Content-Type:application/json" -d "@example.json" "https://serverurl/serviceapi/serviceapi/entityModel/uds/entities/query"

The output is the same format as in the GET API.

Example criteria

• Query all Entities which belong to organization sales or marketing:
  

  {
    "entityType":"myHostEntity",
    "tagCriteria":"org=sales or org=marketing"
  }

  
  This can also written as an expression
  

  {
    "entityType":"myHostEntity",
    "tagCriteria":"org=(sales,marketing)"
  }

  
  
• Query all Entities which do not belong to organization sales or marketing:
  

  {
    "entityType":"myHostEntity",
    "tagCriteria":"org!=sales and org!=marketing"
  }

  
  This can also written as an expression
  

  {
    "entityType":"myHostEntity",
    "tagCriteria":"org!=(sales,marketing)"
  }

  
  
• Query all Entities which belong to sales in Boston or support in New York City:
  

  {
    "entityType":"myHostEntity",
    "tagCriteria":"(org=sales and loc=bos) or (org=support and loc=nyc)"
  }

  
  
• Query all Entities which are tagged with a location (loc):
  

  {
    "entityType":"myHostEntity",
    "tagCriteria":"defined(loc)"
  }

  
  
• To support whitespace in tag key or values use single quotes:
  

  {
    "entityType":"myHostEntity",
    "tagCriteria":"loc='New York City'"
  }

  
  
• To support single quotes in tag key or values use backslash:
  

  {
    "entityType":"myHostEntity",
    "tagCriteria":"'org=John\'s Organization'"
  }

  
  

Back to Top