In diesem Leitfaden wird die Syntax von Listenfiltern beschrieben und Sie erfahren, wie Sie verschiedene Filter Ressourcentypen.
Einige API-Methoden können einen Filter akzeptieren, um die im Antwort.
Zusammenfassung
Dieser Abschnitt bietet einen kurzen Überblick über die Syntaxstruktur für Listenfilter.
Ein Filter ist ein String, der ein
expression
enthält. Einexpression
ist ein boolescher Wert Kombination von Vergleichen:expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )
Ein
comparison
gleicht ein Ressourcenfeld mit einem Wert ab. Sie können alle gängige Vergleichsoperatoren.comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
Der
has
-Operator, ein Doppelpunkt (:
), kann für Strings und wiederholte . Weitere Informationen finden Sie im Abschnitt Hat einen Operator.Sie können die folgenden Arten von Werten in Filtern verwenden:
- iWork Numbers
- Strings
- Ausdrücke in Klammern
value = number| string | "*" | "(" expression ")"
Strings können Folgendes darstellen:
- Beliebiger Text
- Boolesch
- Enum-Werte
- Zeitstempel
Boolesche Ausdrücke
expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}
Die Vorgänge werden in der folgenden Reihenfolge ausgeführt:
NOT
OR
AND
Die folgenden Ausdrücke sind beispielsweise äquivalent:
a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)
Sie können den Operator AND
zwischen Vergleichen auslassen. Beispiel:
sind die gleichen:
c=d AND e=f
c=d e=f
Du kannst den Bindestrich (-
) als Alternative zu NOT
verwenden. Es darf kein
Leerzeichen zwischen dem Bindestrich (-
) und dem folgenden Vergleich. Beispiel: Der Parameter
folgende Filter sind identisch:
NOT e=f
-e=f
Vergleiche
In diesem Abschnitt werden "name OP value"
-Vergleiche so beschrieben:
comparison = name OP value
Bitte wo?
OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"
Auf der linken Seite eines Vergleichs steht der Pfadname eines API-Ressourcenfelds.
Der Name besteht aus einer Reihe von Ressourcenkennungen, die durch einen Punkt (.
) verbunden sind.
Auf jede Feldkennung folgt die nächste Namensebene für das jeweilige Feld. Für
Angenommen, eine Ressource hat das komplexe Feld item
, das eine weitere
komplexes Feld tool
mit einem Feld namens shape
. In einem Filter hierfür
Ressource ist, würden Sie auf die Form mit dem Namen item.tool.shape
verweisen.
Auf der rechten Seite steht in der Regel ein skalarer Wert, der in den Wert des Felds und damit verglichen. Weitere Informationen zu den Typen von Wertliteralen .
Die rechte Seite eines Vergleichs kann auch als boolescher Wert in Klammern ausgedrückt werden
Kombination von Literalwerten und/oder booleschen Ausdrücken, die nur
Literalwerte mit oder ohne NOT
. Der Name auf der linken Seite und der
Vergleichsoperatoren auf jeden der Werte angewendet. Beispiel: Der Parameter
folgende Filter sind identisch:
deal.name = ("test 1" OR "test 2")
deal.name = "test 1" OR deal.name = "test 2"
Hier ist ein weiteres, komplexeres Beispiel für zwei Äquivalente, Filter:
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")
Wertliteraltypen
Der Wert auf der rechten Seite eines Vergleichsoperators kann in Zahlen und Stringliterale.
Zahl
In diesem Abschnitt wird die Darstellung numerischer Literale beschrieben.
Typ | Definition | Beispiele |
---|---|---|
Doppelt | Eine beliebige Zahl, die ein Dezimalzeichen mit oder ohne Vorzeichen („-“) enthält wird als Double behandelt. |
|
Ganzzahl | Alle Zahlen ohne Dezimalzeichen, mit oder ohne Vorzeichen („-“) wird als Ganzzahl behandelt. |
|
String
In diesem Abschnitt werden die Typen beschrieben, die Sie als String-Literal in der Filtersyntax.
Typ | Definition | Beispiele |
---|---|---|
Boolesch | TRUE oder FALSE unabhängig von der Groß-/Kleinschreibung. |
|
Enum | Der Name eines Enumerationstypliterals. Bei Enums wird zwischen Groß- und Kleinschreibung unterschieden. |
„FINALIZED “ ist nicht dasselbe wie „Finalized “
|
String | Ein String mit UTF-8-codiertem oder 7-Bit-ASCII-Text. Eingebetteten Anführungszeichen muss als Escapezeichen ein umgekehrter Schrägstrich vorangestellt werden. Strings ohne Anführungszeichen mit Leerzeichen werden als implizites UND behandelt nach dem Aufteilen des Strings durch Leerzeichen. |
|
Zeitstempel | Ein String im ISO8601-Standardformat. |
"2014-10-02T15:01:23.045Z"
|
Vergleichsoperatoren
Hier sind die Vergleichsoperatoren:
- Kleiner als oder gleich:
"<="
- Kleiner als:
"<"
- Größer als oder gleich:
">="
- Größer als:
">"
- Ungleich:
"!="
- Ist gleich:
"="
- Enthält:
":"
Diese Operatoren gelten für Werte vom Typ „Double“, „Integer“, „Boolesch“, „Enum“ und „Zeitstempel“ Typen.
Mit Operator
Sie können den HAS
-Operator (:
) für spezielle Vorgänge in folgenden Fällen verwenden:
Felder:
- Teilstrings
- Wenn der Operator
HAS
zum Vergleich von Werten in einer Stringspalte mit einer String definiert, fungiert der Operator als Teilstring-Vorgang. Beispiel:name:"abcd"
gibt alle Instanzen zurück, bei denenname
ein String mit folgendem Inhalt ist:"abcd"
- Existenzprüfung
- Wenn Sie den
HAS
-Operator mit dem Sonderzeichen*
verwenden, sucht der OperatorHAS
auf Nicht-Null-Werte. Beispiel:name:*
gibt alle Instanzen zurück, bei denenname
nicht null, fehlt oder nicht definiert ist. - Der Operator
HAS
mit Nicht-String-Werten verhält sich wie den OperatorEQUALS
(=
). Zum Beispiel verhält sichisCompleted:true
in der wie beiisCompleted = true
. - Wiederkehrende Felder
Sie können den Operator
HAS
(:
) verwenden, um nach einer wiederkehrenden API-Ressource zu filtern ein, solange Folgendes zutrifft:- Es gibt nur eine wiederholte Komponente im Pfad der Feldkennungen
- Die letzte Kennzeichnung des Feldpfads hat einen skalaren Typ
Das Filtern nach verschachtelten wiederkehrenden Feldern wird nicht unterstützt.
Beispiel:
item
hat das Feldcolors
, das Stringwerte wie"red"
,"blue"
und"yellow"
.item.colors:("red")
gibt alle Elemente mit dem Wert"red"
im Feldcolors
.item.colors:("red" "yellow")
gibt alle Elemente zurück, die sowohl"red"
als auch"yellow"
im Feldcolors
.item.colors:("red" OR "yellow")
gibt alle Elemente zurück, die"red"
oder"yellow"
im Feldcolors
.
item
hat auch ein wiederkehrendestools
-Feld, das ein komplexes Objekt mit einem Skalar ist Feldshape
, dessen Werte"square"
oder"round"
sein können.item.tools.shape:("square")
gibt alle Elemente zurück, die das Format"square"
haben Werkzeuge.item.tools.shape:("square" "round")
gibt alle Elemente zurück, die sowohl einen"square"
-förmiges Werkzeug und"round"
-förmiges Werkzeug.item.tools.shape:("square" OR "round")
gibt alle Elemente zurück, Form-Tool"square"
oder"round"
-förmiges Tool.
Nicht ausgefüllte verschachtelte Felder
Verschachtelte Felder sind untergeordnete Felder von Feldern auf Stammebene, z. B. shape
in
item.tools.shape
ist ein verschachteltes Feld von items.tools
.
Felder auf Stammebene sind standardmäßig auf „false“ gesetzt. Verschachtelte Felder werden standardmäßig nicht ausgefüllt.
Objekte mit nicht ausgefüllten verschachtelten Feldern werden von negativen
Filter (!=
)
Beispiel:
item.tools
hat eine size
-Enum, deren Wert auf "SMALL"
, "MEDIUM"
oder "LARGE"
Gehen Sie folgendermaßen vor:
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
},
{
"name": "item3"
}
Ein Aufruf von items.list
mit dem negativen Filter "tools.size != SMALL"
gibt Folgendes zurück:
Folgendes:
{
"items": [
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
}
]
}
Da „item.tools.size
“ nicht für „item3
“ festgelegt wurde, gilt der Negativfilter nicht
item3
-Objekt zurückgeben.
Beispiele
Beispiel | Beschreibung |
---|---|
externalDealId = "123456789" |
externalDealId mit dem Stringwert „123456789“. |
advertiserId:93641 |
advertiserId mit dem Ganzzahlwert 93641. |
isSetupComplete = true |
isSetupComplete ist gleich TRUE. |
updateTime > "2018-02-14T11:09:19.378Z" |
updateTime ist später als der 14.02.2018 um 11:09:19.378 UTC |
displayName = "proposal" AND proposalRevision = 3 |
Der String „displayName “ hat einen identischen Wert für „Angebot“ UND AngebotsRevision ist gleich 3. |
displayName = "proposal" OR proposalRevision = 3 |
„displayName “ hat den Stringwert „Angebot“ ODER das Angebot „Revision ist gleich 3“. |
NOT displayName = "proposal" |
displayName ist nicht gleich "Angebot". |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState hat einen ENUM-Wert, der entweder PROPOSED OR BUYER_ACCEPTED ist. |
proposalState = (PROPOSED AND BUYER_ACCEPTED) |
proposalState hat einen Aufzählungswert, der PROPOSED AND BUYER_ACCEPTED ist. |
dealName = Test Deal |
INVALID -Ausdruck |
dealName = "Test Deal" |
dealName entspricht "Test Deal". |
dealName = (Test Deal) |
dealName ist gleich „Test“ und ist gleich „Deal“. |
dealName = ("Test1" OR "Test2") |
dealName ist entweder gleich „Test1“ oder gleich "Test2" sein. |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName enthält den Teilstring „test“. |
dealName:("A B") |
dealName enthält den Teilstring „A B“. |
dealName:(A B) |
dealName enthält den Teilstring „A“. und die Teilzeichenfolge „B“. |
dealName:("A" OR "B" AND "C") |
dealName enthält entweder den Teilstring „A“ ODER "B" AND enthält außerdem Teilstring "C" |
dealName:("A B" C) |
dealName enthält Teilstring "A B" und enthält auch die Teilzeichenfolge "C". |
dealName:("A B" OR C D) |
dealName enthält entweder den Teilstring „A B“ oder "C" und enthält auch die Teilzeichenfolge "D". |
dealName:(NOT "A" B) |
dealName enthält den Teilstring „A“ nicht und enthält auch die Teilzeichenfolge "B". |
dealName:(NOT "A" OR "B") |
dealName enthält den Teilstring „A“ nicht oder Teilzeichenfolge "B" enthält. |