本指南介绍了列表过滤器语法以及如何过滤各种资源类型。
某些 API 方法可以接受过滤条件，以限制响应中返回的资源。
摘要
本部分简要介绍了列表过滤条件语法结构。
过滤条件是包含
expression的字符串。expression是比较项的布尔组合：expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )comparison将资源字段与值匹配。您可以使用所有常见的比较运算符。comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"has运算符（英文冒号 [:]）可用于字符串和重复字段。如需了解详情，请参阅“Has”运算符部分。您可以在过滤条件中使用以下类型的值：
- Numbers
- 字符串
- 括号表达式
value = number| string | "*" | "(" expression ")"字符串可以表示以下内容：
- 任意文本
- 布尔值
- 枚举值
- 时间戳
布尔表达式
expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}
操作按以下顺序执行：
NOTORAND
例如，以下表达式是等效的：
a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)
您可以省略比较运算之间的 AND 运算符。例如，以下过滤条件是相同的：
c=d AND e=f
c=d e=f
您可以使用连字符 (-) 代替 NOT。连字符 (-) 与以下比较项之间不得有空格。例如，以下过滤条件是相同的：
NOT e=f
-e=f
比较对象
本部分介绍了 "name OP value" 比较，例如：
comparison = name OP value
其中
OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"
比较运算的左侧是 API 资源字段的路径名称。该名称由一系列通过英文句号 (.) 连接的资源标识符组成。每个字段标识符后跟该字段的下一级别的名称。例如，假设某个资源包含一个复杂字段 item，该字段包含另一个复杂字段 tool，该字段包含一个名为 shape 的字段。在此资源的过滤器中，您可以使用名称 item.tool.shape 引用形状。
右侧通常是标量值，该值会转换为字段的类型并与之进行比较。如需了解详情，请参阅值字面量类型部分。
比较运算的右侧还可以表示为字面量值和/或仅包含字面量值的布尔表达式的带英文括号的布尔组合（前面可以带有 NOT，也可以不带）。左侧名称和比较运算符将应用于每个值。例如，以下过滤条件是相同的：
deal.name = ("test 1" OR "test 2")
deal.name = "test 1" OR deal.name = "test 2"
下面是另一个更复杂的示例，其中包含两个等效的过滤器：
deal.name = ("test 1" OR "test 2" AND (NOT "test3" OR "test4"))
(deal.name = "test 1" OR deal.name = "test 2") AND ( (NOT deal.name = "test3") OR deal.name = "test4")
值字面量类型
比较运算符的右侧值可以分为数字和字符串字面量。
数字
本部分介绍了数字字面量的表示法。
| 类型 | 定义 | 示例 |
|---|---|---|
| 双精度 | 任何包含小数点的数字，无论是否带有符号（“-”），都将被视为双精度数。 |
|
| 整数 | 任何不含小数点的数字（有无符号“-”均可）都将被视为整数。 |
|
字符串
本部分介绍了您可以在过滤条件语法中作为字符串字面量编写的类型。
| 类型 | 定义 | 示例 |
|---|---|---|
| 布尔值 | TRUE 或 FALSE，字母不区分大小写。 |
|
| 枚举 | 枚举类型字面量的名称。枚举区分大小写。 |
FINALIZED 不同于 Finalized
|
| 字符串 | 任何包含 UTF-8 编码或 7 位 ASCII 文本的字符串。 嵌入的引号必须使用反斜杠进行转义。 在按空格拆分字符串后，包含空格的非引号字符串会被视为所有字词之间的隐式“AND”。 |
|
| 时间戳 | 采用 ISO8601 标准格式的字符串。 |
"2014-10-02T15:01:23.045Z"
|
比较运算符
以下是比较运算符：
- 小于或等于：
"<=" - 小于：
"<" - 大于或等于：
">=" - 大于：
">" - 不等于：
"!=" - 等于：
"=" - 包含：
":"
这些运算符适用于 Double、Integer、Boolean、Enum 和 Timestamp 值类型。
有运算符
您可以使用 HAS 运算符 (:) 对以下字段执行特殊操作：
- 子字符串
- 当
HAS运算符用于将字符串列中的值与字符串进行比较时，该运算符将充当子字符串运算。例如，name:"abcd"会返回name为包含"abcd"的字符串的所有实例。 - 存在性检查
- 当您将
HAS运算符与特殊字符*结合使用时，HAS运算符会检查是否存在非 null 值。例如，name:*会返回name不为 null、不缺失或未定义的所有实例。 - 对非字符串值使用
HAS运算符时，其行为与EQUALS(=) 运算符相同。例如，isCompleted:true的行为与isCompleted = true相同。 - 重复字段
您可以使用
HAS(:) 运算符按重复的 API 资源字段进行过滤，前提是满足以下条件：- 字段标识符路径中只有一个重复组成部分
- 字段路径的最后一个标识符是标量类型
不支持对嵌套的重复字段进行过滤。
示例如下：
item有一个colors字段，该字段包含"red"、"blue"和"yellow"等字符串值。item.colors:("red")会返回colors字段中值为"red"的所有项。item.colors:("red" "yellow")会返回colors字段中同时具有"red"和"yellow"的所有项。item.colors:("red" OR "yellow")会返回colors字段中包含"red"或"yellow"的所有项。
item还包含一个重复的tools字段，该字段是带有标量字段shape的复杂对象，其值可以是"square"或"round"。item.tools.shape:("square")会返回所有具有"square"形状工具的项。item.tools.shape:("square" "round")会返回同时具有"square"形状工具和"round"形状工具的所有项。item.tools.shape:("square" OR "round")会返回具有"square"形状工具或"round"形状工具的所有项。
未填充的嵌套字段
嵌套字段是根级字段的子字段，例如 item.tools.shape 中的 shape 是 items.tools 的嵌套字段。
根级字段默认为 false。默认情况下，嵌套字段不会填充。
否定过滤条件 (!=) 不会返回包含未填充嵌套字段的对象。
示例如下：
item.tools 有一个 size 枚举，其值可设置为 "SMALL"、"MEDIUM" 或 "LARGE"。
如果您有以下几项：
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
},
{
"name": "item3"
}
使用否定过滤条件 "tools.size != SMALL" 调用 items.list 会返回以下内容：
{
"items": [
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
}
]
}
由于未为 item3 设置 item.tools.size，因此排除性过滤器不会返回 item3 对象。
示例
| 示例 | 说明 |
|---|---|
externalDealId = "123456789" |
字符串值为“123456789”的 externalDealId。 |
advertiserId:93641 |
整数值为 93641 的 advertiserId。 |
isSetupComplete = true |
isSetupComplete 等于 TRUE。 |
updateTime > "2018-02-14T11:09:19.378Z" |
updateTime晚于 02/14/2018 11:09:19.378 (UTC) |
displayName = "proposal" AND proposalRevision = 3 |
displayName 字符串的值均为“proposal”，且 proposalRevision 等于 3。 |
displayName = "proposal" OR proposalRevision = 3 |
displayName 的字符串值为“proposal”，或者 proposalRevision 等于 3。 |
NOT displayName = "proposal" |
displayName不等于“提案”。 |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState 的枚举值等于 PROPOSED 或 BUYER_ACCEPTED。 |
proposalState = (PROPOSED AND BUYER_ACCEPTED) |
proposalState 的枚举值等于 PROPOSED AND BUYER_ACCEPTED |
dealName = Test Deal |
INVALID 表达式 |
dealName = "Test Deal" |
dealName 等于“Test Deal”。 |
dealName = (Test Deal) |
dealName 等于“Test”，也等于“Deal”。 |
dealName = ("Test1" OR "Test2") |
dealName 等于“Test1”或“Test2”。 |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName 包含子字符串“test”。 |
dealName:("A B") |
dealName 包含子字符串“A B”。 |
dealName:(A B) |
dealName 包含子字符串“A”和子字符串“B”。 |
dealName:("A" OR "B" AND "C") |
dealName 包含子字符串“A”或“B”，同时还包含子字符串“C” |
dealName:("A B" C) |
dealName 包含子字符串“A B”，同时也包含子字符串“C”。 |
dealName:("A B" OR C D) |
dealName 包含子字符串“A B”或“C”，还包含子字符串“D”。 |
dealName:(NOT "A" B) |
dealName 不包含任何“A”子字符串，并且还包含“B”子字符串。 |
dealName:(NOT "A" OR "B") |
dealName 不包含任何子字符串“A”，或包含子字符串“B”。 |