API Filtering Info

  • 16 June 2022
  • 2 replies
  • 112 views

Badge

Hi Everyone,

I've found myself doing the same searches on API filtering multiple times, so wanted to gather and share some of what I've found & learned in hopes of helping others out (and let's be honest, I'll likely need to reference this again in a few months, so it's mutually beneficial). If you find a good link or have anything to add, please feel free to respond here and add it, it might help someone else down the road. Thanks!

 

I usually start at the Get Devices Example that shows the operators nicely, but doesn't give enough examples for me:

filter filter=property{operator}value Filters the response according to the operator and value specified. Note that you can use * to match on more than one character. You can use the ‘.’ character to filter values within an object (e.g. custom properties), and multiple filters can be separated by a comma. See Example 5.

 

Operators include:

  • Greater than or equals: >:
  • Less than or equals: <:
  • Greater than: >
  • Less than: <
  • Does not equal: !:
  • Equals: :
  • Includes: ~
  • Does not include: !~
/device/devices?filter=name~QA*

 

Also, keep an eye out for filtering for special characters. There's some additional info in the REST API v2 Overview:

Filter Syntax

Filter query parameter values with special characters require encoding. Specifically:

  • Filter query parameter values with special character "+" must be encoded twice.

    For example, the parameter value in this request GET /device/devices?filter=name:"Prod+Server" should be encoded twice for a result of: "Prod%252BServer"

  • Filter query parameter values with special characters EXCEPT "+" (&, -, and so on) must be encoded once.

    For example, the parameter value in this request GET /device/devices?filter=name:"Prod&Server" should be encoded once for a result of: "Prod%26Server"

 

Here are a few simple examples:

Filtering for a custom property (note that the name and value are separate filters as @David Bond explains here):

?filter=customProperties.name:NameOfProperty,customProperties.value:ValueToFind

 

Filtering for X OR Y (meaning the API will return entries matching either one):

?filter=dataSourceName:X|Y

 

Filtering for X AND Y (meaning the API will return entries that match BOTH):

?filter=enableNetflow:X,netflowCollectorId:Y

 


2 replies

Userlevel 7
Badge +20
On 6/16/2022 at 1:58 PM, Ryan A. said:
?filter=customProperties.name:NameOfProperty,customProperties.value:ValueToFind

David Bond mentions this, but keep in mind that this doesn't look for a device where "NameOfProperty" equals "ValueToFind". Instead, it looks for a device that has a property called "NameOfProperty" and any property with "ValueToFind". 

Still, this is better than the support docs on filtering. Also, keep in mind that the SDK doesn't always implement filtering successfully.

Userlevel 1
Badge +1

*** DISREGARD ***

Being a fool, I was using CustomProperties instead of customProperties 🤣

 

----- Original Message ----

Sorry to dig up an old thread. I’m looking at trying to find a Device Group ID based on trying to match (~) a value in a few areas and this thread was one of the only ones that seems to discuss API filtering.

I’m trying to work out the filter syntax to try and match:

device group “name” 

-or-

custom property “location”

-or-

custom property “company.alias”

Unfortunately i’m not getting the results I’m looking for.  If I use the _all~{search} I do return what I”m looking for, but that may be too broad for me to use (_all).

 

I tried something like this:

api.get_device_group_list(filter=f"name~\"{search}\"||CustomProperties.value~\"{search}\"")

But it does not return anything, but when I do the same {search} using _all it does return the device group ID i’m looking for. 

In this case, the Device Group will have a custom property for “company.alias”  that I’m trying to match on. If I put the actual “name” into the search, I get the response I’m expecting.

Any ideas where I might be going wrong?

Reply