Microsoft Entra ID 对象的高级查询功能

Microsoft Graph 支持对各种Microsoft Entra ID对象（也称为目录对象）的高级查询功能，以帮助有效地访问数据。示例包括添加 not (not) 、不等于 (ne) ，并在查询参数上$filter以 (endsWith) 运算符结尾。

Microsoft Graph 查询引擎使用索引存储来满足查询请求。若要添加对某些属性的额外查询功能的支持，这些属性在单独的存储中编制索引。这种单独的索引可以提高查询性能。但是，默认情况下，这些高级查询功能不可用。请求者必须将 ConsistencyLevel 标头设置为 eventual，除了 $search之外，请使用 $count 查询参数。 ConsistencyLevel标头和$count被称为高级查询参数。

例如，若要仅检索非活动用户帐户，可以运行以下任一使用查询参数的 $filter 查询：

选项 1： 将 $filter 查询参数与运算符一起使用 eq 。此请求默认有效，不需要高级查询参数。

GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled eq false


// 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";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('accountEnabled eq false')
	.get();


<?php
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();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "accountEnabled eq false"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
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)

选项 2： 将 $filter 查询参数与运算符一起使用 ne 。默认情况下不支持此请求， ne 因为运算符仅在高级查询中受支持。因此，必须将 ConsistencyLevel 标头设置为 eventual并使用$count=true查询字符串。

GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled ne true&$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.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");
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.header('ConsistencyLevel','eventual')
	.filter('accountEnabled ne true')
	.get();


<?php
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();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "accountEnabled ne true" -CountVariable CountVar  -ConsistencyLevel eventual


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
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)

Microsoft Entra ID (目录) 支持高级查询功能的对象

仅目录对象及其关系支持高级查询功能，包括以下对象：

Object	关系
administrativeUnit	members
application	所有者
appRoleAssignment	-
设备	memberOf transitiveMemberOf registeredUsers registeredOwners
group	members transitiveMembers memberOf transitiveMemberOf 所有者 appRoleAssignments
oAuth2PermissionGrant（委派的权限授予）	-
orgContact	memberOf transitiveMemberOf
servicePrincipal	memberOf 所有者 transitiveMemberOf appRoleAssignments appRoleAssignedTo oAuth2PermissionGrant
user	memberOf transitiveMemberOf ownedObjects registeredDevices ownedDevices transitiveManagers directReports transitiveReports appRoleAssignments oAuth2PermissionGrant

注意

$filter仅高级查询参数支持对上述目录对象列表的关系使用。但是，在这种情况下，不要 $expand 在同一个请求中使用，因为高级查询参数不支持它。

需要高级查询功能的查询方案

下表列出了高级查询支持的目录对象的查询方案：

说明	示例
使用 `$count` 作为 URL 段	GET`~/groups/$count`
使用 `$count` 作为查询字符串参数	GET`~/servicePrincipals?$count=true`
在 `$filter` 表达式中使用 `$count`	GET`~/users?$filter=assignedLicenses/$count eq 0&$count=true`
使用 `$search`	GET`~/applications?$search="displayName:Browser"`
对选择属性使用 `$orderby`	GET`~/applications?$orderby=displayName&$count=true`
将 `$filter` 与 `endsWith` 运算符结合使用	GET`~/users?$count=true&$filter=endsWith(mail,'@outlook.com')`
在同一查询中使用`$filter`和`$orderby`	GET`../applications?$orderby=displayName&$filter=startsWith(displayName, 'Box')&$count=true`
对特定属性将 `$filter` 与 `startsWith` 运算符结合使用.	GET`~/users?$filter=startsWith(mobilePhone, '25478') OR startsWith(mobilePhone, '25473')&$count=true`
将 `$filter` 与 `ne` 和 `not` 运算符结合使用	GET`~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true`
将 `$filter` 与 `not` 和 `startsWith` 运算符结合使用	GET`~/users?$filter=NOT startsWith(displayName, 'Conf')&$count=true`
在带有 `endsWith` 运算符的集合上使用 `$filter`	GET`~/users?$count=true&$filter=proxyAddresses/any (p:endsWith(p, 'contoso.com'))&$select=id,displayName,proxyaddresses`
将 OData 强制转换与可传递成员列表配合使用	GET`~/me/transitiveMemberOf/microsoft.graph.group?$count=true`

