相关文章推荐
小百科  ›  Azure AD 对象上的高级查询功能 - Microsoft Graph | Microsoft Learn
关系运算符
礼貌的鸡蛋
1 年前

随着 Azure Active Directory (Azure AD) 继续在稳定性、可用性和性能方面提供更多功能和改进，Microsoft Graph 也会不断改进和缩放，以有效地访问数据。 一种方法是通过 Microsoft Graph 对各种 Azure Active Directory (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

选项 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 Graph 对象


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

Object
servicePrincipal

  • memberOf 
  • transitiveMemberOf 
  • appRoleAssignments 
  • appRoleAssignmentsTo 
  • oAuth2PermissionGrant
    • 

  • memberOf 
  • transitiveMemberOf
  • ownedObjects 
  • registeredDevices 
  • ownedDevices 
  • transitiveManagers 
  • directReports 
  • transitiveReports 
  • appRoleAssignments 
  • oAuth2PermissionGrant
    • 

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

    下表列出了仅在高级查询中支持的目录对象的查询方案：
    
将 $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

  • 高级查询当前不支持$expand。
    • 

  • 高级查询功能目前不适用于Azure AD B2C租户。
    • 

  • 若要在 批处理请求 中使用高级查询功能，请在 POST 请求的 JSON 正文中指定 ConsistencyLevel 标头。
    • 

    支持按 Azure AD (目录) 对象的属性进行筛选
    

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

  • 默认情况下支持的查询也适用于高级查询参数，但响应最终会一致。
    • 

  • 默认情况下，只要默认支持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 运算符的支持，并指示通过高级查询功能支持查询的位置。
    

    Legend
    

  • 默认情况下有效。不需要高级查询参数。 运算符 $filter 默认适用于该属性。
    • 

  • 需要高级查询参数。运算符$filter需要高级查询参数，这些参数包括：
      

    • ConsistencyLevel=eventual 标头
      • 

    • $count=true 查询字符串
      • 

    • 不支持。 该 $filter 属性不支持 运算符。 向我们发送反馈 ，请求此属性支持 $filter 方案。
      • 

    • 空白单元格指示查询对该属性无效。
      • 

    • 列 null 值 指示该属性可为 null 且可使用 null筛选。
      • 

    • 此处未列出的属性完全不支持 $filter。
      • 

      管理单元属性
      
startsWith
eq Null
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
int int32 = graphClient.users().count()
	.buildRequest()
	.get();
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$graphServiceClient->users()->count()->get();
        "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 标头，则请求将返回错误。
      
JavaScript
PowerShell
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Applications.GetAsync((requestConfiguration) =>
	requestConfiguration.QueryParameters.Search = "\"displayName:Browser\"";
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/applications"
	  //other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestSearch := "\"displayName:Browser\""
requestParameters := &graphconfig.ApplicationsRequestBuilderGetQueryParameters{
	Search: &requestSearch,
configuration := &graphconfig.ApplicationsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
result, err := graphClient.Applications().Get(context.Background(), configuration)
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new QueryOption("$search", "\"displayName:Browser\""));
ApplicationCollectionPage applications = graphClient.applications()
	.buildRequest( requestOptions )
	.get();
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new ApplicationsRequestBuilderGetRequestConfiguration();
$queryParameters = ApplicationsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->search = "\"displayName:Browser\"";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->applications()->get($requestConfiguration);
    "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 查询字符串，则请求将返回错误。
      
JavaScript
PowerShell
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
	requestConfiguration.QueryParameters.Filter = "endsWith(mail,'@outlook.com')";
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFilter := "endsWith(mail,'@outlook.com')"
requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
result, err := graphClient.Users().Get(context.Background(), configuration)
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
UserCollectionPage users = graphClient.users()
	.buildRequest()
	.filter("endsWith(mail,'@outlook.com')")
	.get();
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "endsWith(mail,'@outlook.com')";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration);
        "innerError": {
            "date": "2021-05-18T19:12:36",
            "request-id": "63f2093c-399c-4350-9609-3ce9b62abe3c",
            "client-request-id": "e60ed0ba-df5d-e190-f056-f9c0318456d7"

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

      GET https://graph.microsoft.com/beta/groups?$filter=createdDateTime ge 2021-11-01&$count=true
ConsistencyLevel: eventual
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Groups.GetAsync((requestConfiguration) =>
	requestConfiguration.QueryParameters.Filter = "createdDateTime ge 2021-11-01";
	requestConfiguration.QueryParameters.Count = true;
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-beta-sdk-go/groups"
	  //other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")
requestFilter := "createdDateTime ge 2021-11-01"
requestCount := true
requestParameters := &graphconfig.GroupsRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Count: &requestCount,
configuration := &graphconfig.GroupsRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
result, err := graphClient.Groups().Get(context.Background(), configuration)
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("ConsistencyLevel", "eventual"));
GroupCollectionPage groups = graphClient.groups()
	.buildRequest( requestOptions )
	.filter("createdDateTime ge 2021-11-01")
	.get();
let groups = await client.api('/groups')
	.version('beta')
	.header('ConsistencyLevel','eventual')
	.filter('createdDateTime ge 2021-11-01')
	.get();
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$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);
    "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 参数也缺失。
      
JavaScript
PowerShell
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
	requestConfiguration.QueryParameters.Count = true;
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestCount := true
requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
	Count: &requestCount,
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
result, err := graphClient.Users().Get(context.Background(), configuration)
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
UserCollectionPage users = graphClient.users()
	.buildRequest()
	.get();
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration);
      "displayName":"Oscar Ward",
      "mail":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"

    • 使用查询参数自定义响应
      • 

    • 查询参数限制
      • 

    • 使用$search查询参数匹配搜索条件
      • 

    • 使用 .NET SDK 探索 Azure AD 对象的高级查询功能
      •
    •  
    推荐文章
    今天看啥   ·   Py中国   ·   codingpro   ·   小百科   ·   link之家   ·   卧龙AI搜索
    删除内容请联系邮箱 2879853325@qq.com
    小百科 - 百科知识指南
    © 2024 ~ 沪ICP备11025650号