Questa guida descrive la sintassi dei filtri elenco e come filtrare vari tipi di risorse.
Alcuni metodi dell'API possono accettare un filtro per limitare le risorse restituite nel la risposta corretta.
Riepilogo
Questa sezione fornisce una rapida panoramica della struttura della sintassi dei filtri elenco.
Un filtro è una stringa contenente un
expression
.expression
è un valore booleano combinazione di confronti:expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )
Un valore
comparison
corrisponde a un campo risorsa con un valore. Puoi utilizzare tutte le operatori di confronto comuni.comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
L'operatore
has
, i due punti (:
), può essere utilizzato su stringhe e campi. Consulta la sezione Con operatore per informazioni dettagliate.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,
sono gli stessi:
c=d AND e=f
c=d e=f
Puoi utilizzare il trattino (-
) in alternativa per NOT
. Non può esserci un
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 di "name OP value"
come i seguenti:
comparison = name OP value
dove
OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"
La parte sinistra di un confronto è il nome del percorso di un campo di risorse API.
Il nome è composto da una serie di identificatori di risorse collegati da un punto (.
).
Ogni identificatore di campo è seguito dal livello successivo di nomi per quel campo. Per
Ad esempio, consideriamo una risorsa con un campo complesso item
con un'altra
campo complesso tool
, con un campo denominato shape
. In un filtro per questo
come risorsa, fai riferimento a una forma con il nome item.tool.shape
.
Il lato destro è in genere un valore scalare che viene convertito nel valore di testo e confrontarlo con quest'ultimo. Consulta i tipi di valore letterale per ulteriori dettagli.
Il lato destro di un confronto può anche essere espresso come valore booleano tra parentesi
combinazione di valori letterali e/o espressioni booleane che contengono solo
valori letterali (preceduti con o senza NOT
). Il nome a sinistra e
a ciascuno dei valori. 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:
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 Numero e Valori letterali stringa.
Numero
Questa sezione descrive la rappresentazione dei valori letterali numerici.
Tipo | Definizione | Esempi |
---|---|---|
Doppio | Qualsiasi numero contenente una virgola decimale, con o senza il segno ("-") viene considerato come un doppio. |
|
Numero intero | Qualsiasi numero senza virgola decimale, con o senza segno ("-") viene considerato un numero intero. |
|
Stringa
Questa sezione descrive i tipi che puoi scrivere come valore letterale stringa nel la sintassi del filtro.
Tipo | Definizione | Esempi |
---|---|---|
Booleano | TRUE o FALSE in qualsiasi lettera maiuscola. |
|
Enum | Il nome di un valore letterale di tipo enumerazione. Le enum sono sensibili alle maiuscole. |
FINALIZED non è uguale a Finalized
|
Stringa | Qualsiasi stringa contenente testo con codifica UTF-8 o ASCII a 7 bit. Le virgolette incorporate devono essere precedute dal carattere di escape con una barra rovesciata. Le stringhe senza virgolette con spazi vuoti vengono trattate come "AND" implicite tra tutte le parole dopo la suddivisione della stringa per uno spazio vuoto. |
|
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:
"<="
- Meno di:
"<"
- Maggiore di o uguale a:
">="
- Maggiore di:
">"
- Non uguale a:
"!="
- Uguale a:
"="
- Include:
":"
Questi operatori si applicano ai valori Doppio, Numero intero, Booleano, Enum e Timestamp di testo.
Con operatore
Puoi utilizzare l'operatore HAS
(:
) per operazioni speciali su quanto segue
campi:
- Sottostringhe
- Quando si utilizza l'operatore
HAS
per confrontare i valori di una colonna di tipo stringa con una l'operatore agirà come operazione di sottostringa. Ad esempio:name:"abcd"
restituisce tutte le istanze in cuiname
è una stringa che contiene"abcd"
. - Controllo dell'esistenza
- Quando utilizzi l'operatore
HAS
con il carattere speciale*
, l'operatoreHAS
verifica la presenza di valori diversi da null. Ad esempio:name:*
restituisce tutte le istanze in cuiname
non è nullo, mancante o non definito. di Gemini Advanced.
- 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 una risorsa API ripetuta purché vengano soddisfatte le seguenti condizioni:- È presente un solo componente ripetuto lungo il percorso dell'identificatore del campo
- L'ultimo identificatore del percorso del campo è di tipo scalare
L'applicazione di filtri a campi nidificati e ripetuti non è supportata.
Ecco un esempio:
item
ha un campocolors
, che contiene valori stringa come"red"
,"blue"
e"yellow"
.item.colors:("red")
restituisce tutti gli elementi che hanno il valore"red"
nellacolors
.item.colors:("red" "yellow")
restituisce tutti gli elementi con"red"
e"yellow"
nel campocolors
.item.colors:("red" OR "yellow")
restituisce tutti gli elementi con"red"
o"yellow"
nel campocolors
.
item
ha anche un campotools
ripetuto che è un oggetto complesso con uno scalare camposhape
, i cui valori possono essere"square"
o"round"
.item.tools.shape:("square")
restituisce tutti gli elementi con forma di"square"
i nostri strumenti.item.tools.shape:("square" "round")
restituisce tutti gli elementi che hanno sia un uno strumento a forma di"square"
e uno a forma di"round"
.item.tools.shape:("square" OR "round")
restituisce tutti gli elementi che hanno un strumento Forma"square"
o 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 sono compilati per impostazione predefinita.
Gli oggetti con campi nidificati non compilati non vengono restituiti da valori negativi
(!=
).
Ecco un esempio:
item.tools
ha un'enumerazione size
il cui valore può essere impostato su "SMALL"
, "MEDIUM"
,
o "LARGE"
.
Se hai quanto segue:
{
"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
le seguenti:
{
"items": [
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
}
]
}
Poiché item.tools.size
non è stato impostato per item3
, il filtro negativo non
restituiscono l'oggetto item3
.
Esempi
Esempio | Descrizione |
---|---|
externalDealId = "123456789" |
externalDealId che contiene il valore di stringa "123456789". |
advertiserId:93641 |
advertiserId con un valore intero 93641. |
isSetupComplete = true |
isSetupComplete è uguale a TRUE. |
updateTime > "2018-02-14T11:09:19.378Z" |
updateTime è successiva alle 11:09:19.378 UTC del 14/02/2018 |
displayName = "proposal" AND proposalRevision = 3 |
displayName stringa ha un valore identico di "proposta" E revisione proposta è uguale a 3. |
displayName = "proposal" OR proposalRevision = 3 |
displayName ha il valore stringa "proposta" OPPURE la revisione della proposta è 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 uguale a PROPOSED AND BUYER_ACCEPTED |
dealName = Test Deal |
Espressione INVALID |
dealName = "Test Deal" |
dealName è uguale a "Deal di prova". |
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 una sottostringa "A" OPPURE "B" E contiene anche la sottostringa "C" |
dealName:("A B" C) |
dealName contiene la sottostringa "A B" e contiene anche la sottostringa "C". |
dealName:("A B" OR C D) |
dealName contiene la sottostringa "A B" o "C" e contiene 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 contiene la sottostringa "B". |