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 (=)
|
資源欄位值等於指定值。 範例: |
|
LESS THAN OR EQUAL TO (<=)
|
資源欄位值小於或等於指定值。通常用於比較日期或日期時間。 範例: |
|
GREATER THAN OR EQUAL TO (>=)
|
資源欄位值大於或等於指定值。通常用於比較日期或日期時間。 範例: |
|
HAS (:)
|
資源欄位值包含指定值。如果資源欄位是字串,請檢查指定值是否為現有的子字串。如果資源欄位是陣列,請檢查陣列是否包含指定值。 範例: |
如未為參數說明中的欄位指定運算子,您只能使用 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")