Syntaxe et utilisation des filtres de liste

Ce guide décrit la syntaxe des filtres de liste et explique comment filtrer divers types de ressources.

Certaines méthodes d'API peuvent accepter un filtre pour limiter les ressources renvoyées dans le de réponse.

Résumé

Cette section offre un aperçu rapide de la structure de la syntaxe des filtres de liste.

• Un filtre est une chaîne contenant un élément expression. Un expression est une valeur booléenne combinaison de comparaisons:

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

• comparison correspond à un champ de ressource avec une valeur. Vous pouvez utiliser toutes les opérateurs de comparaison courants.

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

  L'opérateur has, le signe deux-points (:), peut être utilisé sur des chaînes et répété . Pour en savoir plus, consultez la section Contient un opérateur.

• Vous pouvez utiliser les types de valeurs suivants dans les filtres:

  • Numbers
  • Strings
  • Expressions entre parenthèses

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

• Les chaînes peuvent représenter les éléments suivants:

  • Texte arbitraire
  • Booléen
  • Valeurs enum
  • Codes temporels

Expressions booléennes

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

Les opérations sont effectuées dans l'ordre suivant:

1. NOT
2. OR
3. AND

Par exemple, les expressions suivantes sont équivalentes:

a OR NOT b AND NOT c OR d

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

Vous pouvez omettre l'opérateur AND entre les comparaisons. Par exemple : sont identiques:

c=d AND e=f

c=d e=f

Vous pouvez utiliser le trait d'union (-) au lieu de NOT. Il ne peut pas y avoir espace entre le trait d'union (-) et la comparaison suivante. Par exemple, les filtres suivants sont identiques:

NOT e=f

-e=f

Comparaisons

Cette section décrit les comparaisons de "name OP value" comme suit:

comparison = name OP value

où

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

La partie gauche d'une comparaison correspond au nom de chemin d'un champ de ressource d'API. Le nom consiste en une série d'identifiants de ressources reliés par un point (.). Chaque identifiant de champ est suivi du niveau de noms suivant pour ce champ. Pour Prenons l'exemple d'une ressource dont le champ est complexe item et possède une autre champ complexe tool, dont le champ est nommé shape. Dans un filtre pour ressource, vous faites référence à la forme avec le nom item.tool.shape.

Le côté droit est généralement une valeur scalaire convertie au format et nous nous y comparons. Consultez les types de littéraux de valeur. pour en savoir plus.

Le côté droit d'une comparaison peut également être exprimé sous la forme d'une valeur booléenne combinaison de valeurs littérales et/ou d'expressions booléennes contenant uniquement des valeurs littérales (précédées avec ou sans NOT). Le nom figurant sur la gauche et la section de comparaison sont appliqués à chacune des valeurs. Par exemple, les filtres suivants sont identiques:

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

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

Voici un autre exemple plus complexe de deux exemples filtres:

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

Types de littéraux de valeur

La valeur de droite d'un opérateur de comparaison peut être catégorisée en nombre et Littéraux de chaîne.

Nombre

Cette section décrit la représentation des littéraux numériques.

Chaîne

Cette section décrit les types que vous pouvez écrire en tant que littéral de chaîne dans la la syntaxe du filtre.

Opérateurs de comparaison

Voici les opérateurs de comparaison:

• Inférieur ou égal à : "<="
• Inférieur à : "<"
• Supérieur ou égal à : ">="
• Supérieur à : ">"
• Différent de : "!="
• Égal à: "="
• Contient: ":"

Ces opérateurs s'appliquent aux valeurs "Double", "Entier", "Booléen", "Énumération" et "Horodatage" de données.

Contient un opérateur

Vous pouvez utiliser l'opérateur HAS (:) pour effectuer des opérations spéciales sur les éléments suivants : :

Sous-chaîne

Lorsque l'opérateur HAS est utilisé pour comparer les valeurs d'une colonne de chaîne à une l'opérateur agit comme une opération de sous-chaîne. Par exemple : name:"abcd" renvoie toutes les instances où name est une chaîne contenant "abcd"

Vérification de l'existence

Lorsque vous utilisez l'opérateur HAS avec le caractère spécial *, l'opérateur HAS recherche les valeurs non nulles. Par exemple : name:* renvoie toutes les instances pour lesquelles name n'est pas nul, manquant ou indéfini.

Lorsque vous utilisez l'opérateur HAS avec des valeurs autres que des chaînes, il se comporte de la même manière que l'opérateur EQUALS (=). Par exemple, isCompleted:true se comporte dans le de la même manière que pour isCompleted = true.

Champs répétés

Vous pouvez utiliser l'opérateur HAS (:) pour filtrer une ressource d'API répétée. , tant que les conditions suivantes sont remplies:

1. Il n'y a qu'un seul composant répété le long du chemin de l'identifiant de champ
2. Le dernier identifiant du chemin d'accès du champ est de type scalaire.

Le filtrage sur des champs imbriqués et répétés n'est pas accepté.

Exemple :

item comporte un champ colors qui contient des valeurs de chaîne telles que "red", "blue" et "yellow".

• item.colors:("red") renvoie tous les éléments dont la valeur "red" est incluse dans colors.
• item.colors:("red" "yellow") renvoie tous les éléments comportant à la fois "red" et "yellow" dans le champ colors.
• item.colors:("red" OR "yellow") renvoie tous les éléments comportant "red" ou "yellow" dans le champ colors.

item comporte également un champ tools répété qui est un objet complexe avec une valeur scalaire champ shape, dont les valeurs peuvent être "square" ou "round".

• item.tools.shape:("square") renvoie tous les éléments de forme "square". outils.
• item.tools.shape:("square" "round") renvoie tous les éléments comportant à la fois un Outil en forme de "square" et un outil en forme de "round".
• item.tools.shape:("square" OR "round") renvoie tous les éléments ayant un Outil de forme "square" ou "round".

Champs imbriqués non renseignés

Les champs imbriqués sont des sous-champs de champs racines, par exemple shape dans item.tools.shape est un champ imbriqué de items.tools.

Les champs de niveau racine sont définis sur "false" par défaut. Les champs imbriqués ne sont pas renseignés par défaut.

Les objets dont les champs imbriqués ne sont pas renseignés ne sont pas renvoyés par les filtres (!=).

Exemple :

item.tools comporte une énumération size dont la valeur peut être définie sur "SMALL", "MEDIUM", ou "LARGE".

Si vous disposez des éléments suivants:

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

Un appel à items.list avec le filtre négatif "tools.size != SMALL" renvoie les éléments suivants:

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

Comme item.tools.size n'a pas été défini pour item3, le filtre négatif ne permet pas renvoient l'objet item3.

Exemples