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
. Unexpression
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:
NOT
OR
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. |
|
Número entero | Cualquier número que no tenga punto decimal, con o sin signo ("-") se trata como un número entero. |
|
Cadena
En esta sección, se describen los tipos que puedes escribir como un literal de string en la sintaxis del filtro.
Tipo | Definición | Ejemplos |
---|---|---|
Booleano | TRUE o FALSE en mayúsculas o minúsculas. |
|
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. |
|
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.
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 quename
es una string que contiene"abcd"
. - Comprobación de existencia
- Cuando usas el operador
HAS
con el carácter especial*
, el operadorHAS
comprueba si hay valores que no son nulos. Por ejemplo,name:*
muestra todas las instancias en las quename
no es nulo, faltante ni indefinido. - Cuando usas el operador
HAS
con valores que no son de cadena, se comporta igual que el operadorEQUALS
(=
). Por ejemplo,isCompleted:true
se comporta de la misma manera queisCompleted = true
. - Campos repetidos
Puedes usar el operador
HAS
(:
) para filtrar un campo de recursos de API repetido, siempre que se cumplan las siguientes condiciones:- Solo hay un componente repetido en la ruta de acceso del identificador de campo.
- 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 campocolors
, que contiene valores de cadena como"red"
,"blue"
y"yellow"
.item.colors:("red")
muestra todos los elementos que tienen el valor"red"
en el campocolors
.item.colors:("red" "yellow")
muestra todos los elementos que tienen"red"
y"yellow"
en el campocolors
.item.colors:("red" OR "yellow")
muestra todos los elementos que tienen"red"
o"yellow"
en el campocolors
.
item
también tiene un campotools
repetido que es un objeto complejo con un campo escalarshape
, 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"
.
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 que tiene un valor de número entero 93641. |
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 |
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 no es igual a "proposal". |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState tiene un valor de enumeración que es igual a PROPOSED o Buyer_ACEED. |
proposalState = (PROPOSED AND 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 es igual a "Test1" o "Test2". |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName contiene la substring “test”. |
dealName:("A B") |
dealName contiene la subcadena "A B". |
dealName:(A B) |
dealName contiene la substring “A” y la substring “B”. |
dealName:("A" OR "B" AND "C") |
dealName contiene la substring “A” O “B” Y también contiene la substring “C” |
dealName:("A B" 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) |
dealName no contiene ninguna subcadena “A” y también contiene “B”. |
dealName:(NOT "A" OR "B") |
dealName no contiene ninguna subcadena “A” ni contiene “B”. |