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.

Stringa

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

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 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.

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