{"id":5375,"date":"2020-10-02T16:37:35","date_gmt":"2020-10-02T23:37:35","guid":{"rendered":"https:\/\/officedevblogs.wpengine.com\/?p=5375"},"modified":"2020-10-02T16:37:35","modified_gmt":"2020-10-02T23:37:35","slug":"microsoft-graph-advanced-queries-for-directory-objects-are-now-generally-available","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/microsoft-graph-advanced-queries-for-directory-objects-are-now-generally-available\/","title":{"rendered":"Microsoft Graph advanced queries for directory objects are now generally available"},"content":{"rendered":"<p style=\"padding: 0px\">We&#8217;re excited to announce that all the advanced queries for Azure AD we <a href=\"https:\/\/aka.ms\/CountFilterMSGraphAAD\">released in public preview in May<\/a> 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 <code>v1.0<\/code> endpoint.<\/p>\n<p>To recap, we enhanced the query operators for the following objects and links.<\/p>\n<table>\n<tbody style=\"vertical-align: top\">\n<tr style=\"border-bottom: 1px solid #ddd\">\n<td><strong>Object<\/strong><\/td>\n<td><strong>Links<\/strong><\/td>\n<\/tr>\n<tr>\n<td><strong>Users<\/strong><\/td>\n<td>Member Of, Transitive Member Of, Owned Objects,\nRegistered Devices, Owned Devices, Direct Reports<\/td>\n<\/tr>\n<tr>\n<td><strong>Groups<\/strong><\/td>\n<td>Members, Transitive Members, Owners<\/td>\n<\/tr>\n<tr>\n<td><strong>Applications<\/strong><\/td>\n<td>Owners<\/td>\n<\/tr>\n<tr>\n<td><strong>Service Principals<\/strong><\/td>\n<td>Member Of, Transitive Member Of<\/td>\n<\/tr>\n<tr>\n<td><strong>Devices<\/strong><\/td>\n<td>Member Of, Transitive Member Of,\nRegistered Users, Registered Owners<\/td>\n<\/tr>\n<tr>\n<td><strong>Org Contacts<\/strong><\/td>\n<td>Member Of, Transitive Member Of<\/td>\n<\/tr>\n<tr>\n<td><strong>Administrative Units<\/strong><\/td>\n<td>Members<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>This enables you to:<\/p>\n<ul>\n<li><a href=\"https:\/\/docs.microsoft.com\/en-us\/graph\/query-parameters?#count-parameter\">Count<\/a> objects, complex properties, and related links.<\/li>\n<li><a href=\"https:\/\/docs.microsoft.com\/en-us\/graph\/query-parameters?#using-search-on-directory-object-collections\">Search<\/a> on <strong>displayName<\/strong> and description fields using tokenization.<\/li>\n<li><a href=\"https:\/\/docs.microsoft.com\/en-us\/graph\/query-parameters?#filter-parameter\">Filter<\/a> on new properties with new operators (such as endsWith, in, ne, ge, le).<\/li>\n<li><a href=\"https:\/\/docs.microsoft.com\/en-us\/graph\/query-parameters?#orderby-parameter\">OrderBy<\/a> on new properties and filtering at the same time.<\/li>\n<\/ul>\n<p>To use the advanced queries capabilities, you must add the following to your queries:<\/p>\n<ul>\n<li><span style=\"min-width: 120px\"><strong>Query String<\/strong><\/span> <code class=\"language-plaintext\">$count = true<\/code><\/li>\n<li><span style=\"min-width: 120px\"><strong>Header<\/strong><\/span> <code class=\"language-plaintext\">ConsistencyLevel = eventual<\/code><\/li>\n<\/ul>\n<p><a href=\"https:\/\/developer.microsoft.com\/en-us\/graph\/graph-explorer?request=users%3F%24count%3Dtrue&amp;method=GET&amp;version=v1.0&amp;GraphUrl=https:\/\/graph.microsoft.com&amp;headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d\" target=\"_blank\" rel=\"noopener noreferrer\"><img decoding=\"async\" class=\"wp-image-5376 alignnone\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/09\/Picture1-1.png\" alt=\"Graph Explorer screenshot highlighting count=true Query String parameter and Consistency Level eventual header.\" width=\"650\" height=\"221\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/09\/Picture1-1.png 936w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/09\/Picture1-1-300x102.png 300w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/09\/Picture1-1-768x261.png 768w\" sizes=\"(max-width: 650px) 100vw, 650px\" \/><\/a><\/p>\n<h3>What\u2019s new since May?<\/h3>\n<p style=\"padding: 0px\">Other than stability, availability, and performance improvements, we added new <code>$filter<\/code> operators:<\/p>\n<ul>\n<li><code>NotEqual<\/code> (on all properties)<\/li>\n<li><code>endsWith<\/code> (on mail and userPrincipalName)<\/li>\n<\/ul>\n<p>Here a couple of examples:<\/p>\n<pre><a href=\"https:\/\/developer.microsoft.com\/en-us\/graph\/graph-explorer?request=users%3F%24filter%3DofficeLocation%20ne%20null%26%24count%3Dtrue&amp;method=GET&amp;version=v1.0&amp;GraphUrl=https:\/\/graph.microsoft.com&amp;headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d\" target=\"_blank\" rel=\"noopener noreferrer\">GET<\/a> ..\/users?$count=true&amp;$filter=officeLocation ne null\n<a href=\"https:\/\/developer.microsoft.com\/en-us\/graph\/graph-explorer?request=users%3F%24count%3Dtrue%26%24filter%3DendsWith(mail%2C%20'hotmail.com')%26%24select%3Did%2CdisplayName%2Cmail&amp;method=GET&amp;version=v1.0&amp;GraphUrl=https:\/\/graph.microsoft.com&amp;headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d\" target=\"_blank\" rel=\"noopener noreferrer\">GET<\/a> ..\/users?$count=true&amp;$filter=endsWith(mail, 'hotmail.com')<\/pre>\n<p style=\"padding: 0px\">We also indexed new properties, enabling sorting and filtering.<\/p>\n<table>\n<tbody style=\"vertical-align: top\">\n<tr style=\"border-bottom: 1px solid #ddd\">\n<td><strong>Property<\/strong><\/td>\n<td><strong>Filter<\/strong><\/td>\n<td><strong>Order by<\/strong><\/td>\n<td><strong>Example<\/strong><\/td>\n<\/tr>\n<tr>\n<td>Soft-Deleted DateTime<\/td>\n<td style=\"text-align: center\">Supported<\/td>\n<td style=\"text-align: center\">Supported<\/td>\n<td><a href=\"https:\/\/developer.microsoft.com\/en-us\/graph\/graph-explorer?request=directory%2FdeletedItems%2Fmicrosoft.graph.user%3F%24count%3Dtrue%26%24select%3Did%2CdisplayName%2CdeletedDateTime%26%24orderby%3DdeletedDateTime%20desc%26%24filter%3DdeletedDateTime%20ge%202020-09-30T00%3A00%3A00Z&amp;method=GET&amp;version=v1.0&amp;GraphUrl=https:\/\/graph.microsoft.com&amp;headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d\" target=\"_blank\" rel=\"noopener noreferrer\">GET<\/a><\/td>\n<\/tr>\n<tr>\n<td>Group\u2019s expiration DateTime<\/td>\n<td style=\"text-align: center\">Supported<\/td>\n<td style=\"text-align: center\"><\/td>\n<td><a href=\"https:\/\/developer.microsoft.com\/en-us\/graph\/graph-explorer?request=groups%3F%24count%3Dtrue%26%24filter%3DexpirationDateTime%20le%202020-09-30T00%3A00%3A00Z%26%24select%3Did%2CdisplayName%2CexpirationDateTime&amp;method=GET&amp;version=v1.0&amp;GraphUrl=https:\/\/graph.microsoft.com&amp;headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d\" target=\"_blank\" rel=\"noopener noreferrer\">GET<\/a><\/td>\n<\/tr>\n<tr>\n<td>Device\u2019s approximate Last Sign in DateTime<\/td>\n<td style=\"text-align: center\">Supported<\/td>\n<td style=\"text-align: center\">Supported<\/td>\n<td><a href=\"https:\/\/developer.microsoft.com\/en-us\/graph\/graph-explorer?request=devices%3F%24count%3Dtrue%26%24orderBy%3DapproximateLastSignInDateTime%20desc%26%24filter%3DapproximateLastSignInDateTime%20ge%202020-09-30T00%3A00%3A00Z%26%24select%3Did%2CdisplayName%2CapproximateLastSignInDateTime&amp;method=GET&amp;version=v1.0&amp;GraphUrl=https:\/\/graph.microsoft.com&amp;headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d\" target=\"_blank\" rel=\"noopener noreferrer\">GET<\/a><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>Finally, we added the support for <a href=\"https:\/\/docs.microsoft.com\/en-us\/graph\/extensibility-overview\" target=\"_blank\" rel=\"noopener noreferrer\">extension properties<\/a> and <a href=\"https:\/\/docs.microsoft.com\/en-us\/graph\/api\/resources\/onpremisesextensionattributes?view=graph-rest-1.0\" target=\"_blank\" rel=\"noopener noreferrer\">on-premises extensions<\/a>:<\/p>\n<pre>..\/users?$count=true&amp;$filter=extension_&lt;AppId&gt;_&lt;PropName&gt; eq '&lt;value&gt;'\n..\/users?$count=true&amp;$filter=onPremisesExtensionAttributes\/extensionAttribute1\u00a0eq '&lt;value&gt;'<\/pre>\n<p>You&#8217;ll see the implementation of these new capabilities in the Azure Portal soon.<\/p>\n<h3>Access with PowerShell<\/h3>\n<p style=\"padding: 0px\">You can also access many of these functionalities with the IT admin\u2019s favorite scripting language: <strong>PowerShell<\/strong>.<\/p>\n<p>The <a href=\"https:\/\/github.com\/microsoftgraph\/msgraph-sdk-powershell\" target=\"_blank\" rel=\"noopener noreferrer\">Microsoft Graph PowerShell SDK<\/a> is a collection of PowerShell modules that contain cmdlets for calling Microsoft Graph.<\/p>\n<p><img decoding=\"async\" class=\"wp-image-5377 size-full alignnone\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/09\/Picture2.png\" alt=\"PowerShell screenshot showing the Microsoft Graph SDK in action, getting the list of users in the tenant\" width=\"624\" height=\"342\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/09\/Picture2.png 624w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/09\/Picture2-300x164.png 300w\" sizes=\"(max-width: 624px) 100vw, 624px\" \/><\/p>\n<p>To get started:<\/p>\n<ol>\n<li>Install <a href=\"https:\/\/aka.ms\/terminal\" target=\"_blank\" rel=\"noopener noreferrer\">Windows Terminal<\/a> (optional).<\/li>\n<li>Install <a href=\"https:\/\/docs.microsoft.com\/en-us\/powershell\/scripting\/install\/installing-powershell?view=powershell-7\" target=\"_blank\" rel=\"noopener noreferrer\">PowerShell Core.<\/a><\/li>\n<li>Open PowerShell Core in Windows terminal.<\/li>\n<li><code>Install-Module Microsoft.Graph -Repository PSGallery<\/code><\/li>\n<li>List the available commands (optional):\n<code>Get-Command -Module Microsoft.Graph*<\/code><\/li>\n<li><code>Import-Module Microsoft.Graph.Authentication<\/code><\/li>\n<li><code>Connect-Graph -Scopes \"User.Read.All\"<\/code><\/li>\n<li><code>Import-Module Microsoft.Graph.Users<\/code><\/li>\n<li><code>Get-MgUser<\/code><\/li>\n<\/ol>\n<p style=\"padding: 0px\">If you\u2019d like to use the advanced query capabilities, you need to add the <code>ConsistencyLevel eventual<\/code> and <code>count<\/code> parameter to your queries:<\/p>\n<pre style=\"padding: 12px\" class=\"\">get-mguser -consistencyLevel eventual -count userCount -search '\"displayName:room\"'<\/pre>\n<p style=\"padding: 0px\"><img decoding=\"async\" class=\"alignnone wp-image-5572\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/10\/get-mguser-search.png\" alt=\"PowerShell screenshot showing the user search command and result set\" width=\"650\" height=\"119\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/10\/get-mguser-search.png 1784w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/10\/get-mguser-search-300x55.png 300w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/10\/get-mguser-search-1024x187.png 1024w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/10\/get-mguser-search-768x140.png 768w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/10\/get-mguser-search-1536x281.png 1536w\" sizes=\"(max-width: 650px) 100vw, 650px\" \/><\/p>\n<p><strong>Note:<\/strong> if you need to use <code>search<\/code>, remember to escape it with the single quote character like in the example above. <code>$userCount<\/code> variable will contain the result-set count.<\/p>\n<h3>Access with .NET<\/h3>\n<p style=\"padding: 0px\">As a .NET developer, there is nothing better than to have a simple SDK to access the power of our queries. We created a <a href=\"https:\/\/github.com\/microsoftgraph\/dotnet-aad-query-sample\" target=\"_blank\" rel=\"noopener noreferrer\">sample .NET Core app<\/a> that mimics <a href=\"https:\/\/aka.ms\/ge\" target=\"_blank\" rel=\"noopener noreferrer\">Graph Explorer<\/a>, where you can use the advanced filter, search, and orderBy clauses.<\/p>\n<p>The following screenshot shows the Not Equal filtering in action.<\/p>\n<p><a href=\"https:\/\/github.com\/microsoftgraph\/dotnet-aad-query-sample\" target=\"_blank\" rel=\"noopener noreferrer\"><img decoding=\"async\" class=\"wp-image-5380 alignnone\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/09\/Picture5.png\" alt=\"Screenshot of the sample app using the Microsoft Graph .NET SDK\" width=\"650\" height=\"474\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/09\/Picture5.png 936w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/09\/Picture5-300x219.png 300w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/09\/Picture5-768x560.png 768w\" sizes=\"(max-width: 650px) 100vw, 650px\" \/><\/a><\/p>\n<h3>Are you an OData Wizard?<\/h3>\n<p style=\"padding: 0px\">We created a <a href=\"https:\/\/aka.ms\/MSGraphAADQuiz\" target=\"_blank\" rel=\"noopener noreferrer\">challenging quiz<\/a> 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.<\/p>\n<p>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!<\/p>\n<h3>Current limitations and next steps<\/h3>\n<p style=\"padding: 0px\">The new advanced query capabilities are <strong>not yet available in B2C tenants<\/strong>. We are working to implement the support for it, but we don&#8217;t have any date to communicate yet. Please follow this blog or read <a href=\"https:\/\/docs.microsoft.com\/en-us\/azure\/active-directory\/fundamentals\/whats-new\" target=\"_blank\" rel=\"noopener noreferrer\"><em>What&#8217;s new in AAD<\/em><\/a> for updates.<\/p>\n<p>As usual, we&#8217;re eager to know what you think about the new capabilities to help us shape the future direction of our APIs.\nThe <a href=\"https:\/\/microsoftgraph.uservoice.com\/forums\/920506-microsoft-graph-feature-requests?category_id=359596\" target=\"_blank\" rel=\"noopener noreferrer\">Microsoft Graph UserVoice<\/a> is always open, and we also created <a href=\"https:\/\/aka.ms\/MSGraphAADSurvey\" target=\"_blank\" rel=\"noopener noreferrer\">this specific survey<\/a> to share your feedback. We&#8217;re listening!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Developers can query the directory objects with Microsoft Graph using $count, $filter, $search, and $orderBy on more objects, properties, and links.<\/p>\n","protected":false},"author":69076,"featured_media":25159,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3,5],"tags":[22,34,145],"class_list":["post-5375","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-graph","category-microsoft-identity-platform","tag-azure-ad","tag-microsoft-graph-toolkit","tag-power-shell"],"acf":[],"blog_post_summary":"<p>Developers can query the directory objects with Microsoft Graph using $count, $filter, $search, and $orderBy on more objects, properties, and links.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/5375","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69076"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=5375"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/5375\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=5375"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=5375"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=5375"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}