Использование параметра запроса $filter

Статья
04/21/2024

Microsoft Graph поддерживает $filter параметр запроса OData для получения подмножества коллекции.

Выражение, указанное с параметром $filter , вычисляется для каждого ресурса в коллекции, и в ответ включаются только элементы, для которых выражение имеет значение true . Ресурсы, для которых выражение имеет значение false или nullзначение , или которые ссылаются на свойства, недоступные из-за разрешений, опущены в ответе.

Параметр $filter запроса также можно применять к таким связям, как members, memberOf, transitiveMembers и transitiveMemberOf. Например, "получить все группы безопасности, в которые я вхожу".

Операторы и функции, поддерживаемые в выражениях фильтра

Microsoft Graph поддерживает использование следующих операторов и функций. Однако поддержка отдельных ресурсов и их свойств или связей может отличаться. Кроме того, некоторые свойства и связи поддерживаются $filter только с расширенными запросами. Дополнительные сведения см. в документации по конкретному ресурсу и синтаксисе для использования параметра запроса OData фильтра для примеров использования этих операторов и функций.

Тип оператора	Оператор
Операторы равенства	Равно (`eq`) Не равно (`ne`) Логическое отрицание (`not`) В (`in`) Имеет (`has`) Примечание: При использовании `in` оператора запрос по умолчанию ограничен 15 выражениями в предложении фильтра или URL-адресом длиной 2048 символов при использовании расширенных возможностей запроса.
Операторы отношения	Меньше (`lt`) Больше (`gt`) Меньше или равно (`le`) Больше или равно (`ge`)
Лямбда-операторы	Любой (`any`) Все (`all`)
Условные операторы	И (`and`) Или (`or`)
Functions	Начинается с (`startswith`) Оканчивается на (`endswith`) Содержит (`contains`)

Фильтрация с помощью лямбда-операторов

OData определяет операторы any и all для оценки совпадений по многозначным свойствам, т. е. коллекции примитивных значений, таких как типы строк или коллекции ресурсов.

Оператор `any`

Оператор any итеративно применяет логическое выражение к каждому элементу коллекции и возвращает, true если выражение относится trueпо крайней мере к одному элементу коллекции, в противном случае возвращается false. В следующей строке запроса показан синтаксис оператора any :

$filter=collection/any(property:property/subProperty eq 'value-to-match')

Где

collection — это свойство, содержащее коллекцию значений или коллекцию сложных свойств.
property:property — это переменная диапазона, которая содержит текущий элемент коллекции во время итерации. Эта переменная может называться практически любым именем, например p:p.
SubProperty требуется, если запрос применяется к коллекции сущностей. Он представляет свойство сложного типа, с значением которого вы сопоставляете.
Значение для сопоставления представляет член коллекции, с которой выполняется сопоставление.

Эквивалентный синтаксис в C# и LINQ выглядит следующим образом:

collection.Any(property => property.subProperty == "value-to-match")

Например, свойство userimAddresses ресурса содержит коллекцию строковых примитивных типов. Следующий запрос извлекает только пользователей с по крайней мере одним imAddress .admin@contoso.com

GET https://graph.microsoft.com/v1.0/users?$filter=imAddresses/any(i:i eq 'admin@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 = "imAddresses/any(i:i eq 'admin@contoso.com')";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "imAddresses/any(i:i eq 'admin@contoso.com')"



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFilter := "imAddresses/any(i:i eq 'admin@contoso.com')"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)


// 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 = "imAddresses/any(i:i eq 'admin@contoso.com')";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('imAddresses/any(i:i eq \'admin@contoso.com\')')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "imAddresses/any(i:i eq 'admin@contoso.com')";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "imAddresses/any(i:i eq 'admin@contoso.com')"


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "imAddresses/any(i:i eq 'admin@contoso.com')",
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

Свойство userassignedLicenses ресурса содержит коллекцию объектов assignedLicense, сложного типа с двумя свойствами: skuId и disabledPlans. Следующий запрос извлекает только пользователей с по крайней мере одной назначенной лицензией, определенной skuId184efa21-98c3-4e5d-95ab-d07053a96e67.

GET https://graph.microsoft.com/v1.0/users?$filter=assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)


// 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 = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)"



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFilter := "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)


// 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 = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)"


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)",
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

Чтобы инвертировать результат выражения внутри предложения any, используйте оператор not, а не ne. Например, следующий запрос извлекает только пользователей, которым не назначен параметр imAddress .admin@contoso.com

