Questa guida descrive la sintassi dei filtri degli elenchi e come filtrare i vari tipi di risorse.
Alcuni metodi API possono accettare un filtro per limitare le risorse restituite nella risposta.
Riepilogo
Questa sezione fornisce una rapida panoramica della struttura della sintassi dei filtri a livello di elenco.
Un filtro è una stringa contenente un
expression
. Unexpression
è una combinazione booleana di confronti:expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )
comparison
corrisponde a un campo risorsa con un valore. Puoi utilizzare tutti gli operatori di confronto comuni.comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
L'operatore
has
, i due punti (:
), può essere utilizzato su stringhe e campi ripetuti. Per maggiori dettagli, consulta la sezione Con operatore.Nei filtri puoi utilizzare i seguenti tipi di valori:
- Numeri
- Stringa
- Espressioni tra parentesi
value = number| string | "*" | "(" expression ")"
Le stringhe possono rappresentare quanto segue:
- Testo arbitrario
- Booleano
- Valori enum
- Timestamp
Espressioni booleane
expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}
Le operazioni vengono eseguite nel seguente ordine:
NOT
OR
AND
Ad esempio, le seguenti espressioni sono equivalenti:
a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)
Puoi omettere l'operatore AND
tra i confronti. Ad esempio, i seguenti filtri sono gli stessi:
c=d AND e=f
c=d e=f
Puoi utilizzare il trattino (-
) in alternativa a NOT
. Non può essere presente uno spazio tra il trattino (-
) e il seguente confronto. Ad esempio, i seguenti filtri sono gli stessi:
NOT e=f
-e=f
Confronti
In questa sezione vengono descritti i confronti con "name OP value"
come i seguenti:
comparison = name OP value
dove
OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"
Il lato sinistro di un confronto è il nome del percorso di un campo di risorse dell'API.
Il nome è composto da una serie di identificatori di risorse collegati da un punto (.
).
Ogni identificatore di campo è seguito dal livello di nome del campo successivo. Ad esempio, considera una risorsa con un campo complesso item
e un altro campo complesso tool
, il cui campo è denominato shape
. In un filtro per questa risorsa, fare riferimento a una forma con il nome item.tool.shape
.
Il lato destro è in genere un valore scalare che viene convertito nel tipo di campo e confrontato con quest'ultimo. Per ulteriori dettagli, consulta la sezione sui tipi Valori letterali.
Il lato destro di un confronto può essere espresso anche come una combinazione booleana tra parentesi di valori letterali e/o espressioni booleane che contengono solo valori letterali (preceduti con o senza NOT
). A ciascun valore vengono applicati il nome sul lato sinistro e l'operatore di confronto. Ad esempio, i seguenti filtri sono gli stessi:
deal.name = ("test 1" OR "test 2")
deal.name = "test 1" OR deal.name = "test 2"
Ecco un altro esempio più complesso di due filtri equivalenti:
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")
Tipi di valori letterali
Il valore sul lato destro di un operatore di confronto può essere classificato in valori letterali Numero e Stringa.
Numero
Questa sezione descrive la rappresentazione di valori letterali numerici.
Tipo | Definizione | Esempi |
---|---|---|
Matrimoniale | Tutti i numeri che contengono un punto decimale, con o senza un segno ("-") vengono considerati come un Doppio. |
|
Numero intero | Tutti i numeri che non hanno una virgola decimale, con o senza un segno ("-") vengono considerati come un numero intero. |
|
Stringa
Questa sezione descrive i tipi che puoi scrivere come valore letterale stringa nella sintassi del filtro.
Tipo | Definizione | Esempi |
---|---|---|
Booleano | TRUE o FALSE in qualsiasi lettera maiuscola. |
|
Enum | Il nome di un valore letterale di tipo di enumerazione. Le enum fanno distinzione tra maiuscole e minuscole. |
FINALIZED non è uguale a Finalized
|
Stringa | Qualsiasi stringa contenente testo con codifica UTF-8 o ASCII a 7 bit. Le virgolette incorporate devono essere convertite in caratteri di escape con una barra rovesciata. Le stringhe senza virgolette che contengono spazi vuoti vengono considerate come "AND" impliciti tra tutte le parole dopo la suddivisione della stringa per spazi vuoti. |
|
Timestamp | Una stringa nel formato standard ISO8601. |
"2014-10-02T15:01:23.045Z"
|
Operatori di confronto
Ecco gli operatori di confronto:
- Minore o uguale a:
"<="
- Minore di:
"<"
- Maggiore di o uguale a:
">="
- Maggiore di:
">"
- Non uguale a:
"!="
- Uguale a:
"="
- Contiene:
":"
Questi operatori si applicano ai tipi di valori Doppio, Numero intero, booleano, Enum e Timestamp.
Con operatore
Puoi utilizzare l'operatore HAS
(:
) per operazioni speciali sui seguenti
campi:
- Sottostringhe
- Quando viene utilizzato l'operatore
HAS
per confrontare i valori di una colonna stringa con una stringa, l'operatore agisce come un'operazione di sottostringa. Ad esempio,name:"abcd"
restituisce tutte le istanze in cuiname
è una stringa contenente"abcd"
. - Verifica dell'esistenza
- Quando utilizzi l'operatore
HAS
con il carattere speciale*
, l'operatoreHAS
cerca valori non null. Ad esempio,name:*
restituisce tutte le istanze in cuiname
non è nullo, mancante o non definito. - Quando utilizzi l'operatore
HAS
con valori non stringa, si comporta come l'operatoreEQUALS
(=
). Ad esempio,isCompleted:true
si comporta comeisCompleted = true
. - Campi ripetuti
Puoi utilizzare l'operatore
HAS
(:
) per filtrare in base a un campo di risorse API ripetuto, a condizione che si verifichino le seguenti condizioni:- È presente un solo componente ripetuto lungo il percorso dell'identificatore di campo
- L'ultimo identificatore del percorso del campo è di tipo scalare
L'applicazione di filtri in base ai campi ripetuti nidificati non è supportato.
Esempio:
item
ha un campocolors
contenente valori stringa come"red"
,"blue"
e"yellow"
.item.colors:("red")
restituisce tutti gli elementi che hanno il valore"red"
nel campocolors
.item.colors:("red" "yellow")
restituisce tutti gli elementi che hanno sia"red"
sia"yellow"
nel campocolors
.item.colors:("red" OR "yellow")
restituisce tutti gli elementi che hanno"red"
o"yellow"
nel campocolors
.
item
ha anche un campotools
ripetuto che è un oggetto complesso con un campo scalareshape
, i cui valori possono essere"square"
o"round"
.item.tools.shape:("square")
restituisce tutti gli elementi che hanno utensili a forma di"square"
.item.tools.shape:("square" "round")
restituisce tutti gli elementi che hanno uno strumento a forma di"square"
e uno a forma di"round"
.item.tools.shape:("square" OR "round")
restituisce tutti gli elementi che hanno uno strumento Forma"square"
o uno strumento a forma di"round"
.
Campi nidificati non compilati
I campi nidificati sono campi secondari di campi a livello principale, ad esempio shape
in
item.tools.shape
è un campo nidificato di items.tools
.
Per impostazione predefinita, i campi a livello di directory principale sono false. I campi nidificati non vengono compilati per impostazione predefinita.
Gli oggetti con campi nidificati non completati non vengono restituiti dai filtri negativi (!=
).
Esempio:
item.tools
ha un'enumerazione size
il cui valore può essere impostato su "SMALL"
, "MEDIUM"
o "LARGE"
.
Se disponi dei seguenti elementi:
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
},
{
"name": "item3"
}
Una chiamata a items.list
con il filtro negativo "tools.size != SMALL"
restituisce quanto segue:
{
"items": [
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
}
]
}
Poiché item.tools.size
non è stato impostato per item3
, il filtro negativo
non restituisce l'oggetto item3
.
Esempi
Esempio | Descrizione |
---|---|
externalDealId = "123456789" |
externalDealId con valore stringa "123456789". |
advertiserId:93641 |
advertiserId con valore intero 93641. |
isSetupComplete = true |
isSetupComplete è uguale a TRUE. |
updateTime > "2018-02-14T11:09:19.378Z" |
updateTime è successiva al 14/02/2018 11:09:19.378 UTC |
displayName = "proposal" AND proposalRevision = 3 |
La stringa displayName ha lo stesso valore di "Proposta" E propostaRevision è uguale a 3. |
displayName = "proposal" OR proposalRevision = 3 |
displayName ha il valore stringa "proposta" OPPURE la propostaRevision è uguale a 3. |
NOT displayName = "proposal" |
displayName non è uguale a "proposta". |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState ha un valore enum uguale a PROPOSED OR BUYER_acceptED. |
proposalState = (PROPOSED AND BUYER_ACCEPTED) |
proposalState ha un valore enum pari a PROPOSED AND BUYER_);">ED |
dealName = Test Deal |
Espressione INVALID |
dealName = "Test Deal" |
dealName è uguale a "Test deal". |
dealName = (Test Deal) |
dealName è uguale a "Test" e anche uguale a "Deal". |
dealName = ("Test1" OR "Test2") |
dealName è uguale a "Test1" o uguale a "Test2". |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName contiene la sottostringa "test". |
dealName:("A B") |
dealName contiene la sottostringa "A B". |
dealName:(A B) |
dealName contiene la sottostringa "A" e la sottostringa "B". |
dealName:("A" OR "B" AND "C") |
dealName contiene la sottostringa "A" OR "B" E contiene anche la sottostringa "C" |
dealName:("A B" C) |
dealName contiene la sottostringa "A B" e anche la sottostringa "C". |
dealName:("A B" OR C D) |
dealName contiene la sottostringa "A B" o "C" e anche la sottostringa "D". |
dealName:(NOT "A" B) |
dealName non contiene alcuna sottostringa "A" e contiene anche la sottostringa "B". |
dealName:(NOT "A" OR "B") |
dealName non contiene alcuna sottostringa "A" o "B". |