过滤列表响应

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 (=) 运算符。某些字段支持多个运算符。

某些可过滤字段（例如日期和时间字段）要求可比较值采用特定格式。格式在 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")