本指南介绍了列表过滤条件语法以及如何过滤各种资源类型。
某些 API 方法可以接受过滤条件，以限制响应中返回的资源。
摘要
本部分简要介绍了列表过滤条件语法结构。
过滤条件是包含
expression的字符串。expression是一个布尔型比较组合：expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )comparison将资源字段与值匹配。您可以使用所有常见的比较运算符。comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"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"
|
比较运算符
以下是比较运算符：
- 小于或等于：
"<=" - 小于：
"<" - 大于或等于：
">=" - 大于：
">" - 不等于：
"!=" - 等于：
"=" - 包含：
":"
这些运算符适用于双精度、整数、布尔值、枚举和时间戳值类型。
有运算符
您可以对以下字段使用 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" |
externalDealId（具有字符串值“123456789”）。 |
advertiserId:93641 |
advertiserId（具有整数值 93641）。 |
isSetupComplete = true |
isSetupComplete 等于 TRUE。 |
updateTime > "2018-02-14T11:09:19.378Z" |
updateTime 晚于 2018 年 2 月 14 日 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 等于“测试交易”。 |
dealName = (Test Deal) |
dealName 等于“测试”，也等于“交易”。 |
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”OR“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”。 |