Sintassi e utilizzo dei filtri dell'elenco

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. Un expression è 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:

1. NOT
2. OR
3. 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.	1234.567 -789.0123
Numero intero	Tutti i numeri che non hanno una virgola decimale, con o senza un segno ("-") vengono considerati come un numero intero.	1234 -789

Stringa

Questa sezione descrive i tipi che puoi scrivere come valore letterale stringa nella sintassi del filtro.

Nota: un valore letterale stringa può essere racchiuso tra virgolette (" ") o senza virgolette. Non puoi utilizzare virgolette singole per rappresentare un valore letterale stringa. Ad esempio, "ABC DEF" e ABC DEF sono valori letterali stringa, al contrario di "ABC DEF".

Tipo	Definizione	Esempi
Booleano	TRUE o FALSE in qualsiasi lettera maiuscola.	TRUE True "true"
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.	name = "test \"double quotes\"" name=(ABC DEF) equivale a name=ABC AND name=DEF
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.

Nota: per i valori memorizzati come stringhe, puoi utilizzare solo gli operatori "!=", "=" e ":". Il confronto tra stringhe non è sensibile alle maiuscole.

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 cui name è una stringa contenente "abcd".

Verifica dell'esistenza

Quando utilizzi l'operatore HAS con il carattere speciale *, l'operatore HAS cerca valori non null. Ad esempio, name:* restituisce tutte le istanze in cui name non è nullo, mancante o non definito.

Quando utilizzi l'operatore HAS con valori non stringa, si comporta come l'operatore EQUALS (=). Ad esempio, isCompleted:true si comporta come isCompleted = 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:

1. È presente un solo componente ripetuto lungo il percorso dell'identificatore di campo
2. 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 campo colors contenente valori stringa come "red", "blue" e "yellow".

• item.colors:("red") restituisce tutti gli elementi che hanno il valore "red" nel campo colors.
• item.colors:("red" "yellow") restituisce tutti gli elementi che hanno sia "red" sia "yellow" nel campo colors.
• item.colors:("red" OR "yellow") restituisce tutti gli elementi che hanno "red" o "yellow" nel campo colors.

item ha anche un campo tools ripetuto che è un oggetto complesso con un campo scalare shape, 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".

Nota: non tutti i campi ripetuti possono essere filtrati. Per maggiori dettagli su una risorsa specifica, consulta la documentazione di riferimento.

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 = 93641	advertiserId con valore intero 93641.
isSetupComplete = true isSetupComplete:TRUE 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 displayName = "proposal" 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 != "proposal"	displayName non è uguale a "proposta".
proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED	proposalState ha un valore enum uguale a PROPOSED OR BUYER_acceptED.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = 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 = "Test1" OR dealName = "Test2"	dealName è uguale a "Test1" o uguale a "Test2".
dealName:*	dealName is not null.
dealName:"test" dealName:test	dealName contiene la sottostringa "test".
dealName:("A B") dealName:"A B"	dealName contiene la sottostringa "A B".
dealName:(A B) dealName:"A" AND dealName:"B"	dealName contiene la sottostringa "A" e la sottostringa "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 contiene la sottostringa "A" OR "B" E contiene anche la sottostringa "C"
dealName:("A B" C) dealName:"A B" AND dealName:"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) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"	dealName non contiene alcuna sottostringa "A" e contiene anche la sottostringa "B".
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	dealName non contiene alcuna sottostringa "A" o "B".