篩選清單回應

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