Ad Manager API 支持对 List 方法进行过滤。过滤条件字符串语法在 EBNF 语法中进行了正式定义。
下面列出了一些常见使用场景示例，供您参考。
| 示例 | 含义 |
|---|---|
orders.updateTime > "2024-01-01T00:00:00-5:00" |
列出东部标准时间 (EST) 在 2024 年 1 月 1 日之后具有 updateTime 的订单 |
lineItems.targeting.geoTargeting.targetedGeoIds:2840 |
列出地理位置定位包含美国的订单项（地理位置定位 ID 2480） |
lineItems.displayName = "*_interstitial" |
列出显示名称以字符串 _interstitial 结尾的订单项 |
orders.displayName = "*video*" |
列出显示名称包含字符串 video 的订单 |
displayName:"video" |
列出显示名称包含字符串 video（备用语法）的订单 |
字面量
裸字面量值（例如：42、Hugo）是要与之匹配的值。单独显示的字面量与资源上的所有受支持字段进行模糊匹配。资源文档会说明系统会考虑哪些字段来匹配 list 方法。此功能类似于 Ad Manager 界面中的通用搜索，但作用范围仅限于单一资源类型。
包含空格的字符串字面量应用双引号引起来（例如："Foo bar"）。单引号不能用于将字符串字面量引起来。
逻辑运算符
Ad Manager API 支持二元运算符 AND 和 OR。
| 运算符 | 示例 | 含义 |
|---|---|---|
AND |
a AND b |
如果 a 和 b 均为 true，则为 true。 |
OR |
a OR b OR c |
如果 a、b 和 c 中的任意一个为 true，则为 true。 |
否定运算符
Ad Manager API 提供了单元运算符 NOT 和 -。这两者可以互换使用。
| 运算符 | 示例 | 含义 |
|---|---|---|
NOT |
NOT a |
如果 a 不为 true，则为 true。 |
- |
-a |
如果 a 不为 true，则为 true。 |
比较运算符
Ad Manager API 支持对字符串、数字、时间戳和时长字段使用二进制比较运算符 =、!=、<、>、<= 和 >=。
| 运算符 | 示例 | 含义 |
|---|---|---|
= |
a = true |
如果 a 为 true，则为 true。 |
!= |
a != 42 |
除非 a 等于 42，否则为 true。 |
< |
a < 42 |
如果 a 是小于 42 的数值，则返回 true。 |
> |
a > "foo" |
如果 a 在字典顺序上位于“foo”之后，则为 true。 |
<= |
a <= "foo" |
如果 a 为“foo”或在词法上位于“foo”之前，则为 true。 |
>= |
a >= 42 |
如果 a 是 42 或更高的数字值，则为 true。 |
由于过滤条件是作为查询字符串接受的，因此系统会进行类型转换，以将字符串转换为适当的强类型值：
- 字符串应使用双引号。示例：
"Foo bar"。 - 枚举需要枚举的字符串表示法（区分大小写）。
- 布尔值需要
true和false字面量值。 - 数字应采用标准整数或浮点表示法。浮点数支持指数。示例：
2.997e9。 - 时长应采用数字表示法，后跟
s后缀（秒）。示例："20s"、"1.2s"。 - 时间戳应采用 RFC-3339 格式的字符串。示例：
"2012-04-21T11:30:00-04:00"。支持 UTC 偏移量。
通配符
比较字符串是否相等时，Ad Manager API 支持使用 * 字符的通配符。
| 示例 | 含义 |
|---|---|
a = "*.foo" |
如果 a 以“.foo”结尾，则为 true。 |
遍历运算符
Ad Manager API 支持 . 运算符，用于指示通过消息、映射或结构体进行遍历。
| 示例 | 含义 |
|---|---|
a.b = true |
如果 a 的布尔值 b 字段为 true，则为 true。 |
a.b > 42 |
如果 a 的数字 b 字段大于 42，则为 true。 |
a.b.c = "foo" |
如果 a.b 的字符串 c 字段为“foo”，则为 true。 |
使用资源中的字段名称编写遍历。各个服务可以指定支持遍历的字段子集。
有运算符
Ad Manager API 支持 : 运算符，即“包含”。
它适用于集合（重复字段或映射）、消息和字符串，并且在每种情况下的行为略有不同。
字符串字段查询，用于查看字符串是否包含匹配的子字符串：
| 示例 | 含义 |
|---|---|
r.displayName:"_250x250" |
如果字符串字段 r.displayName 包含子字符串 _250x250，则为 true。 |
重复字段查询，以了解重复结构是否包含匹配的元素：
| 示例 | 含义 |
|---|---|
r:42 |
如果 r 包含 42，则返回 true。 |
r.foo:42 |
如果 r 包含 e 元素，使得 e.foo = 42 为 true。 |
映射、结构体和消息可以查询映射中是否存在字段或特定值：
| 示例 | 含义 |
|---|---|
m:foo |
如果 m 包含键“foo”，则为 true。 |
m.foo:* |
如果 m 包含键“foo”，则为 true。 |
m.foo:42 |
如果 m.foo 为 42，则为 true。 |
在遍历消息时，只有当字段具有非默认值时，才会被视为存在。
限制
除了此处定义的结构和限制之外，各个服务还可以为过滤查询指定其他结构或限制。
订单
Ad Manager API 支持对 List 方法进行排序。orderBy 字段的语法是字段名称的英文逗号分隔列表。例如："foo,bar"。
默认排序顺序为升序。如需指定字段的降序顺序，请附加 " desc" 后缀。例如："foo desc, bar"。
语法中的冗余空格字符会被忽略。值 "foo, bar desc"、" foo , bar desc " 和 "foo,bar desc" 都等效。
子字段使用遍历运算符指定。例如：foo.bar 或 address.street。