Listenantworten filtern

Die meisten Dienste in der Display & Video 360 API bieten eine LIST-Methode zum Bulk-Abrufen von Ressourcen. Diese LIST-Methoden unterstützen in der Regel die Filterung von Ergebnissen über einen filter-Abfrageparameter. Mit diesem Parameter können Sie die API-Nutzung optimieren, indem Sie nur die Daten abrufen, die Sie benötigen.

In diesem Leitfaden erfahren Sie, wie Sie den Parameter filter effektiv verwenden.

Filterstruktur

Ein filter-Parameterwert ist ein String, der aus einer oder mehreren Einschränkungen besteht, die mit AND- oder OR-Operatoren kombiniert und mithilfe von Klammern gruppiert werden können.

Einschränkungen haben das Format {field} {operator} {value}. Hier ein Beispiel:

entityStatus="ENTITY_STATUS_ACTIVE"

Der Filterstring darf maximal 500 Zeichen lang sein. Wenn Ihr Filterstring mehr als 500 Zeichen hat, haben Sie folgende Möglichkeiten:

  • Teilen Sie die Logik in mehrere Filterstrings auf und rufen Sie die Ressourcen mithilfe separater LIST-Anfragen ab.
  • Entfernen Sie einen Teil der Logik aus dem Filterstring und verwenden Sie ihn, um die abgerufenen Ressourcen lokal zu filtern.

Setzen Sie die Werte für Einschränkungen in Anführungszeichen, damit die Logik richtig angewendet wird.

URL-codieren Sie Ihre Filterstrings, wenn Sie LIST-Aufrufe direkt ohne Clientbibliothek ausführen.

Weitere Informationen zur Formatierung von Abfragen finden Sie unter Logik zwischen Einschränkungen.

Filterbare Felder

Die filterbaren Felder der einzelnen LIST-Methoden sind in der Parameterbeschreibung filter der Methode aufgeführt. In den meisten Fällen können Sie nach einer Teilmenge der Standardfelder einer Ressource filtern. In seltenen Fällen gibt es zusätzliche Felder, die Sie nur zum Filtern verwenden können.

Jedes Feld in der Beschreibung des Parameters unterstützt mindestens einen der folgenden Vergleichsoperatoren:

Vergleichbare Betreiber
EQUALS (=) Der Wert des Ressourcenfelds entspricht dem angegebenen Wert.

Beispiel: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) Der Wert des Ressourcenfelds ist kleiner als oder gleich dem angegebenen Wert. Wird häufig beim Vergleichen von Datum oder Uhrzeit verwendet.

Beispiel: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) Der Wert des Ressourcenfelds ist größer als oder gleich dem angegebenen Wert. Wird häufig beim Vergleichen von Datum oder Uhrzeit verwendet.

Beispiel: updateTime>="2023-03-01T12:00:00Z"
HAS (:) Der Wert des Ressourcenfelds enthält den angegebenen Wert. Wenn das Ressourcenfeld ein String ist, wird geprüft, ob der angegebene Wert ein vorhandener Teilstring ist. Wenn das Ressourcenfeld ein Array ist, wird geprüft, ob das Array den angegebenen Wert enthält.

Beispiel: lineItemIds:"1234"

Wenn in der Parameterbeschreibung keine Operatoren für das Feld angegeben sind, können Sie nur den Operator EQUALS (=) verwenden. Einige Felder unterstützen mehrere Operatoren.

Bei einigen filterbaren Feldern, z. B. für Datumsangaben und Uhrzeiten, muss der Vergleichswert einem bestimmten Format entsprechen. Das Format wird in der Parameterbeschreibung für filter neben dem Feld angegeben.

Logik zwischen Einschränkungen

Sie können mehrere Einschränkungen kombinieren, um die Antwort auf Ihre LIST-Anfrage einzugrenzen oder zu erweitern.

Normalerweise können Sie mehrere Einschränkungen mit den logischen Operatoren AND und OR kombinieren. Für jede LIST-Methode wird angegeben, welche Operatoren unterstützt werden. Bei einigen Methoden ist nur eine Einschränkung im Parameter filter zulässig.

Beachten Sie die folgenden Einschränkungen, wenn Sie Filterstrings mit den logischen Operatoren AND oder OR erstellen:

  • AND muss zwischen Einschränkungen oder Gruppen von Einschränkungen verwendet werden, die verschiedene Felder oder dasselbe Feld unterschiedlich filtern. Beispiele:
    • updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE"
    • updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
  • OR muss zwischen einzelnen Einschränkungen verwendet werden, die nach demselben Feld filtern. Hier ein Beispiel:
    • (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")

  • Sie können OR nicht verwenden, um zwei Gruppen von Einschränkungen zu kombinieren. Verwenden Sie stattdessen mehrere LIST-Anfragen mit unterschiedlichen Filterwerten. Verwenden Sie beispielsweise die folgenden separaten LIST-Anfragen:

    • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
    • (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

    Verwenden Sie dazu nicht den Operator OR:

    (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

  • Klammern können impliziert werden, wenn Sie sie nicht verwenden, um Einschränkungen in einem Filterstring zu gruppieren. Beispiel:

    updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"

    wird interpretiert als:

    updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")