GET https://graph.microsoft.com/v1.0/users?$filter=NOT(imAddresses/any(i:i eq 'admin@contoso.com'))&$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 = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))";
	requestConfiguration.QueryParameters.Count = true;
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))" --count "true" --consistency-level "eventual"



import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")


requestFilter := "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))"
requestCount := true

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Count: &requestCount,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)


// 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 = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))";
	requestConfiguration.queryParameters.count = true;
	requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.header('ConsistencyLevel','eventual')
	.filter('NOT(imAddresses/any(i:i eq \'admin@contoso.com\'))')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$headers = [
		'ConsistencyLevel' => 'eventual',
	];
$requestConfiguration->headers = $headers;

$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))";
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))" -CountVariable CountVar  -ConsistencyLevel eventual


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))",
		count = True,
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")


result = await graph_client.users.get(request_configuration = request_configuration)

Оператор `all`

Оператор all применяет логическое выражение к каждому члену коллекции и возвращает значение true , если выражение имеет значение true для всех элементов коллекции, в противном случае возвращается false. В настоящее время он не поддерживается в Microsoft Graph.

Примеры использования оператора фильтрации запросов

Приведенная ниже таблица содержит несколько примеров использования параметра запроса $filter. Дополнительные сведения см. в статье Протокол OData.

Примечание.

Примеры, помеченные как ^** , поддерживаются только с расширенными возможностями запросов.
Щелкните метод HTTP, чтобы попробовать примеры в Graph Обозреватель.

Описание	Пример
Получение всех пользователей с именем Маша по нескольким свойствам.	GET`~/users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')`
Получение всех пользователей с почтовым доменом "hotmail.com"	ПОЛУЧИТЬ`~/users?$count=true&$filter=endswith(mail,'@hotmail.com')`^**
Получение всех пользователей без назначенных лицензий	ПОЛУЧИТЬ`~/users?$filter=assignedLicenses/$count eq 0&$count=true`^**
Получение всех событий для вошедшего в систему пользователя, начинающихся начинаются после 01.07.2017 г.	GET`~/me/events?$filter=start/dateTime ge '2017-07-01T08:00'`. ПРИМЕЧАНИЕ: Свойство dateTime сущности события является типом String.
Получение всех сообщений с определенного адреса, полученных вошедшим пользователем.	GET`~/me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'`
Получение всех сообщений, полученных вошедшим пользователем в апреле 2017 г.	GET`~/me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01`
Получение всех непрочитанных сообщений в папке "Входящие" вошедшего пользователя.	GET`~/me/mailFolders/inbox/messages?$filter=isRead eq false`
Получение всех пользователей в отделах розничной торговли и продаж.	GET`~/users?$filter=department in ('Retail', 'Sales')`
Перечисление пользователей с определенным планом обслуживания,находящимся в приостановленном состоянии.	ПОЛУЧИТЬ`~/users?$filter=assignedPlans/any(a:a/servicePlanId eq 2e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2 and a/capabilityStatus eq 'Suspended')&$count=true`^**
Перечисление всех групп, не входящих в Microsoft 365, в организации.	ПОЛУЧИТЬ`~/groups?$filter=NOT groupTypes/any(c:c eq 'Unified')&$count=true`^**
Выведите список всех пользователей, название компании которых не определено (т. е. не является значением `null` ) или майкрософт.	ПОЛУЧИТЬ`~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true`^**
Перечисление всех пользователей, у которых название компании не определено или равно Microsoft.	ПОЛУЧИТЬ`~/users?$filter=companyName in (null, 'Microsoft')&$count=true`^**
Используйте преобразование OData, чтобы получить транзитивное членство в группах с отображаемым именем, которое начинается с "а", включая количество возвращаемых объектов.	ПОЛУЧИТЬ`~/me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a')`^**

Синтаксис использования параметра запроса OData фильтра

В следующей статье демонстрируется синтаксис использования $filter параметра запроса OData и связанных с ним операторов. Примеры приведены только для указания и не отражают полный список для применения $filter.

Примечание.

Значения GUID и DateTimeOffset не заключаются в кавычки в $filter выражениях.

^** : этот пример поддерживается только с расширенными возможностями запросов.

Для отдельных примитивных типов, таких как String, Int и dates

