本指南介绍了列表过滤条件语法以及如何过滤各种资源类型。
某些 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")
会返回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”。 |