Filtrar respuestas de la lista

La mayoría de los servicios de la API de Display & Video 360 proporcionan un método LIST para la recuperación masiva de recursos. Por lo general, estos métodos LIST admiten el filtrado de resultados a través de un parámetro de consulta filter. Usa este parámetro para optimizar el uso de la API y recuperar solo lo que necesitas.

En esta guía, se muestra cómo usar el parámetro filter de manera efectiva.

Estructura del filtro

Un valor del parámetro filter es una cadena que consta de una o más restricciones que se pueden combinar con operadores AND o OR y agruparse con paréntesis.

Las restricciones tienen el formato {field} {operator} {value}. Por ejemplo:

entityStatus="ENTITY_STATUS_ACTIVE"

La longitud de la cadena de filtro no puede superar los 500 caracteres. Si tu string de filtro supera los 500 caracteres, realiza una de las siguientes acciones:

• Divide la lógica en varias strings de filtro y recupera los recursos mediante solicitudes LIST separadas.
• Quita parte de la lógica de la string de filtro y úsala para filtrar los recursos recuperados de manera local.

Une los valores de restricción entre comillas para garantizar que la lógica se aplique correctamente.

Codifica en URL las strings de filtro si realizas llamadas a LIST directamente sin usar una biblioteca cliente.

Consulta Lógica entre restricciones para obtener más detalles sobre el formato de tus consultas.

Campos filtrables

Los campos filtrables de cada método LIST se enumeran en la descripción del parámetro filter del método. En la mayoría de los casos, puedes filtrar un subconjunto de los campos estándar de un recurso. En algunos casos poco frecuentes, hay campos adicionales que puedes usar solo para filtrar.

Cada campo en la descripción del parámetro admite al menos uno de los siguientes operadores comparables:

Operadores comparables
EQUALS (=)	El valor del campo del recurso es igual al valor especificado. Ejemplo: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=)	El valor del campo del recurso es menor o igual que el valor determinado. Suele usarse para comparar una fecha o una fecha y hora. Ejemplo: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=)	El valor del campo del recurso es mayor o igual que el valor determinado. Suele usarse para comparar una fecha o una fecha y hora. Ejemplo: updateTime>="2023-03-01T12:00:00Z"
HAS (:)	El valor del campo de recurso contiene el valor especificado. Si el campo de recursos es una string, se verificará si el valor dado es una substring existente. Si el campo de recursos es un array, verificará si este contiene el valor dado. Ejemplo: lineItemIds:"1234"

Si no se especifican operadores para el campo en la descripción del parámetro, solo puedes usar el operador EQUALS (=). Algunos campos admiten varios operadores.

Algunos campos filtrables, como los de fechas y horas, requieren que el valor comparable siga un formato específico. El formato se especifica junto al campo en la descripción del parámetro filter.

Lógica entre restricciones

Puedes combinar varias restricciones para limitar o expandir la respuesta de tu solicitud LIST.

Por lo general, puedes combinar varias restricciones con operadores lógicos AND y OR. Cada método LIST especifica qué operadores admite. Algunos métodos solo admiten el uso de una única restricción en el parámetro filter.

Ten en cuenta las siguientes restricciones cuando compiles strings de filtro con operadores lógicos AND o OR:

Nota: Los siguientes ejemplos se escriben con las restricciones de parámetros filter del método advertisers.lineItems.list.

• Se debe usar AND entre restricciones o grupos de restricciones que filtren campos diferentes o que filtren el mismo campo de manera diferente. Estos son algunos ejemplos:
  • 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")
• Se debe usar OR entre restricciones individuales que filtren por el mismo campo. Por ejemplo:
  • (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")

• No puedes usar OR para combinar dos grupos de restricciones. En su lugar, usa varias solicitudes LIST con diferentes valores de filtro. Por ejemplo, usa las siguientes solicitudes LIST separadas:

  • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
  • (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

  No uses el operador OR para combinarlos:

  (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

• Los paréntesis pueden estar implícitos si no los usas para agrupar restricciones en una string de filtro. Por ejemplo, la siguiente string de filtro:

  updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"

  se interpreta como:

  updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")