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
. Unexpression
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:
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, 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. |
|
Número entero | Cualquier número que no tenga punto decimal, con o sin signo (“-”) se trata como un número entero. |
|
String
En esta sección se describen los tipos que puedes escribir como un literal de cadena en el la sintaxis del filtro.
Tipo | Definición | Ejemplos |
---|---|---|
Booleano | TRUE o FALSE en mayúscula o minúscula. |
|
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. |
|
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.
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 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 sean nulos. Por ejemplo:name:*
muestra todas las instancias en las quename
no es nulo, faltante o indefinido. - Cuando usas el operador
HAS
con valores que no son de cadena, este se comporta igual que el operadorEQUALS
(=
). Por ejemplo,isCompleted:true
se comporta en la de la misma manera queisCompleted = true
. - Campos repetidos
Puedes usar el operador
HAS
(:
) para filtrar un recurso de API repetido. siempre que se cumplan las siguientes condiciones:- Solo hay un componente repetido a lo largo de la ruta del identificador de campo.
- 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 campocolors
, que contiene valores de cadena, como"red"
."blue"
y"yellow"
.item.colors:("red")
devuelve todos los elementos que tienen el valor"red"
en lascolors
.item.colors:("red" "yellow")
devuelve todos los elementos que tengan"red"
y"yellow"
en el campocolors
.item.colors:("red" OR "yellow")
devuelve todos los elementos que tengan"red"
o"yellow"
en el campocolors
.
item
también tiene un campotools
repetido que es un objeto complejo con un camposhape
, 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"
.
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 que tiene un valor de número entero 93641. |
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 |
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 no es igual a "proposal". |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState tiene un valor de enumeración que es igual a PROPOSED O COMPRADOR_ACEPTADO. |
proposalState = (PROPOSED AND 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 equivale a "Prueba1" o igual a "Prueba2". |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName contiene la substring “test”. |
dealName:("A B") |
dealName contiene la substring “A B”. |
dealName:(A B) |
dealName contiene la substring “A” y la subcadena "B". |
dealName:("A" OR "B" AND "C") |
dealName contiene una de las subcadenas “A” O "B" AND también contiene la subcadena “C” |
dealName:("A B" 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) |
dealName no contiene ninguna subcadena “A” y también contiene la subcadena "B". |
dealName:(NOT "A" OR "B") |
dealName no contiene ninguna subcadena “A” o contenga la subcadena “B”. |