Advanced Search APIs

Required Permissions

You must be a Monitoring Administrator or a Device Administrator to perform these operations.

Create a Filtered Device List

Required Permissions

You must have the Create Filter Definition permission to perform this operation.

Description

Create a filtered device list based on a user-defined filter definition and return the ID of the list. Use the id to make a GET call of the filtered device list to view the list of devices.

You can set baseFilterDefId, queryTypeForBaseFilterDef ,templateIds, filters, projections and so on, in a CreateFilteredDeviceListRequest.

After receiving the CreateFilteredDeviceListRequest, advanced search service first verifies if baseFilterDefId is empty. If not, advanced search service retrieves the filter definition from DB and uses the filter definition values as base request parameters.

Advanced search service uses:

The union of templateIds in the request and templateIds from the filter definition.
The union of filters and the union of projections.

For parameters, such as startTimeMs, endTimeMs, values from the request has priority over values from the filter definition.

API: /api/filter-results/; Deprecated: /api/filters

Method

POST

Required Parameters


Name	Description
projection	keyQualifier `string` Key qualifier to specify the location of the key when the key is in a nested document. dataSource `string` `DEVICEMGMT_SERVICE`: Device management micro service. `CAMPAIGN_SERVICE`: Campaign management micro service. `METRIC_SERVICE`: Metric query micro service. key `string`
startTimeMs `int64`	Start time for metric filters
retentionTimeSec `string`	Retention time of a filtered device list. The list is automatically deleted after the retention time unless the user reads it. This parameter is deprecated from version 0.7 onwards.
filter `string`	Filters are always ANDed. A filter consists of a key and multiple operator-value pairs. Only the OR operation is allowed between the operator-value pairs. oredOperatorValuePair operator `string` `EQUAL_TO` `NOT_EQUAL_TO` `GREATER_THAN` `GREATER_THAN_EQUAL_TO` `LESS_THAN` `LESS_THAN_EQUAL_TO` `CONTAINS` Enter one of the following values: valueInt64 `int64` valueString `string` valueBoolean `boolean` valueDouble `double` keyObj valueType `string` `INT64` `DOUBLE` `STRING` `BOOLEAN` dataSource `string` `DEVICEMGMT_SERVICE`: Device management micro service. `CAMPAIGN_SERVICE`: Campaign management micro service. `METRIC_SERVICE`: Metric query micro service. key `string` keyQualifier `string` Key qualifier to specify the location of the key when the key is in a nested document. isPeriodRequired `string` Whether or not the key requires a period. For example, metric filter keys require a period (start/end time). keyType `PROJECTABLE` `FILTERABLE` `BOTH` displayUnit The unit of value if the key is a metric key. factor The conversion factor to convert from the reported unit of metric to the display unit of metric. This parameter is deprecated from version 0.7 onwards. displayName The display name of the filter.
endTimeMs `int64`	End time for metric filters.
offsetMs `int64`	A time amount to be subtracted from the current time, for the start time of a relative time-ranged query. Note: You must specify either the startTimeMs and endTimeMs parameters or the offsetMs parameter.
limit `int32`	The maximum number of results.
isRelative `boolean`	Indicate whether the time range is relative or not.
templateId `string`	Device template Ids.
queryType	SHOW_CURRENT, SHOW_DESCENDANTS
queryTypeForBaseFilterDef	SHOW_CURRENT, SHOW_ANCESTORS

Input Example

{
"filter": [
{
"keyObj": {
"dataSource": "DEVICEMGMT_SERVICE",
"key": "id",
"keyQualifier": "device",
"valueType": "STRING",
"keyType": "BOTH"
},
"oredOperationValuePair": [
{
"operator": "2",
"valueString": "1"
}
]
}
],
"projection": [
{
"dataSource": "DEVICEMGMT_SERVICE",
"key": "name",
"keyQualifier": "device"
}
],
"templateId": [
"2c18410f-fe2e-48e6-ae13-8b040704916e"
],
"limit": 2
}

