自
2025 年 9 月 8 日起，每个新订单项都需要声明是否会投放欧盟 (EU) 政治广告。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 调用，请对过滤条件字符串进行网址编码。
如需详细了解如何设置查询格式，请参阅限制之间的逻辑。
可过滤的字段
每个 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")
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-07-25。
[null,null,["最后更新时间 (UTC)：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\")`"]]