注意

只能将 $filter 和 $orderby 与高级查询结合使用。
高级查询当前不支持 $expand。
Azure AD B2C 租户当前不支持高级查询功能。
若要在批处理请求中使用高级查询功能，请在 POST 请求的 JSON 正文中指定 ConsistencyLevel 标头。

支持按Microsoft Entra ID (目录) 对象的属性进行筛选

目录对象的属性对查询参数的支持行为各不相同。以下是目录对象的常见应用场景:

默认情况下，只要默认支持eq运算符，则默认支持in运算符。
endswith仅高级查询参数支持运算符，并且仅受 mail、otherMails、userPrincipalName 和 proxyAddresses 属性的支持。
获取空集合 (/$count eq 0、 /$count ne 0) 和对象少于 (/$count eq 1的集合， /$count ne 1) 仅支持高级查询参数。
not和 ne 求反运算符仅支持高级查询参数。
- 支持 eq 运算符的所有属性也支持 ne 或 not 运算符。
- 对于使用 any lambda 运算符的查询，请使用 not 运算符。请参阅使用 lambda 运算符的筛选器。

下表按目录对象的属性汇总了对 $filter 运算符的支持，并指示通过高级查询功能支持查询的位置。

图例

运算符 $filter 默认适用于该属性。
运算符 $filter 仅在没有高级查询参数 的情况下 工作。
运算符$filter需要高级查询参数，这些参数包括：
- ConsistencyLevel=eventual 标头
- $count=true 查询字符串
该 $filter 属性不支持运算符。向我们发送反馈，请求此属性支持 $filter 方案。
空白单元格指示查询对该属性无效。
列 null 值 指示该属性可为 null 且可使用 null筛选。
此处未列出的属性根本不支持 $filter 。

管理单元属性

属性	eq	startsWith	eq Null
description
displayName
isMemberManagementRestricted
membershipRule
membershipRuleProcessingState

应用程序属性

属性	eq	startsWith	ge/le	eq Null
appId
createdDateTime
description
disabledByMicrosoftStatus
displayName
federatedIdentityCredentials/any (f：f/issuer)
federatedIdentityCredentials/any (f：f/name)
federatedIdentityCredentials/any (f：f/subject)
identifierUris/any(p:p)
info/logoUrl
info/termsOfServiceUrl
notes
publicClient/redirectUris/any(p:p)
publisherDomain
requiredResourceAccess/any(r:r/resourceAppId)
serviceManagementReference
signInAudience
spa/redirectUris/any(p:p)
tags/any(p:p)
唯一名称
verifiedPublisher/displayName
web/homePageUrl
web/redirectUris/any(p:p)

应用程序实体的以下属性支持 $count 筛选器表达式中的集合。

属性	eq 计数 0	eq 计数 1
extensionProperties/$count
federatedIdentityCredentials/$count

协定属性

属性	eq	startsWith
customerId
defaultDomainName
displayName

设备属性

属性	eq	startsWith	ge/le	eq Null
accountEnabled
alternativeSecurityIds/any(a:a/identityProvider)
alternativeSecurityIds/any(a:a/type)
approximateLastSignInDateTime
deviceCategory
deviceId
deviceOwnership
displayName
enrollmentProfileName
extensionAttributes/extensionAttribute1-15
hostnames/any(p:p)
isCompliant
isManaged
isRooted
managementType
manufacturer
mdmAppId
model
onPremisesLastSyncDateTime
onPremisesSecurityIdentifier
onPremisesSyncEnabled
operatingSystem
operatingSystemVersion
physicalIds/any(p:p)
profileType
registrationDateTime
trustType

