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:
|
/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):
Filtering for X OR Y (meaning the API will return entries matching either one):
Filtering for X AND Y (meaning the API will return entries that match BOTH):
Jeff_W_
·3 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:
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?
LM User
·4 years agoDavid 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.