通过

使用 OData 筛选行

$filter使用 OData 查询选项筛选资源集合。

Dataverse 通过使用表达式集 $filter 评估集合中的每个资源。 响应仅包含表达式计算结果为 true的记录。 如果表达式的判断结果是false或null，或者如果用户对记录没有读取访问权限，则记录不包括在内。

下表介绍了可以在表达式中使用的 $filter 运算符和函数。

Description 详细信息
比较运算符 使用eq、ne、gt、ge、lt和le运算符来比较属性和值。 比较运算符
逻辑运算符 使用 and、or 和 not 来创建更复杂的表达式。 逻辑运算符
分组运算符 使用括号： ()指定计算复杂表达式的优先级。 分组运算符
OData 查询函数 使用contains和endswithstartswith函数计算字符串值。 使用 OData 查询函数
Dataverse 查询函数 使用专为业务应用程序设计的 60 多个专用函数。 Dataverse 查询函数
Lambda 表达式 基于相关集合的值创建表达式。 使用相关集合的值进行筛选

比较运算符

下表描述了可用于比较属性和值的运算符。

Operator Description Example
eq Equal $filter=revenue eq 100000
ne 不等于 $filter=revenue ne 100000
gt 大于 $filter=revenue gt 100000
ge 大于或等于 $filter=revenue ge 100000
lt 小于 $filter=revenue lt 100000
le 小于或等于 $filter=revenue le 100000

列比较

可以使用比较运算符来比较同一行中的属性值。 只能使用比较运算符来比较同一行中的值，列类型必须匹配。 例如，以下查询返回等于firstnamelastname的任何联系人：

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$filter=firstname eq lastname

逻辑运算符

下表描述了可用于创建更复杂的表达式的逻辑运算符。

Operator Description Example
and 逻辑和 $filter=revenue lt 100000 and revenue gt 2000
or 逻辑或 $filter=contains(name,'(sample)') or contains(name,'test')
not 逻辑非 $filter=not contains(name,'sample')

分组运算符

使用带逻辑运算符的括号 () 来指定计算复杂表达式的优先级。 例如：

