Sintaxis y uso de los filtros de lista

En esta guía, se describe la sintaxis del filtro de lista y cómo filtrar varios tipos de recursos.

Algunos métodos de la API pueden aceptar un filtro para limitar los recursos que se muestran en la respuesta.

Resumen

En esta sección, se proporciona una descripción general rápida de la estructura sintáctica del filtro de lista.

• Un filtro es una cadena que contiene un expression. Un expression es una combinación booleana de comparaciones:

  expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }
  expression = ( expression )
  

• Un comparison coincide con un campo de recurso con un valor. Puedes usar todos los operadores de comparación comunes.

  comparison = name OP value
  OP = "<=" | "<" | ">=" | ">"  | "!=" | "=" | ":"
  

  El operador has, los dos puntos (:), se puede usar en strings y campos repetidos. Consulta la sección Tiene un operador para obtener más detalles.

• Puedes usar los siguientes tipos de valores en los filtros:

  • Números
  • Cadenas
  • Expresiones entre paréntesis

  value = number| string | "*" | "(" expression ")"
  

• Las cadenas pueden representar lo siguiente:

  • Texto arbitrario
  • Booleanos
  • Enum. de valores
  • Marcas de tiempo

Expresiones booleanas

expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}

Las operaciones se realizan en el siguiente orden:

1. NOT
2. OR
3. AND

Por ejemplo, las siguientes expresiones son equivalentes:

a OR NOT b AND NOT c OR d

(a OR (NOT b)) AND ((NOT c) OR d)

Puedes omitir el operador AND entre las comparaciones. Por ejemplo, los siguientes filtros son los mismos:

c=d AND e=f

c=d e=f

Puedes usar el guion (-) como alternativa para NOT. No puede haber un espacio entre el guion (-) y la siguiente comparación. Por ejemplo, los siguientes filtros son los mismos:

NOT e=f

-e=f

Comparaciones

En esta sección, se describen comparaciones "name OP value" como las siguientes:

comparison = name OP value

en el que

OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"

El lado izquierdo de una comparación es el nombre de la ruta de acceso de un campo de recursos de la API. El nombre consta de una serie de identificadores de recursos conectados por punto (.). Cada identificador de campo va seguido del siguiente nivel de nombres para ese campo. Por ejemplo, considera un recurso que tiene un campo complejo item y otro campo complejo tool, que tiene un campo llamado shape. En un filtro para este recurso, harías referencia a la forma con el nombre item.tool.shape.

El lado derecho suele ser un valor escalar que se convierte al tipo de campo y se compara con él. Consulta la sección de tipos de valor literal para obtener más detalles.

El lado derecho de una comparación también se puede expresar como una combinación booleana entre paréntesis de valores literales o expresiones booleanas que contienen solo valores literales (precedidos con o sin NOT). El nombre del lado izquierdo y el operador de comparación se aplican a cada uno de los valores. Por ejemplo, los siguientes filtros son los mismos:

deal.name = ("test 1" OR "test 2")

deal.name = "test 1" OR deal.name = "test 2"

Este es otro ejemplo más complejo de dos filtros equivalentes:

deal.name = ("test 1" OR "test 2" AND (NOT "test3" OR "test4"))

(deal.name = "test 1" OR deal.name = "test 2") AND ( (NOT deal.name = "test3") OR deal.name = "test4")

Tipos literales de valor

El valor del lado derecho de un operador de comparación se puede clasificar en literales de número y string.

Número

En esta sección, se describe la representación de literales numéricos.

Tipo	Definición	Ejemplos
Double	Cualquier número que contenga un punto decimal, con o sin signo ("-") se trata como un doble.	1234.567 -789.0123
Número entero	Cualquier número que no tenga punto decimal, con o sin signo ("-") se trata como un número entero.	1234 -789

Cadena

En esta sección, se describen los tipos que puedes escribir como un literal de string en la sintaxis del filtro.

Nota: Un literal de string puede estar entre comillas dobles (" ") o no estar entre comillas. No puedes usar comillas simples para representar un literal de string. Por ejemplo, "ABC DEF" y ABC DEF son literales de string, pero "ABC DEF" no lo es.

Tipo	Definición	Ejemplos
Booleano	TRUE o FALSE en mayúsculas o minúsculas.	TRUE True "true"
Enum	El nombre de un literal de tipo de enumeración. Las enumeraciones distinguen mayúsculas de minúsculas.	El "FINALIZED" no es igual a "Finalized"
Cadena	Cualquier string que contenga texto codificado en UTF-8 o ASCII de 7 bits. Las comillas incorporadas se deben escapar con una barra invertida. Las strings sin comillas con espacios en blanco se tratan como “AND” implícito entre todas las palabras después de dividir la string por espacios en blanco.	name = "test \"double quotes\"" name=(ABC DEF) equivale a name=ABC AND name=DEF
Marca de tiempo	Es una cadena en el formato estándar ISO8601.	"2014-10-02T15:01:23.045Z"

Operadores de comparación

Estos son los operadores de comparación:

• Menor o igual que: "<="
• Menor que: "<"
• Mayor o igual que: ">="
• Mayor que: ">"
• No igual a: "!="
• Igual a: "="
• Tiene: ":"

Estos operadores se aplican a los tipos de valor doble, número entero, booleano, enumeración y marca de tiempo.

Nota: Para los valores almacenados como strings, solo puedes usar los operadores "!=", "=" y ":". La comparación de strings no distingue mayúsculas de minúsculas.

Tiene un operador

Puedes usar el operador HAS (:) para operaciones especiales en los siguientes campos:

Substring

Cuando el operador HAS se usa para comparar valores en una columna de string con una string, el operador actúa como una operación de substring. Por ejemplo, name:"abcd" muestra todas las instancias en las que name es una string que contiene "abcd".

