篩選清單回應

Display & Video 360 API 中的多數服務都提供 LIST 方法，可用於大量擷取資源。這些 LIST 方法通常會透過 filter 查詢參數支援篩選結果。使用這個參數，只擷取所需內容，即可提升 API 使用效率。

本指南說明如何有效使用 filter 參數。

篩選器結構

filter 參數值是字串，包含一或多個限制，可與 AND 或 OR 運算子結合，並使用括號分組。

限制的格式為 {field} {operator} {value}。以下將舉例說明：

entityStatus="ENTITY_STATUS_ACTIVE"

篩選器字串長度不得超過 500 個半形字元。如果篩選字串超過 500 個字元，請執行下列任一操作：

  • 將邏輯分割成多個篩選字串，並使用個別的 LIST 要求擷取資源。
  • 從篩選字串中移除部分邏輯，並用於在本機篩選擷取的資源。

請在限制值前後加上引號，確保邏輯套用正確。

如果您未使用用戶端程式庫，直接發出 LIST 呼叫，請對篩選字串進行 URL 編碼。

如要進一步瞭解如何設定查詢格式，請參閱「限制之間的邏輯」。

可篩選的欄位

每個 LIST 方法的篩選欄位都會列在該方法的 filter 參數說明中。在大多數情況下，您可以篩選資源的標準欄位子集。在極少數情況下，您可以使用其他欄位來篩選資料。

參數說明中的每個欄位至少支援下列其中一個可比較運算子：

可比較的運算子
EQUALS (=) 資源欄位值等於指定值。

範例：entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) 資源欄位值小於或等於指定值。通常用於比較日期或日期時間。

範例：updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) 資源欄位值大於或等於指定值。通常用於比較日期或日期時間。

範例：updateTime>="2023-03-01T12:00:00Z"
HAS (:) 資源欄位值包含指定的值。如果資源欄位是字串，則會檢查指定值是否為現有的子字串。如果資源欄位是陣列，則會檢查陣列是否包含指定的值。

範例：lineItemIds:"1234"

如果參數說明中未指定欄位運算子，您只能使用 EQUALS (=) 運算子。部分欄位支援多個運算子。

部分可篩選的欄位 (例如日期和時間欄位) 要求可比較的值必須遵循特定格式。格式會在 filter 參數說明中，欄位旁邊指定。

限制之間的邏輯

您可以結合多個限制，縮小或擴大 LIST 要求的回應範圍。

通常您可以使用 AND 和 OR 邏輯運算子結合多個限制。每個 LIST 方法都會指定支援哪些運算子。部分方法僅支援在 filter 參數中使用單一限制。

使用 AND 或 OR 邏輯運算子建構篩選字串時，請考量下列限制：

  • AND 必須用於篩選不同欄位或以不同方式篩選相同欄位的限制或限制群組之間。以下舉例說明：
    • updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE"
    • 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 要求。例如，使用下列個別的 LIST 要求：

    • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
    • (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

    請勿使用 OR 運算子將兩者結合：

    (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

  • 如果您未使用括號在篩選字串中分組限制，系統可能會隱含括號。例如下列篩選字串：

    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")