$filter=(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Dataverse 查询函数

使用专为业务应用程序设计的 60 多个专用函数。 这些函数提供特殊功能，如下表所述。

组 Functions
日期 InFiscalPeriod、、InFiscalPeriodAndYearInFiscalYear、InOrAfterFiscalPeriodAndYear、InOrBeforeFiscalPeriodAndYear、
Last7Days、、LastFiscalPeriod、LastFiscalYearLastMonth、LastWeek、LastXDays、LastXFiscalPeriods、、 LastXFiscalYears
LastXHours、、LastXMonths、LastXWeeksLastXYears、LastYear、Next7Days、NextFiscalPeriod、、 NextFiscalYear
NextMonth、、NextWeekNextXDays、NextXFiscalPeriods、NextXFiscalYears、NextXHours、、 NextXMonths
NextXWeeks、、NextXYearsNextYear、OlderThanXDays、OlderThanXHours、OlderThanXMinutes、、 OlderThanXMonths
OlderThanXWeeks、OlderThanXYears、On、OnOrAfter、OnOrBefore、ThisFiscalPeriod、ThisFiscalYear、ThisMonth、ThisWeek、ThisYear、Today、Tomorrow、Yesterday
ID 值 EqualBusinessId、EqualUserId、NotEqualBusinessId、NotEqualUserId
层次 结构 Above、、AboveOrEqualEqualUserOrUserHierarchy、EqualUserOrUserHierarchyAndTeams、EqualUserOrUserTeams、
EqualUserTeams、NotUnder、Under、UnderOrEqual
详细信息： 查询分层数据
选项列 ContainValues、DoesNotContainValues
详细信息： 从选项查询数据
Between Between、NotBetween
In In、NotIn
语言 EqualUserLanguage

注释

Contains 函数用于具有全文索引的列。 只有 Dynamics 365 KBArticle（文章）表具有建立了全文索引的列。 请改用 OData contains 函数。

Web API Query Function Reference 包含完整列表。 每篇文章都提供了一个可以复制的语法示例。

必须使用函数的 完全限定名称 ，并将 服务命名空间 （Microsoft.Dynamics.CRM） 追加到函数的名称。

每个函数都有一个 PropertyName 指定要计算的属性的参数。 该函数可能具有更多参数，例如 PropertyValue， PropertyValues或 PropertyValue1 和 PropertyValue2。 如果存在这些参数，请提供要与 PropertyName 参数进行比较的值或值。

以下示例演示如何使用 Between 函数 搜索 5 到 2,000 名员工之间的帐户。

GET [Organization URI]/api/data/v9.2/accounts?$select=name,numberofemployees
&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

使用字符串值进行筛选

使用字符串值进行筛选时，请记住以下几点：

  • 使用字符串值的所有筛选器都不区分大小写。
  • 必须在筛选条件中对特殊字符进行 URL 编码。 有关详细信息，请参阅 URL 编码特殊字符。
  • 可以使用通配符，但避免错误地使用它们。 有关详细信息，请参阅 使用通配符。
  • 可以使用 OData 查询函数： contains、 startswith和 endswith。 有关详细信息，请参阅 “使用 OData 查询函数”。
  • 使用接受字符串值数组的筛选器时，必须妥善处理单引号。 有关详细信息，请参阅 “管理单引号”。

URL 编码特殊字符

如果在筛选器函数中用作值的字符串包含特殊字符，则需要对它进行 URL 编码。 例如，如果使用此函数： contains(name,'+123')，则不起作用，因为 + 该函数是不能包含在 URL 中的字符。 当你对字符串进行 URL 编码后，它会变为contains(name,'%2B123')，并且你会得到列值包含 +123 的结果。

下表显示了常见特殊字符的 URL 编码值。

特殊
字符		 已编码的 URL
字符
$ %24
& %26
+ %2B
, %2C
/ %2F
: %3A
; %3B
= %3D
? %3F
@ %40

使用通配符

使用字符串撰写筛选器时，可以使用以下通配符：

字符 Description T-SQL 文档和示例
% 匹配包含零个或多个字符的任意字符串。 将此通配符用作前缀或后缀。 百分比字符（通配符 - 匹配字符）(Transact-SQL)
_ 使用下划线字符匹配涉及模式匹配的字符串比较作中的任何单个字符。 _（通配符 - 匹配一个字符）(Transact-SQL)
[] 匹配指定范围内的任何单个字符，或您在括号中指定的字符集内的字符。 [ ]（通配符 - 匹配字符）(Transact-SQL)
[^] 匹配不在范围内的任何单个字符，或您在方括号中指定的字符集内的字符。 [^]（通配符 - 不匹配字符）(Transact-SQL)

有关详细信息，请参阅 在字符串值条件下使用通配符。

不支持前导通配符

不要使用前导通配符，因为它们不受支持。 使用这些反模式的查询会导致性能问题，因为无法优化查询。 下面是前导通配符的一些示例：

startswith(name,'%value')
endswith(name,'value%')

详细了解在使用前导通配符时返回的错误

使用 OData 查询函数

下表描述了可用于筛选字符串值的 OData 查询函数：

功能 Example
contains $filter=contains(name,'(sample)')
endswith $filter=endswith(name,'Inc.')
startswith $filter=startswith(name,'a')

将这些函数与逻辑运算符 not 一起使用来否定结果。

管理单引号

某些筛选器接受字符串值的数组，例如 In Query 函数。 在这些筛选器中指定包含单引号或撇号字符（如 O'Brian 或 Men's clothes）的值时，应在值的周围使用双引号。例如：

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=Microsoft.Dynamics.CRM.In(PropertyName=@p1,PropertyValues=@p2)
&@p1='lastname'
&@p2=["OBrian","OBryan","O'Brian","O'Bryan"]

如果没有，则会出现以下错误： Invalid JSON. A comma character ',' was expected in scope 'Array'. Every two elements in an array and properties of an object must be separated by commas.

如果筛选器是针对单个值，请将单引号字符替换为两个连续单引号字符;例如：

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=lastname eq 'O''Bryan'

如果没有，将收到如下所示的错误： There is an unterminated literal at position 21 in 'lastname eq 'O'Bryan''.

可以根据相关表中的值筛选返回的行。 筛选方式取决于关系类型。

筛选查找属性

对于一对多关系，过滤的集合 返回的结果与对该关系使用 eq$filter查找属性 的结果相同。 例如，此筛选集合：

GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name

与查找属性上的此筛选器相同。

GET [Organization URI]/api/data/v9.2/accounts?$filter=_owninguser_value eq <systemuserid value>&$select=name

使用查找列的属性值进行筛选

可以根据表示查阅列 的单值导航属性 中的值进行筛选。 使用此模式：

<single-valued navigation property>/<property name>

以下示例根据 primarycontactid/fullname 列的值返回帐户记录：

请求：

GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/fullname eq 'Susanna Stubberod (sample)'
&$select=name,_primarycontactid_value
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

响应：

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_primarycontactid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

还可以进一步比较 单值导航属性的层次结构中的值。

以下示例返回第一个客户，其中联系人记录代表 primarycontactid，记录由“系统管理员”创建，在 $filter 中使用 primarycontactid/createdby/fullname。

请求：

GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/createdby/fullname eq 'System Administrator'
&$select=name,_primarycontactid_value
&$expand=primarycontactid(
$select=fullname,_createdby_value;
$expand=createdby($select=fullname))
&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

响应：

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_primarycontactid_value,primarycontactid(fullname,_createdby_value,createdby(fullname)))",
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "fullname": "Susanna Stubberod (sample)",
                "_createdby_value@OData.Community.Display.V1.FormattedValue": "System Administrator",
                "_createdby_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "createdby": {
                    "fullname": "System Administrator",
                    "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                    "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                }
            }
        }
    ]
}

