自
2025 年 9 月 8 日起，每個新委刊項都必須聲明是否會放送歐盟政治廣告。如果透過 Display & Video 360 API 和 SDF 上傳的檔案未提供聲明，系統就會失敗。如要進一步瞭解如何更新整合服務以進行這項聲明，請參閱
淘汰項目頁面。
篩選清單回應
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
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")
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-07-25 (世界標準時間)。
[null,null,["上次更新時間：2025-07-25 (世界標準時間)。"],[[["\u003cp\u003eOptimize Display & Video 360 API usage by filtering \u003ccode\u003eLIST\u003c/code\u003e method results with the \u003ccode\u003efilter\u003c/code\u003e query parameter to retrieve only necessary data.\u003c/p\u003e\n"],["\u003cp\u003eStructure filter strings using restrictions like \u003ccode\u003e{field} {operator} {value}\u003c/code\u003e, combining them with \u003ccode\u003eAND\u003c/code\u003e or \u003ccode\u003eOR\u003c/code\u003e operators and parentheses for grouping, ensuring the string remains under 500 characters.\u003c/p\u003e\n"],["\u003cp\u003eRefer to each \u003ccode\u003eLIST\u003c/code\u003e method's documentation for filterable fields and supported operators, using comparison operators such as \u003ccode\u003e=\u003c/code\u003e, \u003ccode\u003e<=\u003c/code\u003e, \u003ccode\u003e>=\u003c/code\u003e, and \u003ccode\u003e:\u003c/code\u003e with appropriate values and formats.\u003c/p\u003e\n"],["\u003cp\u003eConstruct complex filter logic by combining restrictions with \u003ccode\u003eAND\u003c/code\u003e for filtering different fields or applying different criteria to the same field, and \u003ccode\u003eOR\u003c/code\u003e for multiple criteria on the same field, adhering to specific guidelines for combining groups.\u003c/p\u003e\n"]]],["The `LIST` method in the Display & Video 360 API uses a `filter` parameter to refine bulk resource retrieval. Filters are strings comprised of restrictions (`{field} {operator} {value}`) combined with `AND` or `OR` operators, and grouped with parentheses. Common operators include `=`, `\u003c=`, `\u003e=`, and `:`. Restrictions on different fields use `AND`, while same-field restrictions use `OR`. Filter strings are limited to 500 characters, and longer logic should be split into multiple requests. The filter strings must be wrapped in quotes.\n"],null,["# Filter list responses\n\nMost services in the Display \\& Video 360 API provide a `LIST` method for bulk retrieval of\nresources. These `LIST` methods usually support filtering results through a\n`filter` query parameter. Use this parameter to optimize your API usage by only\nretrieving what you need.\n\nThis guide shows how to use the `filter` parameter effectively.\n\nFilter structure\n----------------\n\nA `filter` parameter value is a string, consisting of one or more restrictions\nthat can be combined with **`AND`** or **`OR`** operators, and grouped using\nparentheses.\n\nRestrictions are of the form `{field} {operator} {value}`. Here's an\nexample: \n\n entityStatus=\"ENTITY_STATUS_ACTIVE\"\n\nThe filter string length cannot exceed 500 characters. If your filter string\nexceeds 500 characters, do one of the following:\n\n- Split the logic into multiple filter strings, and retrieve the resources using separate `LIST` requests.\n- Remove some of the logic from the filter string, and use it to filter the retrieved resources locally.\n\nWrap restriction values in quotes to ensure logic is properly applied.\n\nURL-encode your filter strings if you are making `LIST` calls directly without\nusing a client library.\n\nSee [Logic between restrictions](#logic) for more details on formatting\nyour queries.\n\nFilterable fields\n-----------------\n\nEach `LIST` method's filterable fields are listed in the method's `filter`\nparameter description. In most cases, you can filter on a subset of a resource's\nstandard fields. In some rare cases, there are additional fields you can use\nonly for filtering.\n\nEach field in the parameter's description supports at least one of the following\ncomparable operators:\n\n| Comparable Operators || |\n|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|\n| **`EQUALS (=)`** | Resource field value is equal to given value. Example: `entityStatus=\"ENTITY_STATUS_ACTIVE\"` |\n| **`LESS THAN OR EQUAL TO (\u003c=)`** | Resource field value is less than or equal to given value. Often used when comparing a date or datetime. Example: `updateTime\u003c=\"2023-04-01T12:00:00Z\"` |\n| **`GREATER THAN OR EQUAL TO (\u003e=)`** | Resource field value is greater than or equal to given value. Often used when comparing a date or datetime. Example: `updateTime\u003e=\"2023-03-01T12:00:00Z\"` |\n| **`HAS (:)`** | Resource field value contains the given value. If the resource field is a string, it will check if the given value is an existing substring. If the resource field is an array, it will check if the array contains the given value. Example: `lineItemIds:\"1234\"` |\n\nIf no operators are specified for the field in the parameter's description, you\ncan only use the `EQUALS (=)` operator. Some fields support multiple operators.\n\nSome filterable fields, such as those for dates and times, require the\ncomparable value to follow a specific format. The format is specified next to\nthe field in the `filter` parameter description.\n\nLogic between restrictions\n--------------------------\n\nYou can combine multiple restrictions to narrow or expand the response from your\n`LIST` request.\n\nYou can usually combine multiple restrictions with **`AND`** and **`OR`**\nlogical operators. Each `LIST` method specifies which operators it supports.\nSome methods only support using a single restriction in the `filter` parameter.\n\nConsider the following restrictions when building filter strings with **`AND`**\nor **`OR`** logical operators:\n| **Note:** The following examples are written using the [`advertisers.lineItems.list`](/display-video/api/reference/rest/current/advertisers.lineItems/list) method's [`filter`](/display-video/api/reference/rest/current/advertisers.lineItems/list#body.QUERY_PARAMETERS.filter) parameter restrictions.\n\n- **`AND`** must be used between restrictions, or groups of restrictions, that filter different fields, or that filter the same field differently. Here are some examples:\n - `updateTime\u003e=\"2023-03-01T12:00:00Z\" AND entityStatus=\"ENTITY_STATUS_ACTIVE\"`\n - `updateTime\u003e=\"2023-03-01T12:00:00Z\" AND updateTime\u003c=\"2023-04-01T12:00:00Z\"\n AND (entityStatus=\"ENTITY_STATUS_ACTIVE\" OR\n entityStatus=\"ENTITY_STATUS_PAUSED\")`\n- **`OR`** must be used between individual restrictions that filter by the same field. Here's an example:\n - `(entityStatus=\"ENTITY_STATUS_ACTIVE\" OR\n entityStatus=\"ENTITY_STATUS_PAUSED\") AND\n (lineItemType=\"LINE_ITEM_TYPE_DISPLAY_DEFAULT\" OR\n lineItemType=\"LINE_ITEM_TYPE_VIDEO_DEFAULT\")`\n- You can't use **`OR`** to combine two groups of restrictions. Use multiple\n `LIST` requests with different filter values instead. For example, use the\n following separate `LIST` requests:\n\n - `(lineItemType=\"LINE_ITEM_TYPE_DISPLAY_DEFAULT\" AND insertionOrderId=\"123\")`\n - `(lineItemType=\"LINE_ITEM_TYPE_VIDEO_DEFAULT\" AND insertionOrderId=\"456\")`\n\n Don't use the **`OR`** operator to combine them:\n\n `(lineItemType=\"LINE_ITEM_TYPE_DISPLAY_DEFAULT\" AND insertionOrderId=\"123\") OR\n (lineItemType=\"LINE_ITEM_TYPE_VIDEO_DEFAULT\" AND insertionOrderId=\"456\")`\n- Parentheses might be implied if you don't use them to group restrictions in a\n filter string. For example, the following filter string:\n\n `updateTime\u003e=\"2023-03-01T12:00:00Z\" AND entityStatus=\"ENTITY_STATUS_ACTIVE\" OR\n entityStatus=\"ENTITY_STATUS_PAUSED\" OR entityStatus=\"ENTITY_STATUS_DRAFT\"`\n\n is interpreted as:\n\n `updateTime\u003e=\"2023-03-01T12:00:00Z\" AND (entityStatus=\"ENTITY_STATUS_ACTIVE\"\n OR entityStatus=\"ENTITY_STATUS_PAUSED\" OR entityStatus=\"ENTITY_STATUS_DRAFT\")`"]]
