Advanced query capabilities on Microsoft Entra ID objects - Microsoft Graph

相关文章推荐

非常酷的手套 · 如何打开浏览器开发者工具，查看控制台输出 ...· 6 月前 ·

私奔的铅笔 · ubuntu编译安装lua - 简书· 1 年前 ·

酒量大的可乐 · io.lettuce.core.redise ...· 1 年前 ·

一身肌肉的板栗 · ChatGPT做不出小学数学题？3大反常识研 ...· 1 年前 ·

踏实的刺猬 · Java遍历对象属性(反射实现) - 知乎· 1 年前 ·

This browser is no longer supported.

Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.

Download Microsoft Edge More info about Internet Explorer and Microsoft Edge

As Microsoft Entra continues to deliver more capabilities and improvements in stability, availability, and performance, Microsoft Graph also continues to evolve and scale to efficiently access the data. One way is through Microsoft Graph's increasing support for advanced query capabilities on various Microsoft Entra ID objects, also called directory objects, and their properties. For example, the addition of not ( not ), not equals ( ne ), and ends with ( endsWith ) operators on the $filter query parameter.

The Microsoft Graph query engine uses an index store to fulfill query requests. To add support for additional query capabilities on some properties, these properties are now indexed in a separate store. This separate indexing allows Microsoft Entra ID to increase support and improve the performance of the query requests. However, these advanced query capabilities aren't available by default but, the requestor must also set the ConsistencyLevel header to eventual and , except for $search , use the $count query parameter. The ConsistencyLevel header and $count are referred to as advanced query parameters .

For example, to retrieve only inactive user accounts, you can run either of these queries that use the $filter query parameter.

Option 1: Use the $filter query parameter with the eq operator. This request works by default, that is, the request doesn't require the advanced query parameters.

JavaScript PowerShell Python // Code snippets are only available for the latest version. Current version is 5.x // To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp var result = await graphClient.Users.GetAsync((requestConfiguration) => requestConfiguration.QueryParameters.Filter = "accountEnabled eq false"; // Code snippets are only available for the latest major version. Current major version is $v1.* // Dependencies import ( "context" msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go" graphusers "github.com/microsoftgraph/msgraph-sdk-go/users" //other-imports requestFilter := "accountEnabled eq false" requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{ Filter: &requestFilter, configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{ QueryParameters: requestParameters, // To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go users, err := graphClient.Users().Get(context.Background(), configuration) // Code snippets are only available for the latest version. Current version is 6.x GraphServiceClient graphClient = new GraphServiceClient(requestAdapter); UserCollectionResponse result = graphClient.users().get(requestConfiguration -> { requestConfiguration.queryParameters.filter = "accountEnabled eq false"; use Microsoft\Graph\GraphServiceClient; use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration; $graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes); $requestConfiguration = new UsersRequestBuilderGetRequestConfiguration(); $queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters(); $queryParameters->filter = "accountEnabled eq false"; $requestConfiguration->queryParameters = $queryParameters; $result = $graphServiceClient->users()->get($requestConfiguration)->wait(); from msgraph import GraphServiceClient from msgraph.generated.users.users_request_builder import UsersRequestBuilder from kiota_abstractions.base_request_configuration import RequestConfiguration graph_client = GraphServiceClient(credentials, scopes) query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters( filter = "accountEnabled eq false", request_configuration = RequestConfiguration( query_parameters = query_params, result = await graph_client.users.get(request_configuration = request_configuration) // Code snippets are only available for the latest version. Current version is 5.x // To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp var result = await graphClient.Users.GetAsync((requestConfiguration) => requestConfiguration.QueryParameters.Filter = "accountEnabled ne true"; requestConfiguration.QueryParameters.Count = true; requestConfiguration.Headers.Add("ConsistencyLevel", "eventual"); // Code snippets are only available for the latest major version. Current major version is $v1.* // Dependencies import ( "context" abstractions "github.com/microsoft/kiota-abstractions-go" msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go" graphusers "github.com/microsoftgraph/msgraph-sdk-go/users" //other-imports headers := abstractions.NewRequestHeaders() headers.Add("ConsistencyLevel", "eventual") requestFilter := "accountEnabled ne true" requestCount := true requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{ Filter: &requestFilter, Count: &requestCount, configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{ Headers: headers, QueryParameters: requestParameters, // To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go users, err := graphClient.Users().Get(context.Background(), configuration) // Code snippets are only available for the latest version. Current version is 6.x GraphServiceClient graphClient = new GraphServiceClient(requestAdapter); UserCollectionResponse result = graphClient.users().get(requestConfiguration -> { requestConfiguration.queryParameters.filter = "accountEnabled ne true"; requestConfiguration.queryParameters.count = true; requestConfiguration.headers.add("ConsistencyLevel", "eventual"); let users = await client.api('/users') .header('ConsistencyLevel','eventual') .filter('accountEnabled ne true') .get(); use Microsoft\Graph\GraphServiceClient; use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration; $graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes); $requestConfiguration = new UsersRequestBuilderGetRequestConfiguration(); $headers = [ 'ConsistencyLevel' => 'eventual', $requestConfiguration->headers = $headers; $queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters(); $queryParameters->filter = "accountEnabled ne true"; $queryParameters->count = true; $requestConfiguration->queryParameters = $queryParameters; $result = $graphServiceClient->users()->get($requestConfiguration)->wait(); from msgraph import GraphServiceClient from msgraph.generated.users.users_request_builder import UsersRequestBuilder from kiota_abstractions.base_request_configuration import RequestConfiguration graph_client = GraphServiceClient(credentials, scopes) query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters( filter = "accountEnabled ne true", count = True, request_configuration = RequestConfiguration( query_parameters = query_params, request_configuration.headers.add("ConsistencyLevel", "eventual") result = await graph_client.users.get(request_configuration = request_configuration) group

