过滤条件

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（备用语法）的订单

提示：对于 GET 请求，过滤条件必须采用网址编码。例如：
过滤条件字符串：orders.updateTime > "2024-01-01T00:00:00-5:00"
网址编码：orders.updateTime%20%3E%20%222024-01-01T00:00:00-5:00%22。
客户端库会自动处理此操作。

字面量

裸字面量值（例如：42、Hugo）是要与之匹配的值。单独显示的字面量与资源上的所有受支持字段进行模糊匹配。资源文档会说明系统会考虑哪些字段来匹配 list 方法。此功能类似于 Ad Manager 界面中的通用搜索，但作用范围仅限于单一资源类型。

包含空格的字符串字面量应用双引号引起来（例如："Foo bar"）。单引号不能用于将字符串字面量引起来。

逻辑运算符

Ad Manager API 支持二元运算符 AND 和 OR。

注意 ：这些运算符区分大小写。字面量 and 和 or 被视为“字面量”。

运算符	示例	含义
AND	a AND b	如果 a 和 b 均为 true，则为 true。
OR	a OR b OR c	如果 a、b 和 c 中的任意一个为 true，则为 true。

注意：为了匹配常见的语音模式，OR 运算符的优先级高于 AND，这与大多数编程语言中的运算符优先级不同。表达式 a AND b OR c 的求值结果为 a AND (b OR c)。尽可能使用显式括号，以免造成混淆。

否定运算符

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 偏移量。

注意：标识符 true、false 和 null 仅在类型化字段引用的上下文中才具有内在含义。

通配符

比较字符串是否相等时，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。

重要提示：过滤条件无法针对重复字段中的特定元素查询值。例如，e.0.foo = 42 和 e[0].foo = 42 不是有效的过滤条件。

映射、结构体和消息可以查询映射中是否存在字段或特定值：

示例	含义
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。