过滤列表响应

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 逻辑运算符构建过滤条件字符串时，请注意以下限制：

注意 ：以下示例是使用 advertisers.lineItems.list 方法的 filter 参数限制编写的。

• 必须在用于过滤不同字段或以不同方式过滤同一字段的限制或限制组之间使用 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")