Filter

Die Ad Manager API unterstützt das Filtern nach List-Methoden. Die Syntax des Filterstrings ist in der EBNF-Grammatik formal definiert.

Im Folgenden finden Sie einige Beispiele für gängige Anwendungsfälle.

Beispiel Bedeutung
orders.updateTime > "2024-01-01T00:00:00-5:00" Listet Bestellungen mit einem updateTime nach dem 1. Januar 2024 in der Eastern Standard Time-Zeitzone auf
lineItems.targeting.geoTargeting.targetedGeoIds:2840 Listet Werbebuchungen mit geografischem Targeting auf, das die USA enthält (ID des geografischen Targetings 2480)
lineItems.displayName = "*_interstitial" Führt Werbebuchungen auf, deren Anzeigename mit dem String _interstitial endet
orders.displayName = "*video*" Hier werden Bestellungen mit einem Anzeigenamen aufgelistet, der den String video enthält.
displayName:"video" Listet Bestellungen auf, deren Anzeigename den String video enthält (alternative Syntax)

Literale

Ein einfacher Literalwert (z. B. 42, Hugo) ist ein Wert, mit dem verglichen werden soll. Allein stehende Literale werden mit allen unterstützten Feldern einer Ressource abgeglichen. In den Ressourcen wird dokumentiert, welche Felder bei der list-Methode für den Abgleich berücksichtigt werden. Diese Funktion ist mit der universellen Suche auf der Ad Manager-Benutzeroberfläche vergleichbar, aber auf einen einzelnen Ressourcentyp beschränkt.

Stringliterale, die Leerzeichen enthalten, müssen in doppelte Anführungszeichen gesetzt werden (Beispiel: "Foo bar"). Einfache Anführungszeichen können nicht zum Umschließen von Stringliteralen verwendet werden.

Logische Operatoren

Die Ad Manager API unterstützt die binären Operatoren AND und OR.

Operator Beispiel Bedeutung
AND a AND b „Wahr“, wenn a und b wahr sind.
OR a OR b OR c Wahr, wenn a, b oder c wahr sind.

Negationsoperatoren

Die Ad Manager API stellt die unären Operatoren NOT und - bereit. Diese können austauschbar verwendet werden.

Operator Beispiel Bedeutung
NOT NOT a „Wahr“, wenn a nicht wahr ist.
- -a "True", wenn a nicht "true" ist.

Vergleichsoperatoren

Die Ad Manager API unterstützt die binären Vergleichsoperatoren =, !=, <, >, <= und >= für String-, Zahlen-, Zeitstempel- und Dauerfelder.

Operator Beispiel Bedeutung
= a = true „Wahr“, wenn a „wahr“ ist.
!= a != 42 „Wahr“, es sei denn, a ist gleich 42.
< a < 42 "True", wenn a ein numerischer Wert kleiner als 42 ist.
> a > "foo" „True“, wenn a lexikalisch nach „foo“ sortiert ist.
<= a <= "foo" "True", wenn a "foo" oder lexisch davor steht.
>= a >= 42 "True", wenn a ein numerischer Wert von 42 oder höher ist.

Da Filter als Abfragestrings akzeptiert werden, erfolgt die Typkonvertierung, um den String in den entsprechenden stark typisierten Wert zu übersetzen:

  • Strings erwarten doppelte Anführungszeichen. Beispiel: "Foo bar".
  • Für Enums wird die Stringdarstellung des Enums erwartet (Groß-/Kleinschreibung wird beachtet).
  • Für boolesche Werte werden die Literalwerte true und false erwartet.
  • Für Zahlen werden die Standarddarstellungen für Ganzzahlen oder Gleitkommazahlen erwartet. Für Gleitkommazahlen werden Exponenten unterstützt. Beispiel: 2.997e9.
  • Für die Dauer wird eine numerische Darstellung gefolgt von einem s-Suffix (für Sekunden) erwartet. Beispiele: "20s", "1.2s".
  • Für Zeitstempel ist ein String im RFC-3339-Format erforderlich. Beispiel: "2012-04-21T11:30:00-04:00". Zeitzonenunterschiede zur UTC werden unterstützt.

Platzhalter

Beim Vergleichen von Strings unterstützt die Ad Manager API Platzhalter mit dem Zeichen *.

Beispiel Bedeutung
a = "*.foo" „Wahr“, wenn a mit „.foo“ endet.

Durchlaufoperator

Die Ad Manager API unterstützt den Operator ., der eine Durchlaufung einer Nachricht, Map oder Struktur angibt.

Beispiel Bedeutung
a.b = true „Wahr“, wenn a ein boolesches b-Feld mit dem Wert „wahr“ hat.
a.b > 42 „Wahr“, wenn a ein numerisches b-Feld hat, das größer als 42 ist.
a.b.c = "foo" „Wahr“, wenn a.b ein Stringfeld c mit dem Wert „foo“ hat.

Die Durchlaufanweisung wird mit den Feldnamen aus der Ressource geschrieben. Einzelne Dienste können eine Teilmenge der Felder angeben, die für die Durchsuchung unterstützt werden.

Mit Betreiber

Die Ad Manager API unterstützt den Operator :, was „enthält“ bedeutet. Sie kann mit Sammlungen (wiederkehrende Felder oder Karten), Nachrichten und Strings verwendet werden und verhält sich in jedem Fall etwas anders.

Stringfelder werden abgefragt, um zu prüfen, ob der String einen übereinstimmenden Teilstring enthält:

Beispiel Bedeutung
r.displayName:"_250x250" „Wahr“, wenn das Stringfeld r.displayName den Teilstring _250x250 enthält.

Mit wiederkehrenden Feldern wird geprüft, ob die wiederkehrende Struktur ein übereinstimmendes Element enthält:

Beispiel Bedeutung
r:42 „True“, wenn r 42 enthält.
r.foo:42 Wahr, wenn r ein Element e enthält, für das e.foo = 42 gilt.

Mithilfe von Maps, Structs und Nachrichten kann entweder das Vorhandensein eines Felds in der Karte oder ein bestimmter Wert abgefragt werden:

Beispiel Bedeutung
m:foo „True“, wenn m den Schlüssel „foo“ enthält.
m.foo:* „True“, wenn m den Schlüssel „foo“ enthält.
m.foo:42 Wahr, wenn m.foo = 42 ist.

Beim Durchlaufen von Nachrichten gilt ein Feld nur dann als vorhanden, wenn es einen anderen Wert als den Standardwert hat.

Beschränkungen

Für einzelne Dienste können zusätzlich zu den hier definierten Strukturen oder Einschränkungen für Filterabfragen weitere festgelegt werden.

Auftrag

Die Ad Manager API unterstützt die Sortierung nach List-Methoden. Die Syntax für orderBy-Felder ist eine durch Kommas getrennte Liste von Feldnamen. Beispiel: "foo,bar".

Die Standardsortierreihenfolge ist aufsteigend. Wenn Sie ein Feld absteigend sortieren möchten, hängen Sie das Suffix " desc" an. Beispiel: "foo desc, bar"

Überflüssige Leerzeichen in der Syntax werden ignoriert. Die Werte "foo, bar desc", " foo , bar desc " und "foo,bar desc" sind äquivalent.

Unterfelder werden mit dem Durchlaufoperator angegeben. Beispiel: foo.bar oder address.street.