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

  • 项目

随着Microsoft Entra在稳定性、可用性和性能方面不断提供更多的功能和改进，Microsoft Graph 也会不断发展和缩放，以有效地访问数据。 一种方法是通过 Microsoft Graph 对各种Microsoft Entra ID对象（也称为目录对象及其属性）的高级查询功能的支持不断增加。 例如，在 $filter 查询参数上添加 not (not)，不等于 (ne)，以 (endsWith) 运算符结尾。

Microsoft Graph 查询引擎使用索引存储来满足查询请求。 为了添加对某些属性的其他查询功能的支持，这些属性现在在单独的存储中编制索引。 这种单独的索引使Microsoft Entra ID能够增加对查询请求的支持并提高性能。 但是，默认情况下，这些高级查询功能不可用，但请求者还必须将 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 (目录) 支持高级查询功能的对象

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

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

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

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

    说明 示例
    使用 $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仅通过邮件、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需要高级查询参数，这些参数包括：
      • ConsistencyLevel=eventual 标头
      • $count=true 查询字符串
    • 不支持。 该 $filter 属性不支持 运算符。 向我们发送反馈 ，请求此属性支持 $filter 方案。
    • 空白单元格指示查询对该属性无效。
    • 列 null 值 指示该属性可为 null 且可使用 null筛选。
    • 此处未列出的属性根本不支持 $filter 。

    管理单元属性

    属性 eq startsWith eq Null
    说明
    displayName
    isMemberManagementRestricted
    membershipRule
    membershipRuleProcessingState
    scopedRoleMembers/any (s：s/id)

    应用程序属性

    属性 eq startsWith ge/le eq Null
    appId
    createdDateTime
    createdOnBehalfOf/id
    说明
    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
    说明
    displayName
    roleTemplateId

    组属性

    属性 eq startsWith ge/le eq Null
    appRoleAssignments/any (a：a/id)
    assignedLicenses/any (a：a/skuId)
    classification
    createdByAppId
    createdOnBehalfOf/id
    说明
    displayName
    expirationDateTime
    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
    settings/any (s：s/displayName)
    settings/any (s：s/id)
    唯一名称

    组实体的以下属性支持$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
    appRoleAssignedTo/any (a：a/id)
    appRoleAssignmentRequired
    appRoleAssignments/any (a：a/id)
    applicationTemplateId
    createdObjects/any(c:c/id)
    delegatedPermissionClassifications/any (d：d/id)
    说明
    displayName
    federatedIdentityCredentials/any (f：f/issuer)
    federatedIdentityCredentials/any (f：f/name)
    federatedIdentityCredentials/any (f：f/subject)
    homepage
    info/logoUrl
    info/termsOfServiceUrl
    notes
    oauth2PermissionGrants/任何 (o：o/id)
    preferredSingleSignOnMode
    preferredTokenSigningKeyEndDateTime
    publisherName
    remoteDesktopSecurityConfiguration/id
    remoteDesktopSecurityConfiguration/targetDeviceGroups/any (t：t/displayName)
    remoteDesktopSecurityConfiguration/targetDeviceGroups/any (t：t/id)
    servicePrincipalNames/any (p：p)
    servicePrincipalType
    tags/any(p:p)
    verifiedPublisher/displayName

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

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

    用户属性

    属性 eq startsWith ge/le eq Null
    accountEnabled
    ageGroup
    appRoleAssignments/any (a：a/id)
    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
    licenseDetails/any (l：l/id)
    mail
    mailNickname
    manager/id
    mobilePhone
    oauth2PermissionGrants/任何 (o：o/id)
    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)
    scopedRoleMemberOf/any (s：s/id)
    showInAddressList
    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
    组 deletedDateTime
    组 displayName
    servicePrincipal createdDateTime
    servicePrincipal deletedDateTime
    servicePrincipal displayName
    用户 createdDateTime
    用户 deletedDateTime
    用户 displayName
    用户 userPrincipalName
    [所有其他] [所有其他]

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

    仅支持使用高级查询参数对目录对象进行计数。 ConsistencyLevel=eventual如果未指定标头，则使用 URL 段时$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"
        }
    }
}

    如果尚未为某个属性编制索引以支持查询参数，即使指定了高级查询参数，请求也会返回错误。

    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"
    }
  ]
}

    相关内容