使用英语阅读

通过


使用 $filter 查询参数

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

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

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

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

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

运算符类型 运算符
相等运算符
  • 等于 (eq)
  • 不等于 (ne)
  • 逻辑否定(not
  • 在 (in) 中
  • 具有 (has)


注意: 使用 in 运算符时,请求在 filter 子句中默认限制为 15 个表达式,在使用 高级查询功能时,URL 长度限制为 2,048 个字符。
关系运算符
  • 小于 (lt)
  • 大于 (gt)
  • 小于或等于 (le)
  • 大于或等于 (ge)
Lambda 运算符
  • 任何 (any)
  • 全部 (all)
条件运算符
  • 以及 (and)
  • 或 (or)
函数
  • 开头为 (startswith
  • 结尾为 (endswith
  • 包含 (contains)

使用 lambda 运算符进行筛选

OData 定义 anyall 运算符来评估多值属性的匹配项,即基元值(如字符串类型)的集合或资源的集合。

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')

资源的 assignedLicenses 属性 user 包含 assignedLicense 对象的集合,该集合是具有两个属性 (skuIddisabledPlans)的复杂类型。 以下查询仅检索具有由 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)

若要对 any 子句内表达式的结果求反,请使用 not 运算符,而不是 ne 运算符。 例如,以下查询仅检索未分配 imAddress 的用户 admin@contoso.com

注意: 对于像用户这样的目录对象,notne 运算符仅在 高级查询 中受支持。

GET https://graph.microsoft.com/v1.0/users?$filter=NOT(imAddresses/any(i:i eq 'admin@contoso.com'))&$count=true
ConsistencyLevel: eventual

all 运算符

运算符all将布尔表达式应用于集合的每个成员,如果true表达式针对集合的所有项,则返回 true ,否则返回 false。 目前,Microsoft Graph 不支持它。

使用筛选器查询运算符的示例

下表展示了一些使用 $filter 查询参数的示例。 有关详细信息,请参阅 OData 协议

备注

说明 示例
跨多个属性获取名为 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')

注意: 对于使用 in 运算符的查询字符串,默认情况下,请求在 filter 子句中限制为 15 个表达式,在使用 高级查询功能时,URL 长度限制为 2,048 个字符。
le ~/devices?$filter=registrationDateTime le 2021-01-02T12:00:00Z **
ge ~/devices?$filter=registrationDateTime ge 2021-01-02T12:00:00Z **
notendswith ~/users?$filter=not(endswith(mail, 'contoso.com')) **
notstartswith ~/users?$filter=not(startswith(mail, 'A')) **
noteq ~/users?$filter=not(companyName eq 'Contoso E.A.') **
notin ~/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') **
notendswith ~/groups?$filter=not(endswith(mail,'contoso.com')) **
notstartswith ~/groups?$filter=not(startswith(mail,'Pineview')) **
noteq ~/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') **
noteq ~/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')) **