设备实体的以下属性支持$count筛选器表达式中的集合。

属性	eq 计数 0	eq 计数 1
physicalIds/$count
systemLabels/$count

目录角色属性

属性	eq	startsWith	eq Null
description
displayName
roleTemplateId

组属性

属性	eq	startsWith	ge/le	eq Null
assignedLicenses/any (a：a/skuId)
classification
createdByAppId
createdDateTime
description
displayName
expirationDateTime
groupTypes/any (p：p)
hasMembersWithLicenseErrors
infoCatalogs/any(p:p)
isAssignableToRole
mail
mailEnabled
mailNickname
membershipRule
membershipRuleProcessingState
onPremisesLastSyncDateTime
onPremisesProvisioningErrors/any(o:o/category)
onPremisesProvisioningErrors/any(o:o/propertyCausingError)
onPremisesSamAccountName
onPremisesSecurityIdentifier
onPremisesSyncEnabled
preferredLanguage
proxyAddresses/any(p:p)
renewedDateTime
resourceBehaviorOptions/any(p:p)
resourceProvisioningOptions/any(p:p)
securityEnabled
唯一名称

组实体的以下属性支持$count筛选器表达式中的集合。

属性	eq 计数 0	eq 计数 1
assignedLicenses/$count
onPremisesProvisioningErrors/$count
proxyAddresses/$count

组织联系人属性

属性	eq	startsWith	ge/le	eq Null
CompanyName
department
displayName
givenName
jobTitle
mail
mailNickname
manager/id
onPremisesLastSyncDateTime
onPremisesProvisioningErrors/any(o:o/category)
onPremisesProvisioningErrors/any(o:o/propertyCausingError)
onPremisesSyncEnabled
proxyAddresses/any(p:p)
surname

orgContact 实体的以下属性支持$count筛选器表达式中的集合。

属性	eq 计数 0	eq 计数 1
onPremisesProvisioningErrors/$count
proxyAddresses/$count

服务主体属性

属性	eq	startsWith	ge/le	eq Null
accountEnabled
alternativeNames/any (p：p)
appId
appOwnerOrganizationId
appRoleAssignmentRequired
applicationTemplateId
claimsPolicy/id
createdObjects/any(c:c/id)
description
displayName
federatedIdentityCredentials/any (f：f/issuer)
federatedIdentityCredentials/any (f：f/name)
federatedIdentityCredentials/any (f：f/subject)
homepage
info/logoUrl
info/termsOfServiceUrl
notes
preferredSingleSignOnMode
preferredTokenSigningKeyEndDateTime
publisherName
remoteDesktopSecurityConfiguration/id
servicePrincipalNames/any (p：p)
servicePrincipalType
tags/any(p:p)
verifiedPublisher/displayName

servicePrincipal 实体的以下属性支持$count筛选器表达式中的集合。

属性	eq 计数 0	eq 计数 1
federatedIdentityCredentials/$count

用户属性

属性	eq	startsWith	ge/le	eq Null
accountEnabled
ageGroup
assignedLicenses/any (a：a/skuId)
assignedPlans/any(a:a/capabilityStatus)
assignedPlans/any(a:a/service)
assignedPlans/any(a:a/servicePlanId)
authorizationInfo/certificateUserIds/any (p：p)
businessPhones/any (p：p)
城市
cloudRealtimeCommunicationInfo/isSipEnabled
CompanyName
consentProvidedForMinor
country
createdDateTime
createdObjects/any(c:c/id)
creationType
department
displayName
employeeHireDate
employeeId
employeeOrgData/costCenter
employeeOrgData/division
employeeType
externalUserState
faxNumber
givenName
identities/any(i:i/issuer)
imAddresses/any (p：p)
infoCatalogs/any(p:p)
isLicenseReconciliationNeeded
isResourceAccount
jobTitle
mail
mailNickname
mobilePhone
officeLocation
onPremisesDistinguishedName
onPremisesExtensionAttributes/extensionAttribute1-15
onPremisesImmutableId
onPremisesLastSyncDateTime
onPremisesProvisioningErrors/any(o:o/category)
onPremisesProvisioningErrors/any(o:o/propertyCausingError)
onPremisesSamAccountName
onPremisesSecurityIdentifier
onPremisesSipInfo/isSipEnabled
onPremisesSyncEnabled
otherMails/any (p：p)
passwordPolicies
passwordProfile/forceChangePasswordNextSignIn
passwordProfile/forceChangePasswordNextSignInWithMfa
postalCode
preferredLanguage
provisionedPlans/any(p:p/provisioningStatus)
provisionedPlans/any(p:p/service)
proxyAddresses/any(p:p)
state
streetAddress
surname
usageLocation
userPrincipalName
userType

以下用户实体属性支持$count筛选器表达式中的集合。

属性	eq 计数 0	eq 计数 1
assignedLicenses/$count
onPremisesProvisioningErrors/$count
otherMails/$count
ownedObjects/$count
proxyAddresses/$count

下表显示了用户对象上其他扩展属性对的支持$filter。

扩展类型	eq	startsWith	eq null
架构扩展
开放扩展
目录扩展

支持按Microsoft Entra ID (目录) 对象的属性排序

下表汇总了对 $orderby 目录对象的按属性的支持，并指示通过高级查询功能支持排序的位置。

图例

运算符 $orderby 默认适用于该属性。
运算符$orderby需要高级查询参数，这些参数包括：
- ConsistencyLevel=eventual 标头
- $count=true 查询字符串
在同一 $filter 查询中对目录对象使用和 $orderby 始终需要高级查询参数。有关详细信息，请参阅需要高级查询功能的查询方案。

目录对象	属性名称	$orderby
administrativeUnit	createdDateTime
administrativeUnit	deletedDateTime
administrativeUnit	displayName
应用程序	createdDateTime
应用程序	deletedDateTime
应用程序	displayName
orgContact	createdDateTime
orgContact	displayName
设备	approximateLastSignInDateTime
设备	createdDateTime
设备	deletedDateTime
设备	displayName
组	createdDateTime
组	deletedDateTime
组	displayName
servicePrincipal	createdDateTime
servicePrincipal	deletedDateTime
servicePrincipal	displayName
用户	createdDateTime
用户	deletedDateTime
用户	displayName
用户	userPrincipalName
[所有其他]	[所有其他]

针对目录对象的高级查询的错误处理

以下部分提供了不在需要时使用高级查询参数时的常见错误方案示例。

只能使用高级查询参数对目录对象进行计数。如果未指定ConsistencyLevel=eventual标头，则使用 $count URL 段 () /$count 时，请求将返回错误，或者如果使用查询参数 (?$count=true) ，请求将返回$count错误。

GET https://graph.microsoft.com/v1.0/users/$count


// 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();


const options = {
	authProvider,
};

const client = Client.init(options);

let int32 = await client.api('/users/$count')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$graphServiceClient->users()->count()->get()->wait();


Import-Module Microsoft.Graph.Users

Get-MgUserCount


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

await graph_client.users.count.get()

{
    "error": {
        "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"
        }
    }
}

对于目录对象， $search 仅适用于高级查询。如果未指定 ConsistencyLevel 标头，请求将返回错误。

GET https://graph.microsoft.com/v1.0/applications?$search="displayName:Browser"


// 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.Applications.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Search = "\"displayName:Browser\"";
});



// 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"
	  graphapplications "github.com/microsoftgraph/msgraph-sdk-go/applications"
	  //other-imports
)


requestSearch := "\"displayName:Browser\""

requestParameters := &graphapplications.ApplicationsRequestBuilderGetQueryParameters{
	Search: &requestSearch,
}
configuration := &graphapplications.ApplicationsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
applications, err := graphClient.Applications().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ApplicationCollectionResponse result = graphClient.applications().get(requestConfiguration -> {
	requestConfiguration.queryParameters.search = "\"displayName:Browser\"";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let applications = await client.api('/applications')
	.search('displayName:Browser')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Applications\ApplicationsRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new ApplicationsRequestBuilderGetRequestConfiguration();
$queryParameters = ApplicationsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->search = "\"displayName:Browser\"";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->applications()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Applications

Get-MgApplication -Search '"displayName:Browser"'


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.applications.applications_request_builder import ApplicationsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = ApplicationsRequestBuilder.ApplicationsRequestBuilderGetQueryParameters(
		search = "\"displayName:Browser\"",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.applications.get(request_configuration = request_configuration)

{
    "error": {
        "code": "Request_UnsupportedQuery",
        "message": "Request with $search query parameter only works through MSGraph with a special request header: 'ConsistencyLevel: eventual'",
        "innerError": {
            "date": "2021-05-27T14:26:47",
            "request-id": "9b600954-ba11-4899-8ce9-6abad341f299",
            "client-request-id": "7964ef27-13a3-6ca4-ed7b-73c271110867"
        }
    }
}

如果 URL 中的属性或查询参数仅支持高级查询，但缺少 ConsistencyLevel 标头或 $count=true 查询字符串，则请求将返回错误。

GET https://graph.microsoft.com/beta/users?$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')


// 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 = "endsWith(userPrincipalName,'";
});



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
	  //other-imports
)


requestFilter := "endsWith(userPrincipalName,'"

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 = "endsWith(userPrincipalName,'";
});

Snippet not available


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "endsWith(userPrincipalName,'";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Beta.Users

Get-MgBetaUser -Filter "endsWith(userPrincipalName,'"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "endsWith(userPrincipalName,'",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

{
    "error": {
        "code": "Request_UnsupportedQuery",
        "message": "Operator 'endsWith' is not supported because the required parameters might be missing. Try adding $count=true query parameter and ConsistencyLevel:eventual header. Refer to https://aka.ms/graph-docs/advanced-queries for more information",
        "innerError": {
            "date": "2023-07-14T08:43:39",
            "request-id": "b3731da7-5c46-4c37-a8e5-b190124d2531",
            "client-request-id": "a1556ddf-4794-929d-0105-b753a78b4c68"
        }
    }
}

如果未为属性编制索引以支持查询参数，则即使指定了高级查询参数，请求也会返回错误。例如，不会为组资源的 createdDateTime 属性编制查询功能的索引。

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");
});


const options = {
	authProvider,
};

const client = Client.init(options);

let groups = await client.api('/groups')
	.version('beta')
	.header('ConsistencyLevel','eventual')
	.filter('createdDateTime ge 2021-11-01')
	.get();


<?php
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();


Import-Module Microsoft.Graph.Beta.Groups

Get-MgBetaGroup -Filter "createdDateTime ge 2021-11-01" -CountVariable CountVar  -ConsistencyLevel eventual


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.groups.groups_request_builder import GroupsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
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"
        }
    }
}

但是，包含查询参数的请求可能会以无提示方式失败。例如，对于不支持的查询参数和不支持的查询参数组合，请求可能会失败。在这些情况下，请检查请求返回的数据，以确定指定的查询参数是否具有所需的效果。例如，在下面的示例中，即使查询成功， @odata.count 参数也缺失。

GET https://graph.microsoft.com/v1.0/users?$count=true


// 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;
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.get();


<?php
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();


Import-Module Microsoft.Graph.Users

Get-MgUser -CountVariable CountVar


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		count = True,
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "value":[
    {
      "displayName":"Oscar Ward",
      "mail":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"
    }
  ]
}

反馈

此页面是否有帮助？

Last updated on 2025-08-29