Here you can find the transcript of Episode #139 of PiaSys TechBites.

Welcome back to PiaSys TechBites. Today we talk about Microsoft Graph advanced queries against directory objects. In fact, the Microsoft Graph team recently introduced some enhancements to the query capabilities of Microsoft Graph when the target of the query is a directory object, like a user, a group, a service principal, an organizational contact and stuff like that. Those enhancements allow us to make queries which will include the new syntax like $count, $search, $filter, and $orderby.

And in order to use these new capabilities we need to provide in the HTTP REST request, in header called ConsistencyLevel with value “eventual”. Which means that based on the fact that the Azure Active Directory service is a distributed service based on multiple servers which need to be synchronized across the whole network, the result that you get from such queries can be eventually consistent, but it is not guaranteed that it will be consistent, because it might be that the query you’re running is targeting a server which is not fully synchronized with all of the other servers that you have in the distributed infrastructure of Azure Active Directory.

So like always, let me move to the demo environment, and let me show you how to play with these new queries. So this is the official blog post through which Microsoft made the announcement of GA of Microsoft Graph advanced queries for directory objects. And here you can find a bunch of technical documentation about how to use the Advanced Queries for directory objects. This post together with the one Microsoft made in May 2020 to announce the release of the beta of this functionality is really useful if you want to dig into the details about how to use the advanced queries.

Now, let me play with the Graph Explorer to show you how the advanced query work. And let’s say, for example, that we want to make a query targeting the v1.0 endpoint to see the count, to read the count of users that I have in my tenant. Well, if I execute a query like this one, I will see that we don’t get any result and actually we get an exception. But if I go to the request headers and I add the ConsistencyLevel header with value “eventual”, as I told you. Simply by adding this custom header to the request, we can run the query, and we can see the result: the number of users in my tenant.

I can also do something else. So I can, for example, query the whole list of users and get user count. So here in the result, I see the actual data and the @data.count property to see the overall count of users. I can even filter users, for example, based on their flavor. So I can say, “Give me the count and the content of all of the users of type guest.” And I can run this query and see the result. And again, I have 10 guest users in this tenant.

But I can also play with groups, for example. So I can say, “Give me the overall number, overall count, of groups that I have in my tenant.” Or, let’s say that I just want to retrieve the count and the content of groups which are of type Unified group, meaning the Microsoft 365 Groups. So I can say again $count = true and $filter groupTypes any containing the value “Unified”. If I run this query, I can get back the number of Unified groups, so Microsoft 365 Groups, that I have in my tenant together with all of the detailed information about those groups.

And the same things can be applied to service principals, for example. So here I can say, “Give me the collection of service principals, count them, and search those that have the display name which contains the SharePoint PnP string.” If I will execute this query, I will get back the 25 service principals registered in my tenant with SharePoint PnP in their name.

And of course, I can even play with sorting, so I can add the $orderby clause to the query, and I will be able to order in descendant way the service principals with the SharePoint PnP in their display name ordered descendant by display name as well. So if I run this query, I can see my 25 service principals order descendant by display name.

So this is a really powerful set of capabilities which will improve the quality of your life whenever you want to execute the queries again directory object using Microsoft Graph. Like always, thank you for watching this video. I hope you found it interesting, and I’m really looking forward to seeing you next week. And remember to subscribe to this channel. Thank you.