members

transitiveMembers

memberOf

transitiveMemberOf

owners

appRoleAssignments

oAuth2PermissionGrant (delegated permission grants) orgContact

memberOf

transitiveMemberOf

servicePrincipal

memberOf

transitiveMemberOf

appRoleAssignments

appRoleAssignmentsTo

oAuth2PermissionGrant

memberOf

transitiveMemberOf

ownedObjects

registeredDevices

ownedDevices

transitiveManagers

directReports

transitiveReports

appRoleAssignments

oAuth2PermissionGrant

Query scenarios that require advanced query capabilities

The following table lists query scenarios on directory objects that are supported only in advanced queries:

Description Example Use of


   $count

in a


   $filter

expression GET


   ~/users?$filter=assignedLicenses/$count eq 0&$count=true

Use of


   $search

GET


   ~/applications?$search="displayName:Browser"

Use of


   $orderby

on select properties GET


   ~/applications?$orderby=displayName&$count=true

Use of


   $filter

with the


   endsWith

operator GET


   ~/users?$count=true&$filter=endsWith(mail,'@outlook.com')

Use of


   $filter

and


   $orderby

in the same query GET


   ../applications?$orderby=displayName&$filter=startsWith(displayName, 'Box')&$count=true

Use of


   $filter

with the


   startsWith

operators on specific properties. GET


   ~/users?$filter=startsWith(mobilePhone, '25478') OR startsWith(mobilePhone, '25473')&$count=true

Use of


   $filter

with

ne

and

not

operators GET


   ~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true

Use of


   $filter

with

not

and


   startsWith

operators GET


   ~/users?$filter=NOT startsWith(displayName, 'Conf')&$count=true

Use of


   $filter

on a collection with


   endsWith

operator GET


   ~/users?$count=true&$filter=proxyAddresses/any (p:endsWith(p, 'contoso.com'))&$select=id,displayName,proxyaddresses

Use of OData cast with transitive members list GET


   ~/me/transitiveMemberOf/microsoft.graph.group?$count=true

Using


    $filter

and


    $orderby

together is supported only with advanced queries.


    $expand

is not currently supported with advanced queries.

The advanced query capabilities are currently not available for Azure AD B2C tenants.

To use advanced query capabilities in batch requests , specify the ConsistencyLevel header in the JSON body of the


    POST

request.

Support for filter by properties of Microsoft Entra ID (directory) objects

Properties of directory objects behave differently in their support for query parameters. The following are common scenarios for directory objects:

Queries that are supported by default will also work with advanced query parameters, but the response will be eventually consistent.

The

in

operator is supported by default whenever

eq

operator is supported by default.

The


    endsWith

operator is supported only with advanced query parameters by mail , otherMails , userPrincipalName , and proxyAddresses properties.

Getting empty collections (


    /$count eq 0


    /$count ne 0

) and collections with less than one object (


    /$count eq 1


    /$count ne 1

) is supported only with advanced query parameters.

The

not

and

ne

negation operators are supported only with advanced query parameters.

All properties that support the

eq

operator also supports the

ne

not

operators.

For queries that use the

any

lambda operator, use the

not

operator. See Filter using lambda operators .

The following tables summarize support for $filter operators by properties of directory objects, and indicates where querying is supported through advanced query capabilities.

Legend

Works by default. Does not require advanced query parameters.

The


    $filter

operator works by default for that property.

The


    $filter

operator requires advanced query parameters , which are:


    ConsistencyLevel=eventual

header


    $count=true

query string

The


    $filter

operator isn't supported on that property. Send us feedback to request that this property support


    $filter

for your scenarios.

Blank cells indicate that the query isn't valid for that property.

The null value column indicates that the property is nullable and filterable using


    null

Properties that aren't listed here don't support


    $filter

at all.

Administrative unit properties

Property startsWith eq Null

Support for sorting by properties of Microsoft Entra ID (directory) objects

The following table summarizes support for $orderby by properties of directory objects and indicates where sorting is supported through advanced query capabilities.

