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:
|
/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