使用 Lambda 运算符any 并 all 评估集合中的值以筛选结果。

  • any：如果为集合的任何成员应用了表达式，则返回 true true;否则返回 false。

    • any如果集合不为空，则不带参数的运算符将true返回。

  • all：如果应用于集合的所有成员的表达式为 true，则返回 true;否则返回 false。

语法如下所示：

<collection>/[any | all](o:<expression to evaluate>)

在本例中， o 是表示集合中的项的变量。 约定是使用类型的第一个字母。 在表达式中，用于 o/<property or collection name> 引用给定项的属性或集合。

可以在多个集合值导航属性和嵌套集合中包含条件。 不能在嵌套在查找导航属性中的集合值导航属性上包括条件。 例如， $filter=primarycontactid/new_contact_account/any(a:a/accountid eq '{GUID}') 不支持。

详细信息： odata.org 的 Lambda 运算符

Lambda 运算符示例

以下示例检索所有在邮件主题中包含“sometext”的至少有一封电子邮件的 帐户 记录：

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(e:contains(e/subject,'sometext'))
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

以下示例检索所有已关闭关联任务的 帐户 记录：

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Tasks/all(t:t/statecode eq 1)
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

以下示例检索所有 帐户 记录，这些记录至少有一封电子邮件，其主题中包含“sometext”，并且状态代码处于活动状态：

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(e:contains(e/subject,'sometext') and 
e/statecode eq 0)
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

以下示例使用 any 和 all 运算符创建嵌套查询：

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=(contact_customer_accounts/any(c:c/jobtitle eq 'jobtitle' and 
c/opportunity_customer_contacts/any(o:o/description ne 'N/A'))) and 
endswith(name,'Inc.')
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

条件限制

查询中最多可以包含 500 个条件。 否则，会看到以下错误消息：

名称：TooManyConditionsInQuery
代码：0x8004430C
编号： -2147204340
消息：Number of conditions in query exceeded maximum limit.

需要减少执行查询的条件数。 可以使用 In 或NotIn 查询函数减少条件数，这些函数可用于数字、唯一标识符和最多 850 个字符的字符串。

后续步骤

了解如何对结果进行分页。

页面结果

  • Last updated on