Оператор	Синтаксис
`eq`	`~/users?$filter=userType eq 'Member'`
`not`	`~/users?$filter=not(userType eq 'Member')`^**
`ne`	`~/users?$filter=companyName ne null`^**
`startswith`	`~/users?$filter=startswith(userPrincipalName, 'admin')`
`endswith`	`~/users?$filter=endswith(mail,'@outlook.com')`^**
`in`	`~/users?$filter=mail in ('mail1@domain.com', 'mail2@domain.com')` Примечание: Для строк запроса, использующих `in` оператор, запрос по умолчанию ограничен 15 выражениями в предложении фильтра или URL-адресом длиной 2048 символов при использовании расширенных возможностей запросов.
`le`	`~/devices?$filter=registrationDateTime le 2021-01-02T12:00:00Z`^**
`ge`	`~/devices?$filter=registrationDateTime ge 2021-01-02T12:00:00Z`^**
`not` и `endswith`	`~/users?$filter=not(endswith(mail, 'contoso.com'))`^**
`not` и `startswith`;	`~/users?$filter=not(startswith(mail, 'A'))`^**
`not` и `eq`;	`~/users?$filter=not(companyName eq 'Contoso E.A.')`^**
`not` и `in`	`~/users?$filter=not(userType in ('Member'))`^**
`contains`	`~/identityGovernance/accessReviews/definitions?$filter=contains(scope/microsoft.graph.accessReviewQueryScope/query, './members')`
`has`	`~/identity/conditionalAccess/templates?$filter=scenarios has 'secureFoundation'`

Для коллекции примитивных типов

Оператор (ы)	Синтаксис
`eq`	`~/groups?$filter=groupTypes/any(c:c eq 'Unified')`
`not`	`~/groups?$filter=not(groupTypes/any(c:c eq 'Unified'))`^**
`ne`	`~/users?$filter=companyName ne null`^**
`startswith`	`~/users?$filter=businessPhones/any(p:startswith(p, '44'))`^**
`endswith`	`~/users?$filter=endswith(mail,'@outlook.com')`^**
`not` и `endswith`	`~/groups?$filter=not(endswith(mail,'contoso.com'))`^**
`not` и `startswith`;	`~/groups?$filter=not(startswith(mail,'Pineview'))`^**
`not` и `eq`	`~/groups?$filter=not(mail eq 'PineviewSchoolStaff@Contoso.com')`^**
`eq` и `$count` для пустых коллекций	`~/users?$filter=assignedLicenses/$count eq 0`^**
`ne` и `$count` для пустых коллекций	`~/users?$filter=assignedLicenses/$count ne 0`^**
`not` и `$count` для пустых коллекций	`~/users?$filter=not(assignedLicenses/$count eq 0)`^**
`$count` для коллекций с одним объектом	`~/servicePrincipals?$filter=owners/$count eq 1`^**

Для типов GUID

Оператор (ы)	Синтаксис
`eq`	`~/servicePrincipals?$filter=appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47`^**
`not`	`~/servicePrincipals?$filter=not(appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47)`^**

Для коллекции типов GUID

Оператор (ы)	Синтаксис
`eq`	`~/devices?$filter=alternativeSecurityIds/any(a:a/type eq 2)`^**
`le`	`~/devices?$filter=alternativeSecurityIds/any(a:a/type le 2)`^**
`ge`	`~/devices?$filter=alternativeSecurityIds/any(a:a/type ge 2)`^**

Для коллекции сложных типов

Оператор (ы)	Синтаксис
`eq`	`~/users?$filter=certificateUserIds/any(x:x eq '9876543210@mil')`^**
`not` и `eq`	`~/users?$filter=not(certificateUserIds/any(x:x eq '9876543210@mil'))`^**
`startswith`	`~/users?$filter=certificateUserIds/any(x:startswith(x,'987654321'))`^**
`endswith`	`~/users?$filter=proxyAddresses/any(p:endswith(p,'contoso.com'))`^**

Расширенные возможности запросов к объектам каталога

Использование параметра запроса $filter

Операторы и функции, поддерживаемые в выражениях фильтра

Фильтрация с помощью лямбда-операторов

Оператор `any`

Оператор `all`

Примеры использования оператора фильтрации запросов

Синтаксис использования параметра запроса OData фильтра

Для отдельных примитивных типов, таких как String, Int и dates

Для коллекции примитивных типов

Для типов GUID

Для коллекции типов GUID

Для коллекции сложных типов

Обратная связь

Обратная связь

Дополнительные ресурсы

Использование параметра запроса $filter

Операторы и функции, поддерживаемые в выражениях фильтра

Фильтрация с помощью лямбда-операторов

Оператор any

Оператор all

Примеры использования оператора фильтрации запросов

Синтаксис использования параметра запроса OData фильтра

Для отдельных примитивных типов, таких как String, Int и dates

Для коллекции примитивных типов

Для типов GUID

Для коллекции типов GUID

Для коллекции сложных типов

Связанные материалы

Обратная связь

Обратная связь

Дополнительные ресурсы

Оператор `any`

Оператор `all`