Spezifikation der Prüfung

Der Hauptzweck der evaluation_spec einer Regel ist die Bestimmung der Objekte, bei denen die Regel ihre Handlung ausführen soll. Der evaluation_type bestimmt die Art der Prüfmethode. Dafür gibt es die folgenden Optionen:

Die evaluation_spec enthält ein filters-Array, mit dem du die Liste der abgeglichenen Objekte weiter eingrenzen kannst. Du kannst beispielsweise nach Werbeanzeigen-, Anzeigengruppen- und Kampagnen-Metadaten und Insights-Kennzahlen filtern. Alle Filter werden gemeinsam mit dem AND-Operator geprüft.

Das filters-Array enthält eine Liste von Filterobjekten. Diese Objekte sind Verzeichnisse mit den Schlüsseln field, value und operator:

Für jeden Filter gibt es eine Liste der unterstützten logischen Operatoren. Hier siehst du die logischen Operatoren, die in SCHEDULE- und TRIGGER-Regeln unterstützt werden:

Die evaluation_spec benötigt einen trigger für die Prüfungsart TRIGGER. Der Trigger enthält eine Art und eine zugrunde liegende Filterspezifikation. Die Filterspezifikation kann field, value oder operator lauten.

Der Trigger bestimmt dynamisch, ob eine Regel geprüft werden soll. Außerdem kannst du nur einen Trigger verwenden. Im Abschnitt Trigger-basierte Regeln findest du weitere Informationen.

Unten definieren wir einige besondere Filter sowie allgemeine Gruppen von verwendbaren Filtern.

Besondere Filter

time_preset

Der time_preset-Filter bestimmt den Zeitraum, in dem wir Insights-Kennzahlen sammeln. Derzeit ist nur ein time_preset zulässig. Die Einstellung gilt für alle Statistikfilter in der Regel. Das schließt gegebenenfalls auch den Filter ein, der für den Trigger verwendet wird.

Als Operator für time_preset wird nur EQUAL unterstützt. Er ist erforderlich, wenn ein Insights-Filter oder Trigger vorhanden ist. Trigger-basierte Regeln unterstützen nur Zeitvoreinstellungen, die TODAY enthalten, da die Prüfung in Echtzeit stattfindet.

Zeitvoreinstellungen für Regeln können ein anderes Verhalten aufweisen als bei anderen Oberflächen. Einige der Zeitvoreinstellungen hier beziehen den heutigen Tag mit ein. Das liegt daran, dass die Daten von heute für Regeln, die häufiger als einmal täglich angewendet werden, äußerst wichtig sind. In anderen Oberflächen bezieht der Voreinstellungswert LAST_N_DAYS meist nicht die Daten von heute ein. Weitere Details findest du in den folgenden Beschreibungen.

{
  "field": "time_preset",
  "value": "TODAY",
  "operator": "EQUAL"
}

attribution_window

Der attribution_window-Filter bestimmt das Zeitfenster in der Vergangenheit, für das Insights-Kennzahlen gesammelt werden. Weitere Informationen findest du in der Insights-Dokumentation zu Attributionsfenstern.

Derzeit lassen wir nur ein attribution_window zu, das für alle Statistikfilter in der Regel gilt. Der einzige unterstützte Operator für attribution_window ist EQUAL. Er wird nur für zeitplanbasierte Regeln unterstützt.

Ob angegeben oder nicht, der einzige zulässige value für attribution_window ist ACCOUNT_DEFAULT.

{
  "field": "attribution_window",
  "value": "ACCOUNT_DEFAULT",
  "operator": "EQUAL"
}

Metadatenfilter

Mit Metadatenfiltern kannst du Objekte anhand des aktuellen Status ihrer Metadatenfelder filtern. Dabei werden auch mehrere Filterebenen unterstützt, sodass du mit Präfixen einen Metadatenfilter auf das übergeordnete Objekt oder dessen übergeordnetes Objekt anwenden kannst. Andere Filter sind davon nicht betroffen. Insights-Filter werden weiterhin auf das eigentliche Objekt angewendet.

Wenn du beispielsweise eine Regel erstellen möchtest, die für Anzeigengruppen in Kampagnen mit dem Ziel WEBSITE_CLICKS gilt, kannst du zwei Filter verwenden:

 "filters" : [
  {
    "field": "entity_type",
    "value": "ADSET",
    "operator": "EQUAL",
  },
  {
    "field": "campaign.objective",
    "value": "WEBSITE_CLICKS",
    "operator": "EQUAL"
  }
]

Metadatenfilter, die von Trigger- und zeitplanbasierten Regeln unterstützt werden

Metadatenfilter, die nur von zeitplanbasierten Regeln unterstützt werden

entity_type und id

Für jede Regel mit der Prüfart SCHEDULE oder TRIGGER musst du einen entity_type- oder id-Filter angeben.

Wenn du einen entity_type-Filter angibst, legst du eine dynamische Objektebene fest, auf der die Regel angewendet wird. Wenn entity_type beispielsweise AD lautet, prüft diese Regel automatisch jede neue Werbeanzeige, die dem Werbekonto hinzugefügt wird. Dieser Vorgang findet unabhängig davon statt, wann du die Regel erstellst. Wenn du einen id-Filter angibst, wird die Regel nur auf Objekte aus einer statischen Liste angewendet.

Wenn du einen id-Filter ohne Präfix angibst, berechnen wir automatisch die Objektebene, auf der die Regel angewendet wird. Wenn du beispielsweise eine Regel auf die Werbeanzeigen [123, 456] anwenden möchtest, benötigst du nur einen Filter mit dem Feld id, dem Wert [123, 456] und dem Operator IN. In diesem Fall benötigst du keinen entity_type-Filter, da du eine statische Objektliste angegeben hast und wir aus diesen Objekten die Objektebene berechnen können.

Du kannst entity_type und id zusammen mit der Filterung auf mehreren Ebenen verwenden. Wenn du beispielsweise eine Regel erstellen möchtest, die für alle Anzeigen in einigen bestimmten Anzeigengruppen gilt, kannst du den entity_type-Filter AD und einen adset.id-Filter mit den gewünschten Anzeigengruppen nutzen.

Wenn du keinen effective_status-Filter angibst, fügen wir standardmäßig einen impliziten effective_status-Filter hinzu, wenn wir die Regel prüfen.

Für alle Ausführungsarten, die für aktive Objekte gelten, hat dieser Standardfilter den Operator IN und den Wert ['ACTIVE', 'PENDING_REVIEW']. Das bedeutet, dass die Regel nur Objekte prüft, die eine aktive Auslieferung haben oder haben werden. Für Ausführungsarten, die nicht mit aktiven Objekten ausgeführt werden (UNPAUSE), fügen wir diesen Filter mit dem Operator NOT_IN und dem Wert ['DELETED', 'ARCHIVED'] hinzu. Der Standardfilter ist eine interne Optimierung für unsere Ausführungsarten.

Insights-Filter

Wir vergleichen Insights-Filter mit den aktuellen Werten, die von der Insights API für eine bestimmte time_preset zurückgegeben werden. Diese Filter werden direkt auf die Objektliste bzw. -ebene angewendet und unterstützen nicht mehrere Filterebenen. Alle Insights-Filter unterstützen die folgenden Operatoren: GREATER_THAN, LESS_THAN, EQUAL, IN_RANGE, NOT_IN_RANGE.

In den Insights API-Dokumenten findest du eine Beschreibung der einzelnen Felder. All diese Filter werden von zeitplanbasierten Regeln unterstützt.

Unten findest du eine Liste mit Insights-Filtern und der Angabe, ob sie von Trigger-basierten Regeln unterstützt werden:

Erweiterte Filter

Du kannst erweiterte Filter basierend auf den oben genannten Insights- und Metadatenfiltern anpassen und ableiten. Mehr dazu erfährst du unter Erweiterte Prüfungsspezifikationsfilter.

Erweiterte Filter unterstützen die folgenden Operatoren: GREATER_THAN, LESS_THAN, EQUAL, IN_RANGE, NOT_IN_RANGE. Sie werden nur von zeitplanbasierten Regeln unterstützt.

Für einige der am häufigsten verwendeten erweiterten Filter unterstützen wir einen Alias als Filter: