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
. Unexpression
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:
NOT
OR
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. |
|
Entier | Tout nombre sans séparateur décimal, avec ou sans signe ("-") est traité comme un entier. |
|
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.
Type | Définition | Exemples |
---|---|---|
Booléen | TRUE ou FALSE dans n'importe quelle casse. |
|
É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. |
|
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.
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érateurHAS
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érateurEQUALS
(=
). Par exemple,isCompleted:true
se comporte de la même manière queisCompleted = 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:- Le chemin d'accès de l'identifiant de champ ne comporte qu'un seul composant répété.
- 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 champcolors
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 champcolors
.item.colors:("red" "yellow")
renvoie tous les éléments comportant à la fois"red"
et"yellow"
dans le champcolors
.item.colors:("red" OR "yellow")
renvoie tous les éléments comportant"red"
ou"yellow"
dans le champcolors
.
item
comporte également un champtools
répété qui est un objet complexe avec un champ scalaireshape
, 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"
.
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 ayant une valeur entière : 93641. |
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 |
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 n'est pas égal à "proposition". |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState possède une valeur d'énumération égale à PROPOSED OU BUYER_ACCEPTED. |
proposalState = (PROPOSED AND 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 est égal à "Test1" ou "Test2". |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName contient la sous-chaîne "test". |
dealName:("A B") |
dealName contient la sous-chaîne "A B". |
dealName:(A B) |
dealName contient la sous-chaîne "A" et la sous-chaîne "B". |
dealName:("A" OR "B" AND "C") |
dealName contient la sous-chaîne "A" OU "B" ET contient également la sous-chaîne "C" |
dealName:("A B" 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) |
dealName ne contient aucune sous-chaîne "A" ni la sous-chaîne "B". |
dealName:(NOT "A" OR "B") |
dealName ne contient aucune sous-chaîne "A" ni la sous-chaîne "B". |