Расширенные возможности запросов к объектам Microsoft Entra ID
Статья
По мере того как Microsoft Entra продолжает предоставлять больше возможностей и улучшений в области стабильности, доступности и производительности, Microsoft Graph также продолжает развиваться и масштабироваться для эффективного доступа к данным. Один из способов заключается в растущей поддержке Microsoft Graph расширенных возможностей запросов к различным объектам Microsoft Entra ID, также называемым объектами каталогов, и их свойствам. Например, добавление не (not ), не равно (ne), и заканчивается (endsWith) операторами в параметре $filter запроса.
Механизм запросов 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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "accountEnabled eq false";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "accountEnabled eq false";
});
Вариант 2.$filter Используйте параметр запроса с оператором ne . Этот запрос не поддерживается по умолчанию, так как ne оператор поддерживается только в расширенных запросах. Поэтому необходимо добавить заголовок eventualConsistencyLevel в значение и использовать $count=true строку запроса.
GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled ne true&$count=true
ConsistencyLevel: eventual
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "accountEnabled ne true";
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "accountEnabled ne true";
requestConfiguration.queryParameters.count = true;
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
Совместное использование $filter и $orderby поддерживается только в расширенных запросах.
$expand в настоящее время не поддерживается в расширенных запросах.
Расширенные возможности запросов в настоящее время недоступны для клиентов Azure AD B2C.
Чтобы использовать расширенные возможности запросов в пакетных запросах, укажите заголовок ConsistencyLevel в теле запроса JSON POST.
Поддержка фильтрации по свойствам объектов Microsoft Entra ID (каталогов)
Свойства объектов каталога ведут себя по-разному в отношении поддержки параметров запросов. Ниже приведены распространенные сценарии для объектов каталога:
Запросы, поддерживаемые по умолчанию, также будут работать с расширенными параметрами запроса, но ответ в конечном итоге будет согласован.
Оператор in поддерживается по умолчанию, когда eq оператор поддерживается по умолчанию.
Оператор endsWith поддерживается только с расширенными параметрами запроса по свойствам mail, otherMails, userPrincipalName и proxyAddresses .
Получение пустых коллекций (/$count eq 0, /$count ne 0) и коллекций с менее чем одним объектом (/$count eq 1, /$count ne 1) поддерживается только с расширенными параметрами запроса.
Операторы not и ne отрицания поддерживаются только с расширенными параметрами запроса.
Все свойства, поддерживающие оператор, eq также поддерживают операторы ne или not .
В следующих таблицах представлена поддержка $filter операторов по свойствам объектов каталога и указывается, где запросы поддерживаются с помощью расширенных возможностей запросов.
Legend
Оператор $filter работает по умолчанию для этого свойства.
Поддержка сортировки по свойствам объектов Microsoft Entra ID (каталог)
В следующей таблице представлена поддержка $orderby по свойствам объектов каталога и указано, где сортировка поддерживается с помощью расширенных возможностей запросов.
Legend
Оператор $orderby работает по умолчанию для этого свойства.
Обработка ошибок расширенных запросов к объектам каталога
Подсчет объектов каталога поддерживается только с использованием расширенных параметров запросов. ConsistencyLevel=eventual Если заголовок не указан, запрос возвращает ошибку при $count использовании сегмента URL-адреса или автоматически игнорирует $count параметр запроса (?$count=true), если он используется.
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Users.Count.GetAsync();
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
graphClient.users().count().get();
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$graphServiceClient->users()->count()->get()->wait();
GET https://graph.microsoft.com/v1.0/applications?$search="displayName:Browser"
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Applications.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Search = "\"displayName:Browser\"";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ApplicationCollectionResponse result = graphClient.applications().get(requestConfiguration -> {
requestConfiguration.queryParameters.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')
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "endsWith(userPrincipalName,'";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "endsWith(userPrincipalName,'";
});
{
"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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "createdDateTime ge 2021-11-01";
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta groups list --filter "createdDateTime ge 2021-11-01" --count "true" --consistency-level "eventual"
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
GroupCollectionResponse result = graphClient.groups().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "createdDateTime ge 2021-11-01";
requestConfiguration.queryParameters.count = true;
requestConfiguration.headers.add("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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Count = true;
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.count = true;
});
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.