Filter

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

Hier sind einige Beispiele für häufige 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 Zone auf
lineItems.targeting.geoTargeting.targetedGeoIds:2840 Listet Werbebuchungen mit geografischem Targeting auf, das die USA umfasst (ID für geografisches Targeting 2480)
lineItems.displayName = "*_interstitial" Listet Werbebuchungen auf, deren Anzeigename mit dem String _interstitial endet
orders.displayName = "*video*" Listet Aufträge auf, deren Anzeigename den String video enthält
displayName:"video" Listet Aufträge auf, deren Anzeigename den String video (alternative Syntax) enthält

Literale

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

Stringliterale mit Leerzeichen müssen in doppelte Anführungszeichen gesetzt werden (Beispiel: "Foo bar"). Einfache Anführungszeichen können nicht zum Umbrechen von Stringliteralen verwendet werden.

Logische Operatoren

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

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

Negationsoperatoren

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

Betreiber Beispiel Bedeutung
NOT NOT a „True“, wenn a nicht wahr ist.
- -a „True“, wenn a nicht wahr ist.

Vergleichsoperatoren

Die Ad Manager REST API unterstützt die binären Vergleichsoperatoren =, !=, <, >, <= und >= für die Felder „String“, „numerisch“, „Zeitstempel“ und „Dauer“.

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

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

  • Zeichenfolgen erwarten doppelte Anführungszeichen. Beispiel: "Foo bar".
  • Bei Enums wird die Stringdarstellung des Enum erwartet (Groß-/Kleinschreibung beachten).
  • Boolesche Werte erwarten true- und false-Literalwerte.
  • Zahlen erwarten die Standarddarstellungen von Ganzzahlen oder Gleitkommazahlen. 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".
  • Zeitstempel erwarten einen RFC-3339-formatierten String. Beispiel: "2012-04-21T11:30:00-04:00". UTC-Offsets werden unterstützt.

Platzhalter

Beim Vergleich von Strings auf Gleichheit unterstützt die Ad Manager REST API Platzhalter mit dem Zeichen *.

Beispiel Bedeutung
a = "*.foo" Dieser Wert ist „True“, wenn a mit „.foo“ endet.

Durchlaufoperator

Die Ad Manager REST API unterstützt den .-Operator, der angibt, dass eine Nachricht, eine Karte oder eine Struktur durchlaufen werden kann.

Beispiel Bedeutung
a.b = true „True“, wenn a ein boolesches b-Feld hat, das wahr ist.
a.b > 42 Wahr, wenn a ein numerisches b-Feld hat, das größer als 42 ist.
a.b.c = "foo" True, wenn a.b das String-Feld c enthält, das „foo“ ist.

Der Durchlauf wird unter Verwendung der Feldnamen aus der Ressource geschrieben. Einzelne Dienste können eine Teilmenge von Feldern angeben, die für den Durchlauf unterstützt werden.

Hat Operator

Die Ad Manager REST API unterstützt den :-Operator. Das bedeutet „enthält“. Sie kann mit Sammlungen (wiederholten Feldern oder Karten), Nachrichten und Strings verwendet werden und verhält sich jeweils etwas unterschiedlich.

Stringfelder abfragen, um zu sehen, ob der String einen übereinstimmenden Teilstring enthält:

Beispiel Bedeutung
r.displayName:"_250x250" True, wenn das String-Feld r.displayName den Teilstring _250x250 enthält.

Abfrage von wiederkehrenden Feldern, um festzustellen, ob die wiederkehrende Struktur ein übereinstimmendes Element enthält:

Beispiel Bedeutung
r:42 „True“, wenn r 42 enthält.
r.foo:42 True, wenn r ein Element e mit e.foo = 42 enthält.

Zuordnungen, Strukturen und Meldungen können entweder das Vorhandensein eines Felds in der Karte oder einen bestimmten Wert abfragen:

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 „True“, wenn m.foo 42 ist.

Beim Durchlauf von Nachrichten wird davon ausgegangen, dass ein Feld nur dann vorhanden ist, wenn es einen anderen Wert als den Standardwert hat.

Beschränkungen

Einzelne Dienste können zusätzlich zu den hier definierten Funktionen eine weitere Struktur oder Einschränkungen für Filterabfragen angeben.

Auftrag

Die Ad Manager REST 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 standardmäßige Sortierreihenfolge ist aufsteigend. Wenn Sie für ein Feld eine absteigende Reihenfolge festlegen möchten, hängen Sie das Suffix " desc" an. Beispiel: "foo desc, bar"

Redundante Leerzeichen in der Syntax werden ignoriert. Die Werte "foo, bar desc", " foo , bar desc " und "foo,bar desc" sind alle gleichwertig.

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