Forum Discussion

Ryan_A_'s avatar
Ryan_A_
3 years ago

API Filtering Info

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

 

  • Anonymous's avatar
    Anonymous
    3 years ago
    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.

  • Jeff_W_'s avatar
    Jeff_W_
    2 years ago

    *** 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?