Getting started with filtering and selecting Microsoft Intune data via Microsoft Graph

This week is another week focussed on retrieving data of Microsoft Intune via Microsoft Graph. This week, however, is not focussed on creating a solution, but on providing some guidance on getting started with filtering and selecting specific data. It’s relativly simple to retrieve a bulk of data, but in many cases it might be more efficient and better performing to immediately filter the data and only select specific objects and properties. This post will provide a closer look at the basics of the main query parameters and show how to use them to filter data immediately in the request. The examples provided in this post are using the managedDevice objects as example and are all tested by using Microsoft Graph Explorer.

Important: The Microsoft Graph Explorer can handle the use of spaces (” “) and quotes (‘) in queries. Make sure to encode those characters when needed. A space is %20 and a single quote is %27.

Tip: The Microsoft Graph Explorer nowadays also provides code snippets for PowerShell, by using the Microsoft Graph PowerShell module. This post also provides the related code snippets using that PowerShell module.

Note: There are still some quirks when using the different filter operators that are available. Throughout this post, the managedDevice objects are used as example and when the behavior is unexpected that’s mentioned as a note.

$select

The $select query parameter can be used to return only a specific set of selected properties. The following example can be used to only return the deviceName property of the different managedDevice objects.

https://graph.microsoft.com/beta/deviceManagement/managedDevices?$select=deviceName

Get-MgDeviceManagementManagedDevice -Property "deviceName"

To use the $select query parameter to return multiple properties, simply use a comma to separate the different properties. The following example can be used to return the deviceName property and the managementState property of the different managedDevice objects.

https://graph.microsoft.com/beta/deviceManagement/managedDevices?$select=deviceName,managementState

Get-MgDeviceManagementManagedDevice -Property "deviceName,managementState" 

$filter

The $filter query parameter can be used to only retrieve a specific set of objects from a collection. That can be achieved by using different operators within the filter.

Equality operators

Equals operator

The equals (eq) operator can be used to query for objects that have a specific property that equals the specified value. The following example can be used to only return the managedDevice objects where the deviceName property equals ‘CLDCLN53’.

https://graph.microsoft.com/beta/deviceManagement/managedDevices?$filter=deviceName eq 'CLDCLN53'

 Get-MgDeviceManagementManagedDevice -Filter "deviceName eq 'CLDCLN53'" 

Note: The not equals (ne) operator currently behaves the same for this object as the equals (eq) operator. The expectation would be that it would filter the opposite information.

Relational operators

Less than or equal operator

The less than or equal to (le) operator can be used to query for objects that have a specific property that is less than or equal to the specified value. The following example can be used to only return the managedDevice objects where the lastSyncDateTime property is less than or equal to the specified date of 2022-01-19.

https://graph.microsoft.com/beta/deviceManagement/managedDevices?$filter=lastSyncDateTime le 2022-01-19

 Get-MgDeviceManagementManagedDevice -Filter "lastSyncDateTime le 2022-01-19"  

Note: The less than (lt) operator currently behaves the same for this object as the less than or equal to (le) operator. The expectation would be that it would filter the equal to information.

Greater than or equal to operator

The greater than or equal to (ge) operator can be used to query for objects that have a specific property that is greater than or equal to the specified value. The following example can be used to only return the managedDevice objects where the lastSyncDateTime property is greater than or equal to the specified date of 2022-01-19.

https://graph.microsoft.com/beta/deviceManagement/managedDevices?$filter=lastSyncDateTime ge 2022-01-19

 Get-MgDeviceManagementManagedDevice -Filter "lastSyncDateTime ge 2022-01-19"

Note: The greater than (gt) operator currently behaves the same for this object as the greater than or equal to (ge) operator. The expectation would be that it would filter the equal to information.

Conditional operators

And operator

The and (and) operator can be used to combine multiple comparisons in a single query. The following can be used to only return the managedDevice objects where the deviceName property equals ‘CLDCLN53’ and the lastSyncDateTime property is greater than or equal to the specified date of 2022-01-19.

https://graph.microsoft.com/beta/deviceManagement/managedDevices?$filter=deviceName eq 'CLDCLN53' and lastSyncDateTime ge 2022-01-19

 Get-MgDeviceManagementManagedDevice -Filter "deviceName eq 'CLDCLN53' and lastSyncDateTime le 2022-01-19"

Note: The or (or) operator currently behaves the same for this object as the and (and) operator. The expectation would be that it would filter information based on either part.

Functions

Contains function

The contains (contains()) function can be used to query for objects that contain a specific property that contains the specified value. The following example can be used to only return the managedDevice objects where the deviceName property contains ‘N5’.

https://graph.microsoft.com/beta/deviceManagement/managedDevices?$filter=contains(deviceName, 'N5')

Get-MgDeviceManagementManagedDevice -Filter "contains(deviceName,'N5')" 

Note: The starts with (startsWith()) and the ends with (endsWith()) function currently behaves the same for this object, but should eventually be able to query start and end parts of properties.

The $top query parameter can be used to only retrieve the top number of objects from a collection. The following example can be used to return the top 5 managedDevice objects.

https://graph.microsoft.com/beta/deviceManagement/managedDevices?$top=5

Get-MgDeviceManagementManagedDevice -Top 5 

Combining parameters and operators

Now let’s end this post by bringing the different parameters and operators together in a single query. The following example can be used to return the deviceName of the top 5 objects when filtering on a specific deviceName.

https://graph.microsoft.com/beta/deviceManagement/managedDevices?$top=5&$filter=contains(deviceName, 'N5')&$select=deviceName

Get-MgDeviceManagementManagedDevice -Top 5 -Filter "contains(deviceName, 'N5')" -Property "deviceName" 

Let’s end this post by actually showing the response of the created query. That response is shown below. The number of returned objects actually matches the top 5 of objects that should be selected. Otherwise the response would would also contain a line with an @odata.nextLink that links to the objects.

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#deviceManagement/managedDevices(deviceName)",
    "@odata.count": 5,
    "value": [
        {
            "deviceName": "CLDCLN51"
        },
        {
            "deviceName": "CLDCLN52"
        },
        {
            "deviceName": "CLDCLN53"
        },
        {
            "deviceName": "CLDCLN54"
        },
        {
            "deviceName": "CLDCLN55"
        }
    ]
}

More information

For more information about the query parameters that are used throughout this post, refer to the following docs.