Syntax und Verwendung von Listenfiltern

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. Ein expression 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:

1. NOT
2. OR
3. 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.	1234.567 -789.0123
Ganzzahl	Jede Zahl ohne Dezimalzeichen und ohne Vorzeichen („-“) wird als Ganzzahl behandelt.	1234 -789

String

In diesem Abschnitt werden die Typen beschrieben, die Sie in der Filtersyntax als Stringliteral schreiben können.

Hinweis: Ein Stringliteral kann in doppelten Anführungszeichen („ “) oder ohne Anführungszeichen stehen. Sie können ein Stringliteral nicht mit einfachen Anführungszeichen darstellen. Beispielsweise sind "ABC DEF" und "ABC DEF" Stringliterale, "ABC DEF" jedoch nicht.

Typ	Definition	Beispiele
Boolesch	TRUE oder FALSE unabhängig von der Groß-/Kleinschreibung.	TRUE True "true"
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.	name = "test \"double quotes\"" name=(ABC DEF) entspricht name=ABC AND name=DEF
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“.

Hinweis: Für Werte, die als Strings gespeichert sind, können Sie nur die Operatoren "!=", "=" und ":" verwenden. Beim Stringvergleich wird die Groß- und Kleinschreibung nicht berücksichtigt.

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 denen name ein String ist, der "abcd" enthält.

Existenzprüfung

Wenn Sie den Operator HAS mit dem Sonderzeichen * verwenden, sucht der Operator HAS nach Nicht-Null-Werten. name:* gibt beispielsweise alle Instanzen zurück, bei denen name 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 Operator EQUALS (=). Beispiel: isCompleted:true verhält sich auf dieselbe Weise wie isCompleted = true.

Wiederkehrende Felder

Sie können den Operator HAS (:) verwenden, um nach einem wiederkehrenden API-Ressourcenfeld zu filtern, sofern Folgendes zutrifft:

1. Entlang des Feldkennungspfads befindet sich nur eine wiederkehrende Komponente
2. Die letzte Kennung des Feldpfads ist vom Typ „Skalar“.

Das Filtern nach verschachtelten wiederkehrenden Feldern wird nicht unterstützt.

Beispiel:

item hat ein colors-Feld, das Stringwerte wie "red", "blue" und "yellow" enthält.

• item.colors:("red") gibt alle Elemente zurück, die im Feld colors den Wert "red" haben.
• item.colors:("red" "yellow") gibt alle Elemente zurück, bei denen im Feld colors sowohl "red" als auch "yellow" enthalten sind.
• item.colors:("red" OR "yellow") gibt alle Elemente zurück, bei denen "red" oder "yellow" im Feld colors enthalten ist.

item hat auch ein wiederkehrendes tools-Feld, das ein komplexes Objekt mit einem skalaren Feld shape 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.

Hinweis: Nicht alle wiederkehrenden Felder können gefiltert werden. Weitere Informationen zu einer bestimmten Ressource finden Sie in der Referenzdokumentation.

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 = 93641	advertiserId mit dem ganzzahligen Wert 93641.
isSetupComplete = true isSetupComplete:TRUE 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 displayName = "proposal" 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 != "proposal"	displayName ist nicht gleich „Angebot“.
proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED	proposalState hat einen enum-Wert, der entweder PROPOSED ODER BUYER_acceptED ist.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = 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 = "Test1" OR dealName = "Test2"	dealName ist entweder gleich „Test1“ oder gleich „Test2“.
dealName:*	dealName is not null.
dealName:"test" dealName:test	dealName enthält den Teilstring „test“.
dealName:("A B") dealName:"A B"	dealName enthält den Teilstring „A B“.
dealName:(A B) dealName:"A" AND dealName:"B"	dealName enthält den Teilstring „A“ und den Teilstring „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 enthält entweder den Teilstring „A“ ODER „B“ UND enthält auch den Teilstring „C“
dealName:("A B" C) dealName:"A B" AND dealName:"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) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"	dealName enthält nicht den Teilstring „A“, sondern auch Teilstring „B“.
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	„dealName“ enthält nicht Teilstring „A“ oder Teilstring „B“.