Sintassi e utilizzo dei filtri dell'elenco

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:

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, 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.	1234,567 -789,0123
Numero intero	Qualsiasi numero senza virgola decimale, con o senza segno ("-") viene considerato un numero intero.	1234 -789

Stringa

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

Nota: un valore letterale stringa può essere racchiusa tra virgolette doppie (" ") 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, ma "ABC DEF" non lo è.

Tipo	Definizione	Esempi
Booleano	TRUE o FALSE in qualsiasi lettera maiuscola.	TRUE True "true"
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.	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: "<="
• 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.

Nota: per i valori archiviati come stringhe, puoi utilizzare solo i valori "!=", "=" e Operatori di ":". Il confronto delle stringhe non fa distinzione tra maiuscole e minuscole.

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

Controllo dell'esistenza

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

di Gemini Advanced.

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 una risorsa API ripetuta purché vengano soddisfatte le seguenti condizioni:

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

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

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

di Gemini Advanced.

Nota: non tutti i campi ripetuti possono essere filtrati. Per ulteriori dettagli su un 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 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 = 93641	advertiserId con un valore intero 93641.
isSetupComplete = true isSetupComplete:TRUE 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 = "proposal" 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 != "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 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 = "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 una sottostringa "A" OPPURE "B" E contiene anche la sottostringa "C"
dealName:("A B" C) dealName:"A B" AND dealName:"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) 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 contiene la sottostringa "B".