Azure AD 目录对象的高级查询功能

项目
07/18/2022

随着 Azure AD 在稳定性、可用性和性能方面不断提供更多功能和改进，Microsoft Graph 也在不断改进和扩展以便高效访问数据。一个途径是 Microsoft Graph 对各种 Azure AD 对象及其属性的高级查询功能加强支持。例如，在 $filter 查询参数上添加 not (not)，不等于 (ne)，以 (endsWith) 运算符结尾。

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

例如，要仅检索非活动用户帐户，你可以运行使用 $filter 查询参数的查询之一。

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

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

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=CS
var user = await graphClient.Users.Request()
    .Filter("accountEnabled eq false")
    .GetAsync();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Javascript
let users = await client.api('/users')
  .filter('accountEnabled eq false')
  .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Objective-C
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users?$filter=accountEnabled eq false"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *usersDataTask = [httpClient dataTaskWithRequest:urlRequest
completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

  NSError *jsonError = nil;
  MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
  MSGraphUser *user = [[MSGraphUser alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[usersDataTask execute];

// See https://docs.microsoft.com/en-us/graph/sdks/create-client?tabs=Java
UserCollectionPage users = graphClient.users()
    .buildRequest()
    .filter("accountEnabled eq false")
    .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Go
requestParameters := &msgraphsdk.UsersRequestBuilderGetQueryParameters{
    Filter: "accountEnabled eq false",
}

options := &msgraphsdk.UsersRequestBuilderGetOptions{
    Q: requestParameters,
}

result, err := client.Users().Get(options)

Import-Module Microsoft.Graph.Users

Get-MgUser -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

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=CS
var user = await graphClient.Users.Request()
    .Request(new Option[] { new QueryOption("$count", "true")})
    .Header("ConsistencyLevel", "eventual")
    .Filter("accountEnabled ne true")
    .GetAsync();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Javascript
let users = await client.api('/users')
  .header('ConsistencyLevel','eventual')
  .filter('accountEnabled ne true')
  .count(true)
  .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Objective-C
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users?$filter=accountEnabled ne true&$count=true"]]];
[urlRequest setHTTPMethod:@"GET"];
[urlRequest setValue:@"eventual" forHTTPHeaderField:@"ConsistencyLevel"];

MSURLSessionDataTask *usersDataTask = [httpClient dataTaskWithRequest:urlRequest
completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

  NSError *jsonError = nil;
  MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
  MSGraphUser *user = [[MSGraphUser alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[usersDataTask execute];

// See https://docs.microsoft.com/en-us/graph/sdks/create-client?tabs=Java
LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("ConsistencyLevel", "eventual"));
requestOptions.add(new QueryOption("$count", "true"))

UserCollectionPage users = graphClient.users()
    .buildRequest(requestOptions)
    .filter("accountEnabled ne true")
    .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Go
requestParameters := &msgraphsdk.UsersRequestBuilderGetQueryParameters{
    Filter: "accountEnabled ne true",
    Count: true,
}

headers := map[string]string{
    "ConsistencyLevel": "eventual"
}

options := &msgraphsdk.UsersRequestBuilderGetOptions{
    Q: requestParameters,
    H: headers,
}

result, err := client.Users().Get(options)

Import-Module Microsoft.Graph.Users

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

这些高级查询功能仅在Azure AD目录对象及其关系（包括以下常用对象）上受支持：

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,+'OnMicrosoft.com'))&select=id,displayName,proxyaddresses`
将 OData 强制转换与可传递成员列表配合使用	GET `../me/transitiveMemberOf/microsoft.graph.group?$count=true`

备注

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

支持筛选 Azure AD 目录对象的属性

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

默认情况下支持的查询也适用于高级查询，但响应最终会保持一致。
默认情况下，只要默认支持eq运算符，则默认支持in运算符。
仅对 mail、otherMails、userPrincipalName 和 proxyAddresses 属性的高级查询支持 endsWith 运算符。
仅高级查询支持 not 和 ne 求反运算符。
- 支持 eq 运算符的所有属性也支持 ne 或 not 运算符。
- 对于使用 any lambda 运算符的查询，请使用 not 运算符。请参阅使用 lambda 运算符的筛选器。

下表汇总了对高级 $filter 查询功能支持的目录对象属性的操作器的支持。

图例

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

管理单元属性

属性名	eq	startsWith	ge	le	Null 值
说明
displayName
isMemberManagementRestricted

应用程序属性

属性名	eq	startsWith	ge	le	Null 值
appId
createdDateTime
createdOnBehalfOf/deletedDateTime
createdOnBehalfOf/id
说明
disabledByMicrosoftStatus
displayName
identifierUris/any(p:p)
info/logoUrl
info/termsOfServiceUrl
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)

设备属性

属性名	eq	startsWith	ge	le	Null 值
accountEnabled
alternativeSecurityIds/any(a:a/identityProvider)
alternativeSecurityIds/any(a:a/type)
approximateLastSignInDateTime
deviceId
displayName
extensionAttributes1-15
hostnames/any(p:p)
isCompliant
isManaged
mdmAppId
onPremisesLastSyncDateTime
onPremisesSyncEnabled
operatingSystem
operatingSystemVersion
physicalIds/any(p:p)
registrationDateTime

组属性

属性名	eq	startsWith	ge	le	Null 值
assignedLicenses/any(a:a/skuId)
classification
createdByAppId
createdOnBehalfOf/deletedDateTime
createdOnBehalfOf/id
说明
displayName
expirationDateTime
hasMembersWithLicenseErrors
infoCatalogs/any(p:p)
isAssignableToRole
mail
mailEnabled
mailNickname
membershipRule
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

组织联系人属性

属性名	eq	startsWith	ge	le	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

服务主体属性

属性名	eq	startsWith	ge	le	Null 值
accountEnabled
alternativeNames/any (p：p)
appId
appOwnerOrganizationId
appRoleAssignmentRequired
applicationTemplateId
createdObjects/any(c:c/id)
说明
displayName
homepage
info/logoUrl
info/termsOfServiceUrl
preferredTokenSigningKeyEndDateTime
publisherName
servicePrincipalNames/any (p：p)
tags/any(p:p)

用户属性

属性名	eq	startsWith	ge	le	Null 值
accountEnabled
ageGroup
assignedLicenses/any (a：a/skuId)
assignedPlans/any(a:a/capabilityStatus)
assignedPlans/any(a:a/service)
assignedPlans/any(a:a/servicePlanId)
businessPhones/any (p：p)
城市
CompanyName
consentProvidedForMinor
country
createdDateTime
createdObjects/any(c:c/id)
creationType
部门
displayName
employeeHireDate
employeeId
employeeOrgData/costCenter
employeeOrgData/division
employeeType
externalUserState
faxNumber
givenName
identities/any(i:i/issuer)
imAddresses/any (p：p)
infoCatalogs/any(p:p)
isResourceAccount
jobTitle
mail
mailNickname
manager/deletedDateTime
manager/id
mobilePhone
officeLocation
onPremisesExtensionAttributes/extensionAttribute1-15
onPremisesImmutableId
onPremisesLastSyncDateTime
onPremisesProvisioningErrors/any(o:o/category)
onPremisesProvisioningErrors/any(o:o/propertyCausingError)
onPremisesSamAccountName
onPremisesSecurityIdentifier
onPremisesSyncEnabled
onPremisesUserPrincipalName
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)
showInAddressList
state
streetAddress
surname
usageLocation
userPrincipalName
userType

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

仅支持使用高级查询参数对目录对象进行计数。如果未指定 ConsistencyLevel=eventual 标头，则当 $count URL 段被使用时，请求将返回错误；如果使用了 $count 查询参数 (?$count=true)，则会无提示地忽略该参数。

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 标头，则请求将返回错误。

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 查询字符串，则请求将返回错误。

https://graph.microsoft.com/v1.0/users?$filter=endsWith(mail,'@outlook.com')

{
    "error": {
        "code": "Request_UnsupportedQuery",
        "message": "Unsupported Query.",
        "innerError": {
            "date": "2021-05-18T19:12:36",
            "request-id": "63f2093c-399c-4350-9609-3ce9b62abe3c",
            "client-request-id": "e60ed0ba-df5d-e190-f056-f9c0318456d7"
        }
    }
}

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

https://graph.microsoft.com/beta/groups?$filter=createdDateTime ge 2021-11-01&$count=true
ConsistencyLevel: eventual

{
    "error": {
        "code": "Request_UnsupportedQuery",
        "message": "The request uses a filter property that is not indexed",
        "innerError": {
            "date": "2021-06-10T19:32:01",
            "request-id": "5625ba13-0c9f-4fce-a853-4b52f3e0bd09",
            "client-request-id": "76fe4cd8-df3a-f8c3-659b-594274b6bb31"
        }
    }
}

但是，值得注意的是请求中指定的查询参数可能会自行失败。不支持的查询参数以及不支持的查询参数组合的情况就是如此。在这些情况下，应检查请求返回的数据，以确定指定的查询参数是否具有所需的效果。例如，在下面的示例中，即使查询成功， @odata.count 参数也缺失。

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