Sintaxis y uso de los filtros de lista

Esta guía describe la sintaxis del filtro de lista y cómo filtrar varios tipos de recursos.

Algunos métodos de API pueden aceptar un filtro para limitar los recursos que se muestran en el 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 un valor booleano una combinación de comparaciones:

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

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

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

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

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

  • Numbers
  • Strings
  • Expresiones entre paréntesis

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

• Las cadenas pueden representar lo siguiente:

  • Texto arbitrario
  • Booleano
  • Valores de enum
  • 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, el siguiente los 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, el los siguientes filtros son iguales:

NOT e=f

-e=f

Comparaciones

En esta sección, se describen comparaciones de "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 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. Para Por ejemplo, considera un recurso que tiene un campo complejo item con otro campo complejo tool, que tiene un campo llamado shape. En un filtro para esto recurso, te referirás a la forma con el nombre item.tool.shape.

Normalmente, el lado derecho es un valor escalar que se convierte en la y compararlo con él. Consulta los tipos de Value Literal. para obtener más detalles.

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

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 equivalentes filtros:

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 de valores literales

El valor del lado derecho de un operador de comparación se puede categorizar en Número y Literales de string.

Número

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

Tipo	Definición	Ejemplos
Doble	Cualquier número que contenga un punto decimal, con o sin un 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

String

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

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

Tipo	Definición	Ejemplos
Booleano	TRUE o FALSE en mayúscula o minúscula.	TRUE True "true"
Enum	El nombre de un literal de tipo de enumeración. Las enumeraciones distinguen mayúsculas de minúsculas.	FINALIZED no es lo mismo que Finalized
String	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 cadenas sin comillas con espacios en blanco se tratan como "AND" implícitos entre todas las palabras después de dividir la cadena 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 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 valores dobles, enteros, booleanos, de enumeración y de marca de tiempo de tipos de datos.

Nota: Para los valores almacenados como strings, solo puedes usar "!=", "=" 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 objetos: campos:

Substring

Cuando el operador HAS se usa para comparar valores en una columna de cadena con una string, el operador actúa como una operación de subcadena. 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 sean nulos. Por ejemplo: name:* muestra todas las instancias en las que name no es nulo, faltante o indefinido.

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

Campos repetidos

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

1. Solo hay un componente repetido a lo largo de la ruta del identificador de campo.
2. El último identificador de la ruta de acceso 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") devuelve todos los elementos que tienen el valor "red" en las colors.
• item.colors:("red" "yellow") devuelve todos los elementos que tengan "red" y "yellow" en el campo colors.
• item.colors:("red" OR "yellow") devuelve todos los elementos que tengan "red" o "yellow" en el campo colors.

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

• item.tools.shape:("square") muestra todos los elementos que tienen la forma "square". con herramientas de visualización.
• item.tools.shape:("square" "round") devuelve todos los elementos que tengan un Las herramientas con forma de "square" y "round".
• item.tools.shape:("square" OR "round") devuelve todos los artículos que tienen un 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 objetos con campos anidados sin propagar no se muestran como filtros (!=).

Por ejemplo:

item.tools tiene una enum 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"
}

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

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

Como no se estableció item.tools.size para item3, el filtro negativo no Devuelve el objeto item3.

Ejemplos

Ejemplo	Descripción
externalDealId = "123456789"	externalDealId con el valor de cadena "123456789".
advertiserId:93641 advertiserId = 93641	advertiserId que tiene un valor de número entero 93641.
isSetupComplete = true isSetupComplete:TRUE isSetupComplete = (True)	isSetupComplete equivale a TRUE.
updateTime > "2018-02-14T11:09:19.378Z"	updateTime es posterior al 14/02/2018 11:09:19.378 UTC
displayName = "proposal" AND proposalRevision = 3 displayName = "proposal" proposalRevision = 3	La cadena displayName tiene un valor idéntico de "proposal" Y proposalRevision es igual a 3.
displayName = "proposal" OR proposalRevision = 3	displayName tiene el valor de cadena "proposal" O bien, ProvisionRevision 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 COMPRADOR_ACEPTADO.
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 COMPRADOR_ACEPTADO
dealName = Test Deal	Expresión INVALID
dealName = "Test Deal"	dealName equivale a "Test Deal".
dealName = (Test Deal)	dealName equivale a "Prueba" y también igual a "Deal".
dealName = ("Test1" OR "Test2") dealName = "Test1" OR dealName = "Test2"	dealName equivale a "Prueba1" o igual a "Prueba2".
dealName:*	dealName is not null.
dealName:"test" dealName:test	dealName contiene la substring “test”.
dealName:("A B") dealName:"A B"	dealName contiene la substring “A B”.
dealName:(A B) dealName:"A" AND dealName:"B"	dealName contiene la substring “A” y la subcadena "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 una de las subcadenas “A” O "B" AND también contiene la subcadena “C”
dealName:("A B" C) dealName:"A B" AND dealName:"C"	dealName contiene la subcadena "A B" y también contiene la subcadena "C".
dealName:("A B" OR C D)	dealName contiene la substring “A B” “C”, y también contiene la subcadena “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 la subcadena "B".
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	dealName no contiene ninguna subcadena “A” o contenga la subcadena “B”.