Legend

The


    $orderby

operator works by default for that property.

The


    $orderby

operator requires advanced query parameters , which are:


    ConsistencyLevel=eventual

header


    $count=true

query string

Use of


    $filter

and


    $orderby

in the same query for directory objects always requires advanced query parameters. For more information, see Query scenarios that require advanced query capabilities .

// Code snippets are only available for the latest version. Current version is 5.x // To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp await graphClient.Users.Count.GetAsync(); // Code snippets are only available for the latest major version. Current major version is $v1.* // Dependencies import ( "context" msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go" //other-imports // To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go graphClient.Users().Count().Get(context.Background(), nil) // Code snippets are only available for the latest version. Current version is 6.x GraphServiceClient graphClient = new GraphServiceClient(requestAdapter); graphClient.users().count().get(); from msgraph import GraphServiceClient graph_client = GraphServiceClient(credentials, scopes) await graph_client.users.count.get() "code": "Request_BadRequest", "message": "$count is not currently supported.", "innerError": { "date": "2021-05-18T19:03:10", "request-id": "d9bbd4d8-bb2d-44e6-99a1-71a9516da744", "client-request-id": "539da3bd-942f-25db-636b-27f6f6e8eae4"

For directory objects, $search works only in advanced queries. If the ConsistencyLevel header isn't specified, the request returns an error.

If a property or query parameter in the URL is supported only in advanced queries but either the ConsistencyLevel header or the $count=true query string is missing, the request returns an error.

If a property hasn't been indexed to support a query parameter, even if the advanced query parameters are specified, the request returns an error.

JavaScript PowerShell Python

GET https://graph.microsoft.com/beta/groups?$filter=createdDateTime ge 2021-11-01&$count=true
ConsistencyLevel: eventual
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.GetAsync((requestConfiguration) =>
	requestConfiguration.QueryParameters.Filter = "createdDateTime ge 2021-11-01";
	requestConfiguration.QueryParameters.Count = true;
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphgroups "github.com/microsoftgraph/msgraph-beta-sdk-go/groups"
	  //other-imports
headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")
requestFilter := "createdDateTime ge 2021-11-01"
requestCount := true
requestParameters := &graphgroups.GroupsRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Count: &requestCount,
configuration := &graphgroups.GroupsRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
GroupCollectionResponse result = graphClient.groups().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "createdDateTime ge 2021-11-01";
	requestConfiguration.queryParameters.count = true;
	requestConfiguration.headers.add("ConsistencyLevel", "eventual");
let groups = await client.api('/groups')
	.version('beta')
	.header('ConsistencyLevel','eventual')
	.filter('createdDateTime ge 2021-11-01')
	.get();
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Groups\GroupsRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new GroupsRequestBuilderGetRequestConfiguration();
$headers = [
		'ConsistencyLevel' => 'eventual',
$requestConfiguration->headers = $headers;
$queryParameters = GroupsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "createdDateTime ge 2021-11-01";
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->groups()->get($requestConfiguration)->wait();
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.groups.groups_request_builder import GroupsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
graph_client = GraphServiceClient(credentials, scopes)
query_params = GroupsRequestBuilder.GroupsRequestBuilderGetQueryParameters(
		filter = "createdDateTime ge 2021-11-01",
		count = True,
request_configuration = RequestConfiguration(
query_parameters = query_params,
request_configuration.headers.add("ConsistencyLevel", "eventual")
result = await graph_client.groups.get(request_configuration = request_configuration)
    "error": {
        "code": "Request_UnsupportedQuery",
        "message": "Unsupported or invalid query filter clause specified for property 'createdDateTime' of resource 'Group'.",
        "innerError": {
            "date": "2023-07-14T08:42:44",
            "request-id": "b6a5f998-94c8-430d-846d-2eaae3031492",
            "client-request-id": "2be83e05-649e-2508-bcd9-62e666168fc8"
However, a request that includes query parameters might fail silently. For example, for unsupported query parameters and for unsupported combinations of query parameters. In these cases, examine the data returned by the request to determine whether the query parameters you specified had the desired effect. For example, in the following example, the @odata.count parameter is missing even if the query is successful.
JavaScript
PowerShell
Python
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
	requestConfiguration.QueryParameters.Count = true;
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
requestCount := true
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Count: &requestCount,
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
	requestConfiguration.queryParameters.count = true;
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration)->wait();
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
graph_client = GraphServiceClient(credentials, scopes)
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		count = True,
request_configuration = RequestConfiguration(
query_parameters = query_params,
result = await graph_client.users.get(request_configuration = request_configuration)
      "displayName":"Oscar Ward",
      "mail":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"
Related content
Use query parameters to customize responses
Query parameter limitations
Use the $search query parameter to match a search criterion
Explore advanced query capabilities for Microsoft Entra ID objects with the .NET SDK
			Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.		
        
Submit and view feedback for
                    This product