篩選清單回應

Display & Video 360 API 中的多數服務都提供 LIST 方法來大量擷取資源。這些 LIST 方法通常支援透過 filter 查詢參數篩選結果。這個參數可以只擷取所需資料，進而最佳化 API 用量。

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

篩選器結構

filter 參數值是字串，其中包含一或多個可與 AND 或 OR 運算子合併的限制，以及使用括號加以分組。

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

entityStatus="ENTITY_STATUS_ACTIVE"

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

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

以半形引號括住限制值，以確保邏輯正確套用。

如要在不使用用戶端程式庫的情況下直接進行LIST呼叫，請將篩選器字串進行網址編碼。

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

可篩選的欄位

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