list 方法會擷取一組類型的多項資源。filter 查詢參數可讓您提供擷取資源必須符合的條件。
篩選器結構
filter 參數值為字串。這些字串由一或多個條件組成。條件會以 AND 或 OR 運算子連結。
單一條件的格式為 {field} {operator} {value}。範例如下：
entityStatus="ENTITY_STATUS_ACTIVE"
篩選字串不得超過 500 個半形字元，如果字串過長：
- 將邏輯拆分成不同的字串。使用每個篩選器字串發出
list呼叫。合併結果，製作成單一清單。 - 從篩選器字串中移除條件。使用已移除的條件，在本機篩選擷取的資源。
將條件的值括在引號內。
直接發出 API 呼叫時，請確保篩選器字串已編碼，可供網址使用。
如要進一步瞭解篩選器字串結構，請參閱「加入條件」一節。
篩選條件
每個清單方法都支援特定篩選條件。方法 filter 參數的說明會列出這些條件。篩選條件通常是擷取資源欄位的子集。
每個條件都支援一或多個運算子：
| 可比較的運算子 | |
|---|---|
EQUALS (=)
|
欄位等於指定值。 範例： |
LESS THAN OR EQUAL TO (<=)
|
欄位小於或等於指定值。通常用於依日期或日期時間篩選。 範例： |
GREATER THAN OR EQUAL TO (>=)
|
欄位大於或等於指定值。通常用於依日期或日期時間篩選。 範例： |
HAS (:)
|
欄位含有指定值。如果欄位是字串，系統會檢查指定值是否為子字串。如果欄位是陣列，系統會檢查陣列是否含有指定值。 範例： |
如果條件未指定運算子，則僅支援 EQUALS (=)。
如果條件需要特殊格式，系統會註明。
加入條件
加入多個條件，進一步限制 list 回覆。
使用邏輯運算子 AND 和 OR 連結條件。每個 list 方法都會指定支援的屬性。部分方法僅支援含有一項條件的篩選器。
使用多項條件時，請注意下列限制：
| 限制和範例 | |
|---|---|
AND 必須合併篩選不同欄位或以不同方式篩選相同欄位的限制或限制群組。
|
updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
|
OR 必須合併依相同欄位篩選的個別限制。
|
(entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")
|
OR 無法合併兩組限制。請改用多個 list 要求，並指定不同的篩選器值。
|
下列兩個篩選器字串必須在個別要求中使用，無法使用 OR 運算子合併：
|
| 即使未加入括號，系統仍可能會將限制歸類為一組。 |
篩選器字串 updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT" 會解讀為 updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")
|