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.

String

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

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 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".

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