随着 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一同使用。 默认情况下,此请求将起作用,即请求不需要高级查询参数。HTTP
GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled eq falseC#
// See https://docs.microsoft.com/graph/sdks/create-client?tabs=CS var user = await graphClient.Users.Request() .Filter("accountEnabled eq false") .GetAsync();JavaScript
// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Javascript let users = await client.api('/users') .filter('accountEnabled eq false') .get();Objective-C
// 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];Java
// See https://docs.microsoft.com/en-us/graph/sdks/create-client?tabs=Java UserCollectionPage users = graphClient.users() .buildRequest() .filter("accountEnabled eq false") .get();Go
// 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)PowerShell
Import-Module Microsoft.Graph.Users Get-MgUser -Filter "accountEnabled eq false"
-
选项 2:将
$filter查询参数与 运算符ne一同使用。 默认情况下不支持此请求,因为仅在高级查询中支持ne运算符。 因此,必须将 ConsistencyLevel 标头设置为eventual并 使用$count=true查询字符串。HTTP
GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled ne true&$count=true ConsistencyLevel: eventualC#
// 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();JavaScript
// 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();Objective-C
// 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];Java
// 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();Go
// 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)PowerShell
Import-Module Microsoft.Graph.Users Get-MgUser -Filter "accountEnabled ne true" -CountVariable CountVar -ConsistencyLevel eventual
这些高级查询功能仅在Azure AD目录对象及其关系(包括以下常用对象)上受支持:
| Object | 关系 |
|---|---|
| administrativeUnit | <li>members |
| application | <li>所有者 |
| appRoleAssignment | - |
| 设备 | <li>memberOf <li>transitiveMemberOf <li>registeredUsers <li>registeredOwners |
| group | <li>members <li>transitiveMembers <li>memberOf <li>transitiveMemberOf <li>所有者 <li>appRoleAssignments |
| oAuth2PermissionGrant(委派的权限授予) | - |
| orgContact | <li>memberOf <li>transitiveMemberOf |
| servicePrincipal | <li>memberOf <li>transitiveMemberOf <li>appRoleAssignments <li>appRoleAssignmentsTo <li>oAuth2PermissionGrant |
| user | <li>memberOf <li>transitiveMemberOf<li>ownedObjects <li>registeredDevices <li>ownedDevices <li>transitiveManagers <li>directReports <li>transitiveReports <li>appRoleAssignments <li>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 |
Note:
- 仅高级查询支持将
$filter和$orderBy结合使用。- 高级查询当前不支持
$expand。- 高级查询功能目前不适用于Azure AD B2C租户。
- 若要在 批处理请求 中使用高级查询功能,请在
POST请求的 JSON 正文中指定 ConsistencyLevel 标头。
支持筛选 Azure AD 目录对象的属性
目录对象的属性对查询参数的支持行为各不相同。 以下是目录对象的常见应用场景:
- 默认情况下支持的查询也适用于高级查询,但响应最终会保持一致。
- 默认情况下,只要默认支持
eq运算符,则默认支持in运算符。 - 仅对 mail、otherMails、userPrincipalName 和 proxyAddresses 属性的高级查询支持
endsWith运算符。 - 仅高级查询支持
not和ne求反运算符。- 支持
eq运算符的所有属性也支持ne或not运算符。 - 对于使用
anylambda 运算符的查询,请使用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 | 默认支持 | 不支持 | |||
| 默认支持 | 默认支持 | 需要高级查询参数。 | |||
| 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 | 默认支持 | 默认支持 | 需要高级查询参数。 | ||
| 默认支持 | 默认支持 | 需要高级查询参数。 | |||
| 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 | 默认支持 | 默认支持 | 需要高级查询参数。 | ||
| 默认支持 | 默认支持 | 需要高级查询参数。 | |||
| 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"
},
]
}
另请参阅
历史资料。此文对应 2023-02-03 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 Licantrop0)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
