Microsoft Graph advanced queries for directory objects are now generally available
We’re excited to announce that all the advanced queries for Azure AD we released in public preview in May are now generally available. This means that these new Microsoft Graph functionalities are fully supported in your production apps and you can access them through the
To recap, we enhanced the query operators for the following objects and links.
|Users||Member Of, Transitive Member Of, Owned Objects, Registered Devices, Owned Devices, Direct Reports|
|Groups||Members, Transitive Members, Owners|
|Service Principals||Member Of, Transitive Member Of|
|Devices||Member Of, Transitive Member Of, Registered Users, Registered Owners|
|Org Contacts||Member Of, Transitive Member Of|
This enables you to:
- Count objects, complex properties, and related links.
- Search on displayName and description fields using tokenization.
- Filter on new properties with new operators (such as endsWith, in, ne, ge, le).
- OrderBy on new properties and filtering at the same time.
To use the advanced queries capabilities, you must add the following to your queries:
- Query String
$count = true
ConsistencyLevel = eventual
What’s new since May?
Other than stability, availability, and performance improvements, we added new
NotEqual(on all properties)
endsWith(on mail and userPrincipalName)
Here a couple of examples:
GET ../users?$count=true&$filter=officeLocation ne null GET ../users?$count=true&$filter=endsWith(mail, 'hotmail.com')
We also indexed new properties, enabling sorting and filtering.
|Group’s expiration DateTime||Supported||GET|
|Device’s approximate Last Sign in DateTime||Supported||Supported||GET|
../users?$count=true&$filter=extension_<AppId>_<PropName> eq '<value>' ../users?$count=true&$filter=onPremisesExtensionAttributes/extensionAttribute1 eq '<value>'
You’ll see the implementation of these new capabilities in the Azure Portal soon.
Access with PowerShell
You can also access many of these functionalities with the IT admin’s favorite scripting language: PowerShell.
The Microsoft Graph PowerShell SDK is a collection of PowerShell modules that contain cmdlets for calling Microsoft Graph.
To get started:
- Install Windows Terminal (optional).
- Install PowerShell Core.
- Open PowerShell Core in Windows terminal.
Install-Module Microsoft.Graph -Repository PSGallery
- List the available commands (optional):
Get-Command -Module Microsoft.Graph*
Connect-Graph -Scopes "User.Read.All"
If you’d like to use the advanced query capabilities, you need to add the
ConsistencyLevel eventual and
count parameter to your queries:
get-mguser -consistencyLevel eventual -count userCount -search '"displayName:room"'
Note: if you need to use
search, remember to escape it with the single quote character like in the example above.
$userCount variable will contain the result-set count.
Access with .NET
As a .NET developer, there is nothing better than to have a simple SDK to access the power of our queries. We created a sample .NET Core app that mimics Graph Explorer, where you can use the advanced filter, search, and orderBy clauses.
The following screenshot shows the Not Equal filtering in action.
Are you an OData Wizard?
We created a challenging quiz to test your knowledge of Microsoft Graph and directory objects. This will help you learn about the nuances of Microsoft Graph, OData, and Azure AD.
If you think you got all the answers right, and you want to be contacted by engineers working on the Microsoft Graph Identity workload, leave your mail in the last question. We would like to hear from you!
Current limitations and next steps
The new advanced query capabilities are not yet available in B2C tenants. We are working to implement the support for it, but we don’t have any date to communicate yet. Please follow this blog or read What’s new in AAD for updates.
As usual, we’re eager to know what you think about the new capabilities to help us shape the future direction of our APIs. The Microsoft Graph UserVoice is always open, and we also created this specific survey to share your feedback. We’re listening!