使用 $filter 查询参数

2024-12-30

Microsoft Graph 支持 $filterOData 查询参数来检索集合的子集。

使用 $filter 指定的表达式将针对集合中的每个资源进行计算，并且只有表达式计算结果为 true 的项才会包含在响应中。表达式的计算结果为 false 或计算结果为 null的资源，或者因权限而不可用的引用属性将从响应中省略。

查询 $filter 参数也可以应用于成员、 memberOf、 transitiveMembers 和 transitiveMemberOf 等关系。例如，“获取我所属的所有安全组”。

筛选器表达式中支持的运算符和函数

Microsoft Graph 支持使用以下运算符和函数。但是，各个资源及其属性或关系的支持可能会有所不同。此外，某些属性和关系仅支持$filter高级查询。有关详细信息，请参阅特定资源文档，以及如何使用 filter OData 查询参数的语法，了解如何使用这些运算符和函数的示例。此外，存在一些限制。

运算符类型	运算符
相等运算符	等于 (`eq`) 不等于 (`ne`) 逻辑否定（`not`）在 (`in`) 中具有 (`has`) 注意：有关和 `eq` 运算符的限制，请参阅已知问题中的查询参数限制`in`。
关系运算符	小于 (`lt`) 大于 (`gt`) 小于或等于 (`le`) 大于或等于 (`ge`)
Lambda 运算符	任何 (`any`) 全部 (`all`)
条件运算符	以及 (`and`) 或 (`or`)
函数	开头为（`startswith`）结尾为（`endswith`）包含 (`contains`)

使用 lambda 运算符进行筛选

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。它表示要与之匹配的值的复杂类型的属性。
value-to-match 表示要与之匹配的集合的成员。

和 LINQ 中的C#等效语法如下所示：

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

例如，资源的 imAddresses 属性 user 包含 String 基元类型的集合。以下查询仅检索至少有一个 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')";
});



mgc users list --filter "imAddresses/any(i:i eq 'admin@contoso.com')"



// Code snippets are only available for the latest major version. Current major version is $v1.*

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


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

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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
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')"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "imAddresses/any(i:i eq 'admin@contoso.com')",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

资源的 assignedLicenses 属性 user 包含 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)";
});



mgc users list --filter "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)"



// Code snippets are only available for the latest major version. Current major version is $v1.*

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


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

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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
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)"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)",
)

request_configuration = RequestConfiguration(
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");
});



mgc users list --filter "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))" --count "true" --consistency-level "eventual"



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
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
)

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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
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


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))",
		count = True,
)

request_configuration = RequestConfiguration(
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 资源管理器中的示例。

说明	示例
跨多个属性获取名为 Mary 的用户。	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`^**
获取 2017 年 7 月 1 日之后开始的所有登录用户的事件。	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 年 4 月收到的所有电子邮件。	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`) 或Microsoft的值。	获取`~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true`^**
列出其公司名称是未定义或 Microsoft 的所有用户。	获取`~/users?$filter=companyName in (null, 'Microsoft')&$count=true`^**
使用 OData 转换可实现显示名称以“ a”开头(包括返回的对象数)的组中的临时成员资格。	获取`~/me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a')`^**

使用筛选器 OData 查询参数的语法

以下文章演示了使用 $filter OData 查询参数及其关联运算符的语法。这些示例仅用于指导，不反映应用的综合 $filter列表。

注意

GUID 和 DateTimeOffset 值不在表达式中的引号中 $filter 引起来。

^** ：此示例仅支持高级查询功能。

对于字符串、Int 和日期等单个基元类型

运算符	语法
`eq`	`~/users?$filter=userType eq 'Member'` `~/groups?$filter=isAssignableToRole eq true`
`not`	`~/users?$filter=not(userType eq 'Member')`^**
`ne`	`~/users?$filter=companyName ne null`^ `~/groups?$filter=isAssignableToRole ne true`^
`startswith`	`~/users?$filter=startswith(userPrincipalName, 'admin')`
`endswith`	`~/users?$filter=endswith(mail,'@outlook.com')`^**
`in`	`~/users?$filter=mail in ('mail1@___domain.com', 'mail2@___domain.com')` 注意：有关和 `eq` 运算符的限制，请参阅已知问题中的查询参数限制`in`。
`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'))`^**

通过