Response

{
  "id": "string"
}

Get a Filtered Device List

Required Permissions

You must have the View Filter Definition permission to perform this operation.

API

/api/filter-results/{id}

Deprecated: /api/filters/{id}

Method

GET

Optional Parameters


Name	Description
queryType	SHOW_CURRENT, SHOW_ANCESTORS

Response

{
  "filteredDevice": [
    {
      "keyValuePair": [
        {
          "valueString": "string",
          "key": "string",
        }
      ],
      "id": "string"
    }
  ],
  "aggregationTaskStatus": "STARTED",
  "pageInfo": {
    "totalPages": 2,
    "totalElements": 2",
    "page": 1,
    "pageSize": 1
  }
}

Delete a Filtered Device List

Required Permissions: You must have the Delete Filter Definition permission to perform this operation.
API: /api/filter-results/{id}; Deprecated: /api/filters/{id}

Method: DELETE

Required Parameters


Name	Description
id `string`	ID of the filtered device list.

Response

{}

Get All Keys for Filters and Projections

Required Permissions

You must have the View Filter Definition permission to perform this operation.

API

/api/filter-keys

Deprecated: /api/filters/filter-keys

Method

GET

Required Parameters

None

Optional Parameters


Name	Description
queryType	SHOW_CURRENT, SHOW_ANCESTORS

Response

{
  "keyObjs": [
    {
      "valueType": "BOOLEAN",
      "keyQualifier": "string",
      "isPeriodRequired": false,
      "dataSource": "CAMPAIGN_SERVICE",
      "key": "string"
      "keyType": "BOTH"
    },
    {
      "valueType": "INT64",
      "keyQualifier": "string",
      "isPeriodRequired": true,
      "dataSource": "METRIC_SERVICE",
      "key": "string",
      "keyType": "FILTERABLE",
      "displayUnit" :"%",
      "factor": 1
    }
  ]
}

Save a Filter Definition

Required Permissions: You must have the Edit Filter Definition permission to perform this operation.
API: /api/filter-definitions; Deprecated: /api/filters/definitions

Method

POST

Required Parameters


Name	Description
projection	keyQualifier `string` Key qualifier to specify the location of the key when the key is in a nested document. dataSource `string` `DEVICEMGMT_SERVICE`: Device management micro service. `CAMPAIGN_SERVICE`: Campaign management micro service. `METRIC_SERVICE`: Metric query micro service. key `string`
startTimeMs `int64`	Start time for metric filters.
retentionTimeSec `string`	Retention time of a filtered device list. The list is automatically deleted after the retention time unless the user reads it.
filter `string`	Filters are always ANDed. A filter consists of a key and multiple operator-value pairs. Only the OR operation is allowed between the operator-value pairs. oredOperatorValuePair operator `string` `EQUAL_TO` `NOT_EQUAL_TO` `GREATER_THAN` `GREATER_THAN_EQUAL_TO` `LESS_THAN` `LESS_THAN_EQUAL_TO` `CONTAINS` Enter one of the following values: valueInt64 `int64` valueString `string` valueBoolean `boolean` valueDouble `double` keyObj valueType `string` `INT64` `DOUBLE` `STRING` `BOOLEAN` dataSource `string` `DEVICEMGMT_SERVICE`: Device management micro service. `CAMPAIGN_SERVICE`: Campaign management micro service. `METRIC_SERVICE`: Metric query micro service. key `string` keyQualifier `string` Key qualifier to specify the location of the key when the key is in a nested document. isPeriodRequired `string` Whether or not the key requires a period. For example, metric filter keys require a period (start/end time). keyType `PROJECTABLE` `FILTERABLE` `BOTH` displayUnit The unit of value if the key is a metric key. factor The conversion factor to convert from the reported unit of metric to the display unit of metric.
endTimeMs `int64`	End time for metric filters.
isRelative `boolean`	Indicate whether the time range is relative or not.
templateId `string`	Device template Ids.

