Filter

Die Ad Manager API unterstützt das Filtern nach List-Methoden. Die Syntax von 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 einer updateTime nach dem 1. Januar 2024 in der Eastern Standard Time-Zeitzone auf
lineItems.targeting.geoTargeting.targetedGeoIds:2840	Listet Werbebuchungen mit geografischem Targeting auf, die die USA (ID für geografische Ziele 2480) enthalten.
lineItems.displayName = "*_interstitial"	Werbebuchungen mit einem Anzeigenamen, der auf den 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)

Tipp :Filter müssen für GET-Anfragen URL-codiert sein. Beispiel: Filterstring: orders.updateTime > "2024-01-01T00:00:00-5:00", URL-codiert: orders.updateTime%20%3E%20%222024-01-01T00:00:00-5:00%22. Dies wird automatisch von Clientbibliotheken erledigt.

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 in der Ad Manager-Benutzeroberfläche vergleichbar, aber auf einen einzelnen Ressourcentyp beschränkt.

Stringliterale mit Leerzeichen müssen in doppelte Anführungszeichen gesetzt werden (Beispiel: "Foo bar"). Sie können nicht in einfache Anführungszeichen gesetzt werden.

Logische Operatoren

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

Achtung: Bei diesen Operatoren wird zwischen Groß- und Kleinschreibung unterschieden. Die Literale and und or werden als Literale behandelt.

Operator	Beispiel	Bedeutung
AND	a AND b	„Wahr“, wenn a und b „wahr“ sind.
OR	a OR b OR c	„Wahr“, wenn mindestens einer der Werte a, b oder c wahr ist.

Hinweis :Der Operator OR hat im Gegensatz zu den meisten Programmiersprachen eine höhere Priorität als AND, um gängige Sprachmuster zu erkennen. Der Ausdruck a AND b OR c ergibt a AND (b OR c). Verwenden Sie nach Möglichkeit Klammern, um Verwirrung zu vermeiden.

Negationsoperatoren

Die Ad Manager API bietet die unaryn Operatoren NOT und -. Sie können austauschbar verwendet werden.

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

Vergleichsoperatoren

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

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

Hinweis: Anders als in den meisten Programmiersprachen müssen Feldnamen auf der linken Seite eines Vergleichsoperators stehen. Auf der rechten Seite sind nur Literale und logische Operatoren zulässig.

Da Filter als Suchstrings akzeptiert werden, erfolgt eine Typkonvertierung, um den String in den entsprechenden stark typisierten Wert umzuwandeln:

• Strings müssen in doppelte Anführungszeichen gesetzt werden. 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. Bei Gleitkommazahlen werden Exponenten unterstützt. Beispiel: 2.997e9.
• Für die Dauer ist eine numerische Darstellung mit dem Suffix s (für Sekunden) erforderlich. Beispiele: "20s", "1.2s".
• Für Zeitstempel ist ein String im Format RFC-3339 erforderlich. Beispiel:"2012-04-21T11:30:00-04:00". Zeitzonenunterschiede zur UTC-Zeit werden unterstützt.

Achtung: Die Kennungen true, false und null haben nur dann eine inhärente Bedeutung, wenn sie im Kontext einer typisierten Feldreferenz verwendet werden.

Platzhalter

Beim Vergleichen von Strings auf Gleichheit 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 die 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.

Wichtig: Der Operator . kann nicht verwendet werden, um ein wiederholtes Feld oder eine wiederholte Liste zu durchsuchen, es sei denn, er wird speziell mit dem Operator : verwendet.

Mit Betreiber

Die Ad Manager API unterstützt den Operator :, der für „hat“ steht. 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	„Wahr“, wenn r die Zahl 42 enthält.
r.foo:42	Wahr, wenn r ein Element e enthält, für das e.foo = 42 gilt.

Wichtig :Mit Filtern können Sie nicht nach einem Wert für ein bestimmtes Element in einem wiederkehrenden Feld suchen. e.0.foo = 42 und e[0].foo = 42 sind beispielsweise nicht gültige Filter.

Bei Zuordnungen, Strukturen und Nachrichten kann entweder nach dem Vorhandensein eines Felds in der Zuordnung oder nach einem bestimmten Wert gesucht 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.

Bei der Durchsuchung von Nachrichten wird ein Feld nur dann als vorhanden betrachtet, 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 meisten Ressourcen unterstützen die Sortierung nach List-Methoden. Weitere Informationen zum genauen Verhalten der Ressource und zu den für die Sortierung unterstützten Feldern findest du in der Dokumentation der List-Methode.

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.