Los métodos list recuperan varios recursos de un tipo determinado. El parámetro de búsqueda filter te permite especificar criterios que deben cumplir los recursos recuperados.
Estructura del filtro
Los valores del parámetro filter son cadenas. Estas cadenas constan de uno o más criterios. Los criterios se unen con los operadores AND o OR.
Un solo criterio tiene el formato {field} {operator} {value}. Por ejemplo:
entityStatus="ENTITY_STATUS_ACTIVE"
Las cadenas de filtro tienen un límite de 500 caracteres. Si la cadena es demasiado larga, haz lo siguiente:
- Divide la lógica en cadenas separadas. Realiza una llamada a
listcon cada cadena de filtro. Combina los resultados para crear una sola lista. - Quita criterios de la cadena de filtro. Usa los criterios quitados para filtrar los recursos recuperados de forma local.
Encierra entre comillas los valores de un criterio.
Asegúrate de que tus cadenas de filtro estén codificadas para usarse en una URL cuando realices llamadas a la API directamente.
Consulta la sección Criterios de unión para obtener más información sobre la estructura de las cadenas de filtro.
Criterios de filtro
Cada método de lista admite ciertos criterios de filtro. La descripción de las listas de parámetros filter del método incluye estos criterios. Los criterios de filtro suelen ser un subconjunto de los campos del recurso recuperado.
Cada criterio admite uno o más operadores:
| Operadores comparables | |
|---|---|
EQUALS (=)
|
El campo es igual al valor proporcionado. Ejemplo: |
LESS THAN OR EQUAL TO (<=)
|
El campo es menor o igual que el valor proporcionado. Se suele usar para filtrar por una fecha o fecha y hora. Ejemplo: |
GREATER THAN OR EQUAL TO (>=)
|
El campo es mayor o igual que el valor proporcionado. Se suele usar para filtrar por una fecha o fecha y hora. Ejemplo: |
HAS (:)
|
El campo contiene el valor proporcionado. Si el campo es una cadena, se verificará si el valor proporcionado es una subcadena. Si el campo es un array, se verificará si contiene el valor determinado. Ejemplo: |
Si un criterio no especifica un operador, solo admite EQUALS (=).
Un criterio indicará si necesita un formato especial.
Criterios de unión
Combina varios criterios para restringir aún más la respuesta de list.
Une criterios con los operadores lógicos AND y OR. Cada método list especifica cuáles son compatibles. Algunos métodos solo admiten filtros con un criterio.
Ten en cuenta estos límites cuando uses varios criterios:
| Limitaciones y ejemplos | |
|---|---|
AND debe combinar restricciones o grupos de restricciones que filtran diferentes campos o que filtran el mismo campo de manera diferente.
|
updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
|
OR debe combinar las restricciones individuales que filtran por el mismo campo.
|
(entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")
|
OR no puede combinar dos grupos de restricciones. En su lugar, usa varias solicitudes list con diferentes valores de filtro.
|
Las siguientes dos cadenas de filtro se deben usar en solicitudes separadas y no se pueden combinar con el operador OR:
|
| Se pueden dar por implícitos los paréntesis para agrupar restricciones, incluso si no se incluyen. |
La cadena 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").
|