Input Example

{
          name: "string",
          templateId: ["string", "string"],
          filter: [
             keyObj: {
                dataSource: "DEVICEMGMT_SERVICE",
                key: "string",
                keyQualifier: "string",
                valueType: "STRING",
                isPeriodRequired: false,
                keyType: "BOTH"
               },
               oredOperationValuePair: [
                 {
                   operator: "EQUAL_TO",
                   valueString: "blue"
                 },
                 {
                   operator: "EQUAL_TO",
                   valueString: "red"
                 }
                ]
              },
            {
             keyObj: {
             dataSource: "CAMPAIGN_SERVICE",
              key: "string",
              keyQualifier: "",
              valueType: "STRING",
              isPeriodRequired: false,
              keyType: "BOTH"
            },
            oredOperationValuePair: [
              {
                operator: "EQUAL_TO",
                valueString: "INITIALIZED"
              }
            ]
           },
           {
             keyObj: {
               "dataSource": "METRIC_SERVICE",
               "key": "string",
               "keyType": "FILTERABLE",
               "valueType": "INT64",
               "keyQualifier": "string",
               "isPeriodRequired": true, 
               "displayUnit" :"%",
               "factor": 1
           }
           },
           oredOperationValuePair: [
             {
               operator: "GREATER_THAN",
               valueInt64: 90
             }
           ]
          }
         ],
         projection: [
            {
               "dataSource": "CAMPAIGN_SERVICE",
               "key": "string",
               "keyQualifier": ""
            }
         ],
         startTimeMs: 1500000001000,
         endTimeMs: 1500000002000
        }

Response

{
  "id": "string"
}

Update a Filter Definition

Required Permissions: You must have the Edit Filter Definition permission to perform this operation.
API: /api/filter-definitions/{id}; Deprecated: /api/filters/definitions/{id}

Method

PUT

Required Parameters


Name	Description
projection	keyQualifier `string` Key qualifier to specify the location of the key when the key is in a nested document. dataSource `string` `DEVICEMGMT_SERVICE`: Device management micro service. `CAMPAIGN_SERVICE`: Campaign management micro service. `METRIC_SERVICE`: Metric query micro service. key `string`
startTimeMs `int64`	Start time for metric filters.
retentionTimeSec `string`	Retention time of a filtered device list.
filter `string`	Filters are always ANDed. A filter consists of a key and multiple operator-value pairs. Only the OR operation is allowed between the operator-value pairs. oredOperatorValuePair operator `string` `EQUAL_TO` `NOT_EQUAL_TO` `GREATER_THAN` `GREATER_THAN_EQUAL_TO` `LESS_THAN` `LESS_THAN_EQUAL_TO` `CONTAINS` Enter one of the following values: valueInt64 `int64` valueString `string` valueBoolean `boolean` valueDouble `double` keyObj valueType `string` `INT64` `DOUBLE` `STRING` `BOOLEAN` dataSource `string` `DEVICEMGMT_SERVICE`: Device management micro service. `CAMPAIGN_SERVICE`: Campaign management micro service. `METRIC_SERVICE`: Metric query micro service. key `string` keyQualifier `string` Key qualifier to specify the location of the key when the key is in a nested document. isPeriodRequired `string` Whether or not the key requires a period-like metric key. keyType `PROJECTABLE` `FILTERABLE` `BOTH` displayUnit The unit of value if the key is a metric key. factor The conversion factor to convert from the reported unit of metric to the display unit of metric.
endTimeMs `int64`	End time for metric filters.
offsetMs `int64`	A time amount to be subtracted from the current time, for the start time of a relative time-ranged query. Note: You must specify either the startTimeMs and endTimeMs parameters or the offsetMs parameter.
isRelative `boolean`	Indicate whether the time range is relative or not.
templateId `string`	Device template Ids.

