Microsoft 365 Microsoft identity platform Azure AD Microsoft Graph

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 v1.0 endpoint.

To recap, we enhanced the query operators for the following objects and links.

Object Links
Users Member Of, Transitive Member Of, Owned Objects,
Registered Devices, Owned Devices, Direct Reports
Groups Members, Transitive Members, Owners
Applications 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
Administrative Units Members

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
  • Header ConsistencyLevel = eventual

Graph Explorer screenshot highlighting count=true Query String parameter and Consistency Level eventual header.

What’s new since May?

Other than stability, availability, and performance improvements, we added new $filter operators:

  • 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.

Property Filter Order by Example
Soft-Deleted DateTime Supported Supported GET
Group’s expiration DateTime Supported GET
Device’s approximate Last Sign in DateTime Supported Supported GET

Finally, we added the support for extension properties and on-premises extensions:

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

PowerShell screenshot showing the Microsoft Graph SDK in action, getting the list of users in the tenant

To get started:

  1. Install Windows Terminal (optional).
  2. Install PowerShell Core.
  3. Open PowerShell Core in Windows terminal.
  4. Install-Module Microsoft.Graph -Repository PSGallery
  5. List the available commands (optional):
    Get-Command -Module Microsoft.Graph*
  6. Import-Module Microsoft.Graph.Authentication
  7. Connect-Graph -Scopes "User.Read.All"
  8. Import-Module Microsoft.Graph.Users
  9. Get-MgUser

If you’d like to use the advanced query capabilities, you need to use a special command called Invoke-GraphRequest. This allows you to send an arbitrary request to Microsoft Graph and automatically parse the result:

$users = Invoke-GraphRequest -uri '/v1.0/users?$count=true&$select=id,displayName,mail’ -headers @{"ConsistencyLevel"="eventual"}

Now, $users will contain the OData result as-is:

PowerShell screenshot showing the content of the $users object (value and odata count)

To see the actual list of users, type:

$users.value | Select id,displayName,mail

PowerShell screenshot showing the content of $users.value: the list of the users

To get the count, type:

$users.'@odata.count'

Soon, you’ll be able to use the advanced query parameters using the standard cmdlets. Follow our blog for the latest updates.

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.

Screenshot of the sample app using the Microsoft Graph .NET SDK

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!

Next steps

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!

filter-icon