Comprobación de existencia

Cuando usas el operador HAS con el carácter especial *, el operador HAS comprueba si hay valores que no son nulos. Por ejemplo, name:* muestra todas las instancias en las que name no es nulo, faltante ni indefinido.

Cuando usas el operador HAS con valores que no son de cadena, se comporta igual que el operador EQUALS (=). Por ejemplo, isCompleted:true se comporta de la misma manera que isCompleted = true.

Campos repetidos

Puedes usar el operador HAS (:) para filtrar un campo de recursos de API repetido, siempre que se cumplan las siguientes condiciones:

1. Solo hay un componente repetido en la ruta de acceso del identificador de campo.
2. El último identificador de la ruta del campo es de tipo escalar

No se admite el filtrado en campos repetidos anidados.

Por ejemplo:

item tiene un campo colors, que contiene valores de cadena como "red", "blue" y "yellow".

• item.colors:("red") muestra todos los elementos que tienen el valor "red" en el campo colors.
• item.colors:("red" "yellow") muestra todos los elementos que tienen "red" y "yellow" en el campo colors.
• item.colors:("red" OR "yellow") muestra todos los elementos que tienen "red" o "yellow" en el campo colors.

item también tiene un campo tools repetido que es un objeto complejo con un campo escalar shape, cuyos valores pueden ser "square" o "round".

• item.tools.shape:("square") muestra todos los elementos que tienen herramientas con forma de "square".
• item.tools.shape:("square" "round") muestra todos los elementos que tienen una herramienta con forma "square" y una con forma "round".
• item.tools.shape:("square" OR "round") muestra todos los elementos que tienen una herramienta de forma "square" o "round".

Nota: No todos los campos repetidos se pueden filtrar. Para obtener más detalles sobre un recurso específico, consulta la documentación de referencia.

Campos anidados sin propagar

Los campos anidados son subcampos de los campos de nivel raíz, por ejemplo, shape en item.tools.shape es un campo anidado de items.tools.

El valor predeterminado de los campos de nivel de raíz es falso. Los campos anidados no se propagan de forma predeterminada.

Los filtros negativos (!=) no muestran los objetos con campos anidados sin propagar.

Por ejemplo:

item.tools tiene una enumeración size cuyo valor se puede establecer en "SMALL", "MEDIUM" o "LARGE".

Si tienes los siguientes elementos:

{
  "name": "item1",
  "tools": {
    "size": "MEDIUM"
  }
},
{
  "name": "item2",
  "tools": {
    "size": "LARGE"
  }
},
{
  "name": "item3"
}

Una llamada a items.list con el filtro negativo "tools.size != SMALL" muestra lo siguiente:

{
  "items": [
    {
      "name": "item1",
      "tools": {
        "size": "MEDIUM"
      }
    },
    {
      "name": "item2",
      "tools": {
        "size": "LARGE"
      }
    }
  ]
}

Dado que item.tools.size no se configuró para item3, el filtro negativo no muestra el objeto item3.

Ejemplos

Ejemplo	Descripción
externalDealId = "123456789"	externalDealId que tiene un valor de string "123456789".
advertiserId:93641 advertiserId = 93641	advertiserId que tiene un valor de número entero 93641.
isSetupComplete = true isSetupComplete:TRUE isSetupComplete = (True)	isSetupComplete es igual a TRUE.
updateTime > "2018-02-14T11:09:19.378Z"	updateTime es posterior al 14/02/2018 a las 11:09:19.378 UTC
displayName = "proposal" AND proposalRevision = 3 displayName = "proposal" proposalRevision = 3	La cadena displayName tiene el mismo valor de "proposal" Y proposalRevision es igual a 3.
displayName = "proposal" OR proposalRevision = 3	displayName tiene el valor de cadena "proposal" O la propuestaRevision es igual a 3.
NOT displayName = "proposal" displayName != "proposal"	displayName no es igual a "proposal".
proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED	proposalState tiene un valor de enumeración que es igual a PROPOSED o Buyer_ACEED.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = BUYER_ACCEPTED	proposalState tiene un valor de enumeración que es igual a PROPOSED Y BUYER_ACEEDED.
dealName = Test Deal	Expresión INVALID
dealName = "Test Deal"	dealName es igual a "Acuerdo de prueba".
dealName = (Test Deal)	dealName es igual a "Prueba" y también a "Acuerdo".
dealName = ("Test1" OR "Test2") dealName = "Test1" OR dealName = "Test2"	dealName es igual a "Test1" o "Test2".
dealName:*	dealName is not null.
dealName:"test" dealName:test	dealName contiene la substring “test”.
dealName:("A B") dealName:"A B"	dealName contiene la subcadena "A B".
dealName:(A B) dealName:"A" AND dealName:"B"	dealName contiene la substring “A” y la substring “B”.
dealName:("A" OR "B" AND "C") dealName:("A" OR "B" "C") dealName:"A" OR dealName:"B" AND dealName:"C" dealName:"A" OR dealName:"B" dealName:"C" (dealName:"A" OR dealName:"B") AND dealName:"C" (dealName:"A" OR dealName:"B") dealName:"C"	dealName contiene la substring “A” O “B” Y también contiene la substring “C”
dealName:("A B" C) dealName:"A B" AND dealName:"C"	dealName contiene la substring “A B” y también la substring “C”.
dealName:("A B" OR C D)	dealName contiene la substring “A B” o “C”, y también contiene la substring “D”.
dealName:(NOT "A" B) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"	dealName no contiene ninguna subcadena “A” y también contiene “B”.
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	dealName no contiene ninguna subcadena “A” ni contiene “B”.