Input Example

{
          name: "string",
          templateId: ["string", "string"],
          filter: [
             keyObj: {
                dataSource: "DEVICEMGMT_SERVICE",
                key: "string",
                keyQualifier: "string",
                valueType: "STRING",
                isPeriodRequired: false,
                keyType: "BOTH"
               },
               oredOperationValuePair: [
                 {
                   operator: "EQUAL_TO",
                   valueString: "blue"
                 },
                 {
                   operator: "EQUAL_TO",
                   valueString: "red"
                 }
                ]
              },
            {
             keyObj: {
             dataSource: "CAMPAIGN_SERVICE",
              key: "string",
              keyQualifier: "",
              valueType: "STRING",
              isPeriodRequired: false,
              keyType: "BOTH"
            },
            oredOperationValuePair: [
              {
                operator: "EQUAL_TO",
                valueString: "INITIALIZED"
              }
            ]
           },
           {
             keyObj: {
             dataSource: "METRIC_SERVICE",
              key: "string",
              keyQualifier: "",
              valueType: "NUMBER",
              isPeriodRequired: true,
              keyType: "FILTERABLE"
           },
           oredOperationValuePair: [
             {
               operator: "GREATER_THAN",
               valueInt64: 90
             }
           ]
          }
         ],
         projection: [
            {
               "dataSource": "CAMPAIGN_SERVICE",
               "key": "string",
               "keyQualifier": ""
            }
         ],
         startTimeMs: 1500000001000,
         endTimeMs: 1500000002000
        }

Response

{
  "id": "string"
}

Get a Filter Definition by ID

Required Permissions

You must have the View Filter Definition permission to perform this operation.

API

/api/filter-definitions/{id}

Deprecated: /api/filters/definitions/{id}

Method

GET

Required Parameters


Name	Description
id `string`	ID of the filter definition.

Optional Parameters


Name	Description
queryType	SHOW_CURRENT, SHOW_ANCESTORS

Response

{
  "id": "string",
  "name": "string",
  "templateId": ["string", "string"],
  "filter": [
       {
          "keyObj": {
              "dataSource": "DEVICEMGMT_SERVICE",
              "key": "type",
              "keyQualifier": "device",
              "valueType": "STRING"
          }
        }
    ],
    "projection": [
        {
            "dataSource": "CAMPAIGN_SERVICE",
            "key": "string"
        },
        {
            "dataSource": "DEVICEMGMT_SERVICE",
            "key": "string",
            "keyQualifier": "string"
        }
    ],
    "startTimeMs": 1500000000000,
    "endTimeMs": 1500000001000,
    "tenantId": "string",
    "createdTime": 1500000002000,
    "lastUpdatedTime": 1500000003000,
    "createdBy": "string",
    "lastUpdatedBy": "string",
    "updateVersion": 2
}

Delete a Filter Definition by ID

Required Permissions

You must have the Delete Filter Definition permission to perform this operation.

API

/api/filter-definitions/{id}

Deprecated: /api/filters/definitions/{id}

Method

DELETE

Required Parameters


Name	Description
id `string`	ID of the filter definition.

Response

{}

Get a Filter Definition List

Required Permissions

You must have the View Filter Definition permission to perform this operation.

API

/api/filter-definitions

Deprecated: /api/filters/definitions

Method

GET

Required Parameters


Name	Description
id	ID of the filter definition.
page.number `int32`	Enter the number of pages to be displayed.
page.size `int32`	Enter the number of items to be displayed per page. The default number is 10.

Optional Parameters


Name	Description
queryType	SHOW_CURRENT, SHOW_ANCESTORS

Response

{
  "filterDefinitionObjIdName": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "pageInfo": {
    "page": 1,
    "pageSize": 10
    "totalElements": "1",
    "totalPages": "1"
    
  }
}