篩選器

Ad Manager REST API 支援篩選 List 方法。篩選器字串語法在 EBNF grammar 中正式定義。

首先，請參考下列常見用途範例。

範例	意義
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 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」之後，則為「是」。
<=	a <= "foo"	如果 a 之前為「foo」或前文是 True，則為 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 REST API 支援使用 * 字元的萬用字元。

範例	意義
a = "*.foo"	如果 a 結尾為「.foo」，則為 true。

走訪運算子

Ad Manager REST API 支援 . 運算子，可透過訊息、地圖或結構表示週遊。

範例	意義
a.b = true	如果 a 的布林值 b 欄位為 true，則為 true。
a.b > 42	如果 a 的 b 欄位大於 42，則為 true。
a.b.c = "foo"	如果 a.b 的字串 c 欄位是「foo」，則為「是」。

週遊是使用資源中的欄位名稱編寫。個別服務可指定遍歷支援的部分欄位子集。

重要事項： . 運算子不能用於透過重複的欄位或清單掃遍整個過程，但搭配 : 運算子的特定用途除外。

含有運算子

Ad Manager REST API 支援 : 運算子，表示「具有」。但可以與集合 (重複欄位或對應)、訊息和字串搭配使用，在每種情況下，行為會略有不同。

字串欄位查詢，用於確認字串是否含有相符的子字串：

範例	意義
r.displayName:"_250x250"	如果 String 欄位 r.displayName 包含子字串 _250x250，則為 true。

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

範例	意義
r:42	如果 r 包含 42，則為 true。
r.foo:42	如果 r 包含類似 e.foo = 42 的元素 e，則為「是」。

重要事項： 篩選器無法在重複欄位中查詢值的特定特定元素。舉例來說，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。