本指南介绍了列表过滤条件语法以及如何过滤各种 资源类型。
某些 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}
操作按以下顺序完成:
NOT
OR
AND
例如,以下表达式是等效的:
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”。 |