过滤条件

Ad Manager REST API 支持根据 List 方法进行过滤。过滤器字符串语法在 EBNF 语法中正式定义。

首先，请查看一些常见的使用场景示例。

示例	含义
orders.updateTime > "2024-01-01T00:00:00-5:00"	列出 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 REST 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 REST API 提供一元运算符 NOT 和 -。它们可以互换使用。

运营商	示例	含义
NOT	NOT a	如果 a 不为 true，则为 true。
-	-a	如果 a 不为 true，则为 true。

比较运算符

Ad Manager REST 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”或在词法上位于它之前，则为 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 REST API 支持使用 * 字符的通配符。

示例	含义
a = "*.foo"	如果 a 以“.foo”结尾，则为 true。

遍历运算符

Ad Manager REST API 支持 . 运算符，该运算符表示通过消息、映射或结构体进行遍历。

示例	含义
a.b = true	如果 a 具有为 true 的布尔值 b 字段，则为 true。
a.b > 42	如果 a 具有大于 42 的数字 b 字段，则为 true。
a.b.c = "foo"	如果 a.b 的字符串 c 字段为“foo”，则为 true。

遍历是使用资源中的字段名称编写的。 单个服务可以指定支持遍历的部分字段。

重要提示 ：. 运算符不能用于遍历重复字段或列表，但与 : 运算符一起使用的情况除外。

有运算符

Ad Manager REST API 支持 : 运算符，即“包含”。它可与集合（重复字段或映射）、消息和字符串一起使用，并且在每种情况下的行为都略有不同。

字符串字段查询，用于检查字符串是否包含匹配的子字符串：

示例	含义
r.displayName:"_250x250"	如果字符串字段 r.displayName 包含子字符串 _250x250，则为 true。

重复字段查询，以查看重复结构是否包含匹配元素：

示例	含义
r:42	如果 r 包含 42，则为 true。
r.foo:42	如果 r 包含元素 e 使 e.foo = 42 为 true，则该值为 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 REST API 支持根据 List 方法进行排序。orderBy 字段的语法是以英文逗号分隔的字段名称列表。例如："foo,bar"。

默认排序顺序为升序。如需为字段指定降序，请附加 " desc" 后缀。例如："foo desc, bar"。

语法中的冗余空格字符会被忽略。值 "foo, bar desc"、" foo , bar desc " 和 "foo,bar desc" 都等效。

子字段使用遍历运算符指定。例如：foo.bar 或 address.street。