Syntaxe et utilisation des filtres de liste

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

Certaines méthodes d'API peuvent accepter un filtre pour limiter les ressources renvoyées dans la 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 expression. Un expression est une combinaison booléenne de comparaisons:

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

• Un élément comparison correspond à un champ de ressource avec une valeur. Vous pouvez utiliser tous 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 des champs répétés. Pour en savoir plus, consultez la section Comporte un opérateur.

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

  • Numéros
  • Strings
  • Expressions entre parenthèses

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

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

  • Texte arbitraire
  • Valeurs booléennes
  • Valeurs d'énumération
  • 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, les filtres suivants sont équivalents:

c=d AND e=f

c=d e=f

Vous pouvez utiliser le trait d'union (-) comme alternative à NOT. Il ne doit pas y avoir d'espace entre le trait d'union (-) et la comparaison suivante. Par exemple, les filtres suivants sont équivalents:

NOT e=f

-e=f

Comparaisons

Cette section décrit les comparaisons avec "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 est le nom du chemin d'accès à un champ de ressource d'API. Le nom se compose d'une série d'identifiants de ressources reliés par un point (.). Chaque identifiant de champ est suivi du niveau suivant de noms pour ce champ. Par exemple, considérons une ressource ayant un champ complexe item avec un autre champ complexe tool, dont le champ est nommé shape. Dans un filtre pour cette ressource, vous feriez référence à la forme nommée item.tool.shape.

Le côté droit est généralement une valeur scalaire qui est convertie dans le type du champ et comparée à celle-ci. Pour en savoir plus, consultez la section sur les types de littéraux de valeur.

Le côté droit d'une comparaison peut également être exprimé sous la forme d'une combinaison booléenne de valeurs littérales entre parenthèses et/ou d'expressions booléennes ne contenant que des valeurs littérales (précédées ou sans NOT). Le nom de gauche et l'opérateur de comparaison sont appliqués à chacune des valeurs. Par exemple, les filtres suivants sont équivalents:

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

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

Voici un autre exemple plus complexe de deux filtres équivalents:

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 du côté droit d'un opérateur de comparaison peut être classée en littéraux de nombre et de chaîne.

Nombre

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

Type	Définition	Exemples
Double	Tout nombre contenant un point décimal, avec ou sans signe ("-") est considéré comme un nombre double.	1234.567 -789.0123
Entier	Tout nombre sans séparateur décimal, avec ou sans signe ("-") est traité comme un entier.	1234 -789

Chaîne

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

Remarque :Un littéral de chaîne peut comporter des guillemets doubles (" ") ou sans guillemets. Vous ne pouvez pas utiliser de guillemets simples pour représenter un littéral de chaîne. Par exemple, "ABC DEF" et ABC DEF sont des littéraux de chaîne, mais "ABC DEF" ne l'est pas.

Type	Définition	Exemples
Booléen	TRUE ou FALSE dans n'importe quelle casse.	TRUE True "true"
Énumération	Nom d'un littéral de type d'énumération. Les énumérations sont sensibles à la casse.	FINALIZED est différent de Finalized
Chaîne	Toute chaîne contenant du texte encodé en UTF-8 ou en ASCII sur 7 bits. Les guillemets intégrés doivent être échappés avec une barre oblique inverse. Les chaînes sans guillemets contenant des espaces blancs sont traitées comme des "AND" implicites parmi tous les mots après avoir divisé la chaîne par des espaces.	name = "test \"double quotes\"" name=(ABC DEF) équivaut à name=ABC AND name=DEF.
Code temporel	Chaîne au format standard ISO8601.	"2014-10-02T15:01:23.045Z"

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 types de valeurs Double, Entier, booléen, Enum et Horodatage.

Remarque :Pour les valeurs stockées sous forme de chaînes, vous ne pouvez utiliser que les opérateurs "!=", "=" et ":". La comparaison de chaînes n'est pas sensible à la casse.

Possède un opérateur

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

Sous-chaîne

Lorsque l'opérateur HAS est utilisé pour comparer les valeurs d'une colonne de chaînes à une chaîne, 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 d'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 où name n'est pas nul, manquant ou non défini.

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

Champs répétés

Vous pouvez utiliser l'opérateur HAS (:) pour filtrer un champ de ressource d'API répété, à condition que les conditions suivantes soient remplies:

1. Le chemin d'accès de l'identifiant de champ ne comporte qu'un seul composant répété.
2. Le dernier identifiant du chemin d'accès du champ est de type scalaire.

Le filtrage sur les champs répétés imbriqués n'est pas disponible.

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 qui ont la valeur "red" dans le champ 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 un champ scalaire shape, dont les valeurs peuvent être "square" ou "round".

• item.tools.shape:("square") renvoie tous les éléments ayant des outils en forme de "square".
• item.tools.shape:("square" "round") renvoie tous les éléments ayant à 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".

Remarque :Tous les champs répétés ne peuvent pas être filtrés. Pour en savoir plus sur une ressource spécifique, consultez la documentation de référence.

Champs imbriqués non renseignés

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

Par défaut, les champs de niveau racine sont définis sur "false". Par défaut, les champs imbriqués ne sont pas renseignés.

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

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"
      }
    }
  ]
}

Étant donné que item.tools.size n'a pas été défini pour item3, le filtre négatif ne renvoie pas l'objet item3.

Exemples

Exemple	Description
externalDealId = "123456789"	externalDealId dont la valeur de chaîne est "123456789".
advertiserId:93641 advertiserId = 93641	advertiserId ayant une valeur entière : 93641.
isSetupComplete = true isSetupComplete:TRUE isSetupComplete = (True)	isSetupComplete est égal à TRUE.
updateTime > "2018-02-14T11:09:19.378Z"	updateTime est postérieure au 14/02/2018 à 11:09:19.378 UTC.
displayName = "proposal" AND proposalRevision = 3 displayName = "proposal" proposalRevision = 3	La chaîne displayName a la même valeur "proposition" ET la révision de proposition est égale à 3.
displayName = "proposal" OR proposalRevision = 3	displayName comporte la valeur de chaîne "proposition", OU la révision de la proposition est égale à 3.
NOT displayName = "proposal" displayName != "proposal"	displayName n'est pas égal à "proposition".
proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED	proposalState possède une valeur d'énumération égale à PROPOSED OU BUYER_ACCEPTED.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = BUYER_ACCEPTED	proposalState a une valeur d'énumération égale à PROPOSED ET BUYER_ACCEPTED.
dealName = Test Deal	Expression INVALID
dealName = "Test Deal"	dealName est égal à "Tester l'accord".
dealName = (Test Deal)	dealName est égal à "Test" et également égal à "Accord".
dealName = ("Test1" OR "Test2") dealName = "Test1" OR dealName = "Test2"	dealName est égal à "Test1" ou "Test2".
dealName:*	dealName is not null.
dealName:"test" dealName:test	dealName contient la sous-chaîne "test".
dealName:("A B") dealName:"A B"	dealName contient la sous-chaîne "A B".
dealName:(A B) dealName:"A" AND dealName:"B"	dealName contient la sous-chaîne "A" et la sous-chaîne "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 contient la sous-chaîne "A" OU "B" ET contient également la sous-chaîne "C"
dealName:("A B" C) dealName:"A B" AND dealName:"C"	dealName contient la sous-chaîne "A B" et la sous-chaîne "C".
dealName:("A B" OR C D)	dealName contient la sous-chaîne "A B" ou "C", ainsi que la sous-chaîne "D".
dealName:(NOT "A" B) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"	dealName ne contient aucune sous-chaîne "A" ni la sous-chaîne "B".
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	dealName ne contient aucune sous-chaîne "A" ni la sous-chaîne "B".