Syntax und Verwendung von Listenfiltern

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

1. NOT
2. OR
3. 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.	1234,567 -789,0123
Ganzzahl	Alle Zahlen ohne Dezimalzeichen, mit oder ohne Vorzeichen („-“) wird als Ganzzahl behandelt.	1234 -789

String

In diesem Abschnitt werden die Typen beschrieben, die Sie als String-Literal in der Filtersyntax.

Hinweis: Ein Stringliteral kann sowohl in Anführungszeichen (" ") als auch ohne Anführungszeichen gesetzt werden. Sie können nicht einfache Anführungszeichen für ein Stringliteral. Beispiel: „ABC DEF“ und ABC DEF sind Stringliterale, aber ABC DEF nicht.

Typ	Definition	Beispiele
Boolesch	TRUE oder FALSE unabhängig von der Groß-/Kleinschreibung.	TRUE True "true"
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.	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

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.

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

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 denen name ein String mit folgendem Inhalt ist: "abcd"

Existenzprüfung

Wenn Sie den HAS-Operator mit dem Sonderzeichen * verwenden, sucht der Operator HAS auf Nicht-Null-Werte. Beispiel: name:* gibt alle Instanzen zurück, bei denen name nicht null, fehlt oder nicht definiert ist.

Der Operator HAS mit Nicht-String-Werten verhält sich wie den Operator EQUALS (=). Zum Beispiel verhält sich isCompleted:true in der wie bei isCompleted = true.

Wiederkehrende Felder

Sie können den Operator HAS (:) verwenden, um nach einer wiederkehrenden API-Ressource zu filtern ein, solange Folgendes zutrifft:

1. Es gibt nur eine wiederholte Komponente im Pfad der Feldkennungen
2. Die letzte Kennzeichnung des Feldpfads hat einen skalaren Typ

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

Beispiel:

item hat das Feld colors, das Stringwerte wie "red", "blue" und "yellow".

• item.colors:("red") gibt alle Elemente mit dem Wert "red" im Feld colors.
• item.colors:("red" "yellow") gibt alle Elemente zurück, die sowohl "red" als auch "yellow" im Feld colors.
• item.colors:("red" OR "yellow") gibt alle Elemente zurück, die "red" oder "yellow" im Feld colors.

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

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

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 = 93641	advertiserId mit dem Ganzzahlwert 93641.
isSetupComplete = true isSetupComplete:TRUE 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 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 das Angebot „Revision 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 OR BUYER_ACCEPTED ist.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = 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 = "Test1" OR dealName = "Test2"	dealName ist entweder gleich „Test1“ oder gleich "Test2" sein.
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 die Teilzeichenfolge „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" AND enthält außerdem Teilstring "C"
dealName:("A B" C) dealName:"A B" AND dealName:"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) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"	dealName enthält den Teilstring „A“ nicht und enthält auch die Teilzeichenfolge "B".
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	dealName enthält den Teilstring „A“ nicht oder Teilzeichenfolge "B" enthält.