篩選器

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 元素，則為 True，例如 e.foo = 42。

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