In diesem Leitfaden werden die Syntax der Listenfilter und das Filtern verschiedener Ressourcentypen beschrieben.
Einige API-Methoden unterstützen einen Filter, um die in der Antwort zurückgegebenen Ressourcen zu begrenzen.
Zusammenfassung
Dieser Abschnitt bietet einen kurzen Überblick über die Syntaxstruktur von Listenfiltern.
Ein Filter ist ein String, der ein
expression
enthält. Einexpression
ist eine boolesche Kombination von Vergleichen:expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )
Ein
comparison
entspricht einem Ressourcenfeld mit einem Wert. Sie können alle gängigen Vergleichsoperatoren verwenden.comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
Der
has
-Operator, ein Doppelpunkt (:
), kann für Strings und wiederkehrende Felder verwendet werden. Weitere Informationen finden Sie im Abschnitt Has-Operator.Sie können die folgenden Werttypen in Filtern verwenden:
- Numbers
- Strings
- Ausdrücke in Klammern
value = number| string | "*" | "(" expression ")"
Strings können Folgendes darstellen:
- Beliebiger Text
- Boolesche Werte
- 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 gleichwertig:
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. Die folgenden Filter sind beispielsweise identisch:
c=d AND e=f
c=d e=f
Sie können den Bindestrich (-
) anstelle von NOT
verwenden. Zwischen dem Bindestrich (-
) und dem folgenden Vergleich darf kein Leerzeichen stehen. Die folgenden Filter sind beispielsweise identisch:
NOT e=f
-e=f
Vergleiche
In diesem Abschnitt werden "name OP value"
-Vergleiche so beschrieben:
comparison = name OP value
wobei
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 dieses Feld. Angenommen, eine Ressource hat ein komplexes Feld item
und ein weiteres komplexes Feld tool
mit einem Feld namens shape
. In einem Filter für diese Ressource verweisen Sie auf die Form mit dem Namen item.tool.shape
.
Auf der rechten Seite steht normalerweise ein skalarer Wert, der in den Feldtyp umgewandelt und damit verglichen wird. Weitere Informationen finden Sie im Abschnitt Wertliterale.
Die rechte Seite eines Vergleichs kann auch als in Klammern gesetzte boolesche Kombination von Literalwerten und/oder booleschen Ausdrücken ausgedrückt werden, die nur Literalwerte (mit oder ohne NOT
vorangestellt) enthält. Der Name auf der linken Seite und der Vergleichsoperator werden auf jeden der Werte angewendet. Die folgenden Filter sind beispielsweise identisch:
deal.name = ("test 1" OR "test 2")
deal.name = "test 1" OR deal.name = "test 2"
Hier 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 kategorisiert werden.
Zahl
In diesem Abschnitt wird die Darstellung numerischer Literale beschrieben.
Typ | Definition | Beispiele |
---|---|---|
Doppelwert | Jede Zahl, die ein Dezimalzeichen enthält, mit oder ohne Vorzeichen („-“), wird als Double behandelt. |
|
Ganzzahl | Jede Zahl ohne Dezimalzeichen und ohne Vorzeichen („-“) wird als Ganzzahl behandelt. |
|
String
In diesem Abschnitt werden die Typen beschrieben, die Sie in der Filtersyntax als Stringliteral schreiben können.
Typ | Definition | Beispiele |
---|---|---|
Boolesch | TRUE oder FALSE unabhängig von der Groß-/Kleinschreibung. |
|
Enum | Der Name eines Aufzählungstyp-Literals. 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 nach dem Aufteilen des Strings durch Leerzeichen als implizites "AND" unter allen Wörtern behandelt. |
|
Zeitstempel | Ein String im ISO8601-Standardformat. |
"2014-10-02T15:01:23.045Z"
|
Vergleichsoperatoren
Vergleichsoperatoren:
- Kleiner als oder gleich:
"<="
- Kleiner als:
"<"
- Größer als oder gleich:
">="
- Größer als:
">"
- Ungleich:
"!="
- Gleich:
"="
- Enthält:
":"
Diese Operatoren gelten für Werte vom Typ „Double“, „Ganzzahl“, „Boolesch“, „Enum“ und „Zeitstempel“.
Hat Operator
Sie können den Operator HAS
(:
) für spezielle Operationen in den folgenden Feldern verwenden:
- Teilstrings
- Wenn der Operator
HAS
zum Vergleich von Werten in einer Stringspalte mit einem String verwendet wird, fungiert der Operator als Teilstring-Vorgang. Beispiel:name:"abcd"
gibt alle Instanzen zurück, bei denenname
ein String ist, der"abcd"
enthält. - Existenzprüfung
- Wenn Sie den Operator
HAS
mit dem Sonderzeichen*
verwenden, sucht der OperatorHAS
nach Nicht-Null-Werten.name:*
gibt beispielsweise alle Instanzen zurück, bei denenname
nicht null ist, fehlt oder nicht definiert ist. - Wenn Sie den Operator
HAS
mit Werten verwenden, die keine Stringwerte sind, verhält er sich genauso wie der OperatorEQUALS
(=
). Beispiel:isCompleted:true
verhält sich auf dieselbe Weise wieisCompleted = true
. - Wiederkehrende Felder
Sie können den Operator
HAS
(:
) verwenden, um nach einem wiederkehrenden API-Ressourcenfeld zu filtern, sofern Folgendes zutrifft:- Entlang des Feldkennungspfads befindet sich nur eine wiederkehrende Komponente
- Die letzte Kennung des Feldpfads ist vom Typ „Skalar“.
Das Filtern nach verschachtelten wiederkehrenden Feldern wird nicht unterstützt.
Beispiel:
item
hat eincolors
-Feld, das Stringwerte wie"red"
,"blue"
und"yellow"
enthält.item.colors:("red")
gibt alle Elemente zurück, die im Feldcolors
den Wert"red"
haben.item.colors:("red" "yellow")
gibt alle Elemente zurück, bei denen im Feldcolors
sowohl"red"
als auch"yellow"
enthalten sind.item.colors:("red" OR "yellow")
gibt alle Elemente zurück, bei denen"red"
oder"yellow"
im Feldcolors
enthalten ist.
item
hat auch ein wiederkehrendestools
-Feld, das ein komplexes Objekt mit einem skalaren Feldshape
ist, dessen Werte"square"
oder"round"
sein können.item.tools.shape:("square")
gibt alle Elemente mit Tools in"square"
-Form zurück.item.tools.shape:("square" "round")
gibt alle Elemente zurück, die sowohl ein"square"
-förmiges Tool als auch ein"round"
-förmiges Tool haben.item.tools.shape:("square" OR "round")
gibt alle Elemente mit einem"square"
-Form-Tool oder einem"round"
-Form-Tool zurück.
Nicht ausgefüllte verschachtelte Felder
Verschachtelte Felder sind untergeordnete Felder von Feldern auf Stammebene. Beispielsweise ist shape
in item.tools.shape
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 Filtern (!=
) nicht zurückgegeben.
Beispiel:
item.tools
hat eine size
-Enum, deren Wert auf "SMALL"
, "MEDIUM"
oder "LARGE"
festgelegt werden kann.
Sie haben folgende Artikel:
{
"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:
{
"items": [
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
}
]
}
Da item.tools.size
nicht für item3
festgelegt wurde, gibt der negative Filter nicht das item3
-Objekt zurück.
Beispiele
Beispiel | Beschreibung |
---|---|
externalDealId = "123456789" |
externalDealId mit dem Stringwert „123456789“. |
advertiserId:93641 |
advertiserId mit dem ganzzahligen Wert 93641. |
isSetupComplete = true |
isSetupComplete ist gleich TRUE. |
updateTime > "2018-02-14T11:09:19.378Z" |
updateTime liegt nach dem 14.02.2018 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 „Angebotsrevision“ ist gleich 3. |
NOT displayName = "proposal" |
displayName ist nicht gleich „Angebot“. |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState hat einen enum-Wert, der entweder PROPOSED ODER BUYER_acceptED ist. |
proposalState = (PROPOSED AND BUYER_ACCEPTED) |
Der enum-Wert für proposalState entspricht PROPOSED AND CUSTOMER_acceptED. |
dealName = Test Deal |
INVALID -Ausdruck |
dealName = "Test Deal" |
dealName ist gleich „Test-Deal“. |
dealName = (Test Deal) |
dealName ist gleich „Test“ und auch „Deal“. |
dealName = ("Test1" OR "Test2") |
dealName ist entweder gleich „Test1“ oder gleich „Test2“. |
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 den Teilstring „B“. |
dealName:("A" OR "B" AND "C") |
dealName enthält entweder den Teilstring „A“ ODER „B“ UND enthält auch den Teilstring „C“ |
dealName:("A B" C) |
dealName enthält den Teilstring „A B“ und auch den Teilstring „C“. |
dealName:("A B" OR C D) |
dealName enthält entweder den Teilstring „A B“ oder „C“ und auch den Teilstring „D“. |
dealName:(NOT "A" B) |
dealName enthält nicht den Teilstring „A“, sondern auch Teilstring „B“. |
dealName:(NOT "A" OR "B") |
„dealName “ enthält nicht Teilstring „A“ oder Teilstring „B“. |