本指南介绍了列表过滤条件语法以及如何过滤各种 资源类型。
某些 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")会返回"red"colors字段。item.colors:("red" "yellow")会返回同时具有"red"和colors字段中的"yellow"。item.colors:("red" OR "yellow")会返回包含"red"或colors字段中的"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"形状工具。
未填充的嵌套字段
嵌套字段是根级字段的子字段，例如 shape
item.tools.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 |
整数值 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”字符串的“suggest”值完全相同AND 提案修订版本等于 3。 |
displayName = "proposal" OR proposalRevision = 3 |
“displayName”的字符串值为“提案订单项”或者，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 等于“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”AND 还包含子字符串“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”。 |