使用英语阅读

通过


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

Microsoft Graph 支持对各种Microsoft Entra ID对象(也称为目录对象)的高级查询功能,以帮助有效地访问数据。 例如,在 $filter 查询参数上添加 not (not),不等于 (ne), (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

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

GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled ne true&$count=true
ConsistencyLevel: eventual

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

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

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

下表列出了仅在高级查询中支持的目录对象的查询方案:

说明 示例
使用 $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
$filterendsWith 运算符结合使用 GET~/users?$count=true&$filter=endsWith(mail,'@outlook.com')
在同一查询中使用$filter$orderby GET../applications?$orderby=displayName&$filter=startsWith(displayName, 'Box')&$count=true
对特定属性将 $filterstartsWith 运算符结合使用. GET~/users?$filter=startsWith(mobilePhone, '25478') OR startsWith(mobilePhone, '25473')&$count=true
$filternenot 运算符结合使用 GET~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true
$filternotstartsWith 运算符结合使用 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仅高级查询参数支持运算符,并且仅受 mailotherMailsuserPrincipalNameproxyAddresses 属性的支持
  • 获取空集合 (/$count eq 0/$count ne 0) 和对象少于 (/$count eq 1的集合, /$count ne 1) 仅支持高级查询参数。
  • notne 求反运算符仅支持高级查询参数。
    • 支持 eq 运算符的所有属性也支持 nenot 运算符。
    • 对于使用 any lambda 运算符的查询,请使用 not 运算符。 请参阅使用 lambda 运算符的筛选器

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

图例

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

管理单元属性

属性 eq startsWith eq Null
description 高级 高级 高级
displayName Default+Advanced Default+Advanced 高级
isMemberManagementRestricted Default+Advanced
membershipRule Default+Advanced Default+Advanced
membershipRuleProcessingState Default+Advanced

应用程序属性

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

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

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

协定属性

属性 eq startsWith
customerId Default+Advanced
defaultDomainName Default+Advanced Default+Advanced
displayName Default+Advanced Default+Advanced

设备属性

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

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

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

目录角色属性

属性 eq startsWith eq Null
description 高级 高级 高级
displayName Default+Advanced 高级 高级
roleTemplateId Default+Advanced NotSupported

组属性

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

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

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

组织联系人属性

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

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

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

服务主体属性

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

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

属性 eq 计数 0 eq 计数 1
federatedIdentityCredentials/$count 高级 NotSupported

用户属性

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

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

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

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

扩展类型 eq startsWith eq null
架构扩展 高级 高级 高级
开放扩展 NotSupported NotSupported NotSupported
目录扩展 Default+Advanced 高级 高级

支持按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 默认
[所有其他] [所有其他] NotSupported

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

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

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

GET https://graph.microsoft.com/v1.0/users/$count
{
    "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"
{
    "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')
{
    "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
{
    "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
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"
    }
  ]
}