Filtros

La API de Ad Manager admite el filtrado en los métodos List. La sintaxis de la cadena de filtro se define de forma formal en la gramática EBNF.

Para comenzar, estos son algunos ejemplos de casos de uso comunes.

Ejemplo	Significado
orders.updateTime > "2024-01-01T00:00:00-5:00"	Muestra los pedidos con un updateTime después del 1 de enero de 2024 en la zona horaria estándar del este
lineItems.targeting.geoTargeting.targetedGeoIds:2840	Muestra las líneas de pedido con una segmentación geográfica que contiene Estados Unidos (ID de segmentación geográfica 2480).
lineItems.displayName = "*_interstitial"	Muestra las líneas de pedido que tienen un nombre visible que termina con la cadena _interstitial.
orders.displayName = "*video*"	Muestra una lista de los pedidos que tienen un nombre visible que contiene la cadena video.
displayName:"video"	Muestra una lista de pedidos que tienen un nombre visible que contiene la cadena video (sintaxis alternativa).

Nota: El filtro debe estar codificado como URL para las solicitudes GET. Por ejemplo:
String de filtro: orders.updateTime > "2024-01-01T00:00:00-5:00"
URL codificada: orders.updateTime%20%3E%20%222024-01-01T00:00:00-5:00%22.
Las bibliotecas cliente se encargan de esto automáticamente.

Literales

Un valor literal sin formato (por ejemplo, 42, Hugo) es un valor con el que se debe hacer coincidir. Los literales que aparecen solos se comparan de forma imprecisa con todos los campos compatibles de un recurso. Los recursos documentan qué campos se consideran para la coincidencia en el método list. Esta función es comparable a la búsqueda universal en la IU de Ad Manager, pero se limita a un solo tipo de recurso.

Los literales de cadena que contienen espacios deben encerrarse entre comillas dobles (por ejemplo, "Foo bar"). No se pueden usar comillas simples para unir literales de cadena.

Operadores lógicos

La API de Ad Manager admite los operadores binarios AND y OR.

Precaución: Estos operadores distinguen mayúsculas de minúsculas. Los literales and y or se tratan como literales.

Operador	Ejemplo	Significado
AND	a AND b	Es verdadero si a y b son verdaderos.
OR	a OR b OR c	Es verdadero si alguno de los valores de a, b y c es verdadero.

Nota: Para coincidir con patrones de habla comunes, el operador OR tiene una prioridad más alta que AND, a diferencia de lo que se encuentra en la mayoría de los lenguajes de programación. La expresión a AND b OR c se evalúa como a AND (b OR c). Cuando sea posible, usa paréntesis explícitos para evitar confusiones.

Operadores de negación

La API de Ad Manager proporciona los operadores unarios NOT y -. Se pueden usar indistintamente.

Operador	Ejemplo	Significado
NOT	NOT a	Es verdadero si a no es verdadero.
-	-a	Es verdadero si a no es verdadero.

Operadores de comparación

La API de Ad Manager admite los operadores de comparación binaria =, !=, <, >, <= y >= para campos de cadena, numéricos, de marca de tiempo y duración.

Operador	Ejemplo	Significado
=	a = true	Es verdadero si a es verdadero.
!=	a != 42	Es verdadero, a menos que a sea igual a 42.
<	a < 42	Es verdadero si a es un valor numérico menor que 42.
>	a > "foo"	Es verdadero si a está ordenado de manera léxica después de "foo".
<=	a <= "foo"	Es verdadero si a es "foo" o está antes de él de forma léxica.
>=	a >= 42	Es verdadero si a es un valor numérico de 42 o superior.

Nota: A diferencia de la mayoría de los lenguajes de programación, los nombres de campos deben aparecer en el lado izquierdo de un operador de comparación; en el lado derecho, solo se aceptan literales y operadores lógicos.

Debido a que los filtros se aceptan como cadenas de consulta, se realiza la conversión de tipo para traducir la cadena al valor fuertemente tipado adecuado:

• Las cadenas esperan comillas dobles. Ejemplo: "Foo bar".
• Las enumeraciones esperan la representación de cadena de la enumeración (distingue mayúsculas de minúsculas).
• Los valores booleanos esperan valores literales true y false.
• Los números esperan las representaciones estándar de números enteros o flotantes. Para los números de punto flotante, se admiten exponentes. Ejemplo: 2.997e9.
• Las duraciones esperan una representación numérica seguida de un sufijo s (para segundos). Ejemplos: "20s", "1.2s".
• Las marcas de tiempo esperan una cadena con formato RFC-3339. Ejemplo: "2012-04-21T11:30:00-04:00". Se admiten compensaciones de UTC.

Precaución: Los identificadores true, false y null solo tienen un significado intrínseco cuando se usan en el contexto de una referencia de campo escrito.

Comodines

Cuando se comparan strings por igualdad, la API de Ad Manager admite comodines que usan el carácter *.

Ejemplo	Significado
a = "*.foo"	Es verdadero si a termina con ".foo".

Operador de recorrido

La API de Ad Manager admite el operador ., que indica la iteración a través de un mensaje, un mapa o una estructura.

Ejemplo	Significado
a.b = true	Es verdadero si a tiene un campo booleano b que es verdadero.
a.b > 42	Es verdadero si a tiene un campo b numérico que es mayor que 42.
a.b.c = "foo"	Es verdadero si a.b tiene un campo c de cadena que es “foo”.

La navegación se escribe con los nombres de los campos del recurso. Los servicios individuales podrían especificar un subconjunto de campos que son compatibles con el recorrido.

Importante: El operador . no se puede usar para recorrer un campo o una lista repetidos, excepto para un uso específico con el operador :.

Tiene un operador

La API de Ad Manager admite el operador :, que significa “tiene”. Se puede usar con colecciones (campos o mapas repetidos), mensajes y cadenas, y se comporta de manera ligeramente diferente en cada caso.

Consulta de campos de cadena para ver si la cadena contiene una subcadena coincidente:

Ejemplo	Significado
r.displayName:"_250x250"	Es verdadero si el campo de cadena r.displayName contiene la substring _250x250.

Consulta de campos repetidos para ver si la estructura repetida contiene un elemento coincidente:

Ejemplo	Significado
r:42	Es verdadero si r contiene 42.
r.foo:42	Es verdadero si r contiene un elemento e tal que e.foo = 42.

Importante: Los filtros no pueden consultar un elemento específico en un campo repetido para obtener un valor. Por ejemplo, e.0.foo = 42 y e[0].foo = 42 no son filtros válidos.

Los mapas, las structs y los mensajes pueden consultar la presencia de un campo en el mapa o un valor específico:

Ejemplo	Significado
m:foo	Es verdadero si m contiene la clave "foo".
m.foo:*	Es verdadero si m contiene la clave "foo".
m.foo:42	Es verdadero si m.foo es 42.

Cuando se atraviesan los mensajes, se considera que un campo solo está presente si tiene un valor que no es predeterminado.

Limitaciones

Los servicios individuales pueden especificar más estructura o limitaciones para las consultas de filtro, además de lo que se define aquí.

Ordenar

La API de Ad Manager admite el ordenamiento en métodos List. La sintaxis para los campos orderBy es una lista de nombres de campos separados por comas. Por ejemplo: "foo,bar".

El orden de clasificación predeterminado es ascendente. Si quieres especificar un orden descendente para un campo, agrega un sufijo " desc". Por ejemplo: "foo desc, bar".

Se ignoran los caracteres de espacio redundantes en la sintaxis. Los valores "foo, bar desc", " foo , bar desc " y "foo,bar desc" son equivalentes.

Los subcampos se especifican con el operador de recorrido. Por ejemplo: foo.bar o address.street.