篩選器

Ad Manager 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 UI 中的通用搜尋相似，但範圍僅限於單一資源類型。

含有空格的字串常值應以雙引號括住 (例如："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」或其詞之前的詞句則為「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"。支援世界標準時間時差。

注意：識別碼 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，則傳回「是」。

重複欄位查詢，查看重複結構體是否包含相符的元素：

範例	意義
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」鍵，則傳回「是」。
m.foo:*	如果 m 包含「foo」鍵，則傳回「是」。
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。