此页面由 Cloud Translation API 翻译。

列表过滤条件语法和用法

本指南介绍了列表过滤条件语法以及如何过滤各种资源类型。

某些 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")

值字面量类型

比较运算符的右侧值可分为“数字”和“数字” 字符串字面量。

数字

本部分介绍了数字字面量的表示形式。

类型	定义	示例
双精度	任何包含小数点的数字，有无符号（“-”）视为双精度浮点型数值。	1234.567 -789.0123
整数	不含小数点（有符号或无符号）的任何数字（“-”）被视为整数。	1234 -789

字符串

本部分介绍了可以在过滤条件语法。

类型	定义	示例
布尔值	`TRUE` 或 `FALSE`（字母不区分大小写）。	`TRUE` `True` `"true"`
枚举	枚举类型字面量的名称。枚举区分大小写。	`FINALIZED` 不同于 `Finalized`。
字符串	任何包含 UTF-8 编码或 7 位 ASCII 文本的字符串。嵌入的引号必须使用反斜杠进行转义。带空格的不带英文引号的字符串被视为隐式“AND” 。	`name = "test \"double quotes\""` `name=(ABC DEF)` 相当于 `name=ABC AND name=DEF`
时间戳	采用 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 advertiserId = 93641`	整数值 93641 的 `advertiserId`。
`isSetupComplete = true isSetupComplete:TRUE 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`”字符串的“suggest”值完全相同AND 提案修订版本等于 3。
`displayName = "proposal" OR proposalRevision = 3`	“`displayName`”的字符串值为“提案订单项”或者，ProposalRevision 等于 3。
`NOT displayName = "proposal" displayName != "proposal"`	`displayName`不等于“提案”。
`proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED`	`proposalState` 具有等于 PROPOSED 或 BUYER_ACCEPTED 的枚举值。
`proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = 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" OR dealName = "Test2"`	`dealName` 等于“Test1”或等于“Test2”。
`dealName:*`	`dealName is not null.`
`dealName:"test" dealName:test`	`dealName` 包含子字符串“test”。
`dealName:("A B") dealName:"A B"`	`dealName` 包含子字符串“A B”。
`dealName:(A B) dealName:"A" AND dealName:"B"`	`dealName` 包含子字符串“A”和子字符串“B”。
`dealName:("A" OR "B" AND "C") dealName:("A" OR "B" "C") dealName:"A" OR dealName:"B" AND dealName:"C" dealName:"A" OR dealName:"B" dealName:"C" (dealName:"A" OR dealName:"B") AND dealName:"C" (dealName:"A" OR dealName:"B") dealName:"C"`	“`dealName`”包含子字符串“A”或“B”AND 还包含子字符串“C”
`dealName:("A B" C) dealName:"A B" AND dealName:"C"`	“`dealName`”包含子字符串“A B”还包含子字符串“C”。
`dealName:("A B" OR C D)`	`dealName` 包含子字符串“A B”或“C”，还包含子字符串“D”。
`dealName:(NOT "A" B) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"`	“`dealName`”不包含任何子字符串“A”还包含子字符串“B”。
`dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"`	“`dealName`”不包含任何子字符串“A”或包含子字符串“B”。