Die meisten Dienste in der Display & Video 360 API bieten eine LIST-Methode für den Bulk-Abruf von Ressourcen. Diese LIST-Methoden unterstützen in der Regel das Filtern von Ergebnissen über einen filter-Abfrageparameter. Verwenden Sie diesen Parameter, um die API-Nutzung zu optimieren, indem nur die benötigten Daten abgerufen werden.
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 den Operatoren AND oder OR kombiniert und in Klammern gruppiert werden können.
Die Einschränkungen werden im Format {field} {operator} {value} angegeben. Hier ein Beispiel:
entityStatus="ENTITY_STATUS_ACTIVE"
Der Filterstring darf nicht länger als 500 Zeichen sein. Wenn Ihr Filterstring länger als 500 Zeichen ist, führen Sie einen der folgenden Schritte aus:
- Teilen Sie die Logik in mehrere Filterstrings auf und rufen Sie die Ressourcen mit separaten
LIST-Anfragen ab. - Entfernen Sie einen Teil der Logik aus dem Filterstring und verwenden Sie sie, um die abgerufenen Ressourcen lokal zu filtern.
Setzen Sie die Einschränkungswerte in Anführungszeichen, damit die Logik korrekt angewendet wird.
Codieren Sie Ihre Filterstrings als URL, wenn Sie LIST-Aufrufe direkt ohne Verwendung einer Clientbibliothek ausführen.
Weitere Informationen zum Formatieren von Abfragen finden Sie unter Logik zwischen Einschränkungen.
Filterbare Felder
Die filterbaren Felder jeder LIST-Methode sind in der Beschreibung des filter-Parameters der Methode aufgeführt. In den meisten Fällen können Sie eine Teilmenge der Standardfelder einer Ressource filtern. In einigen 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 vergleichenden Operatoren:
| Vergleichbare Operatoren | ||
|---|---|---|
EQUALS (=)
|
Der Wert des Ressourcenfelds entspricht dem angegebenen Wert.
Beispiel: |
|
LESS THAN OR EQUAL TO (<=)
|
Der Wert des Ressourcenfelds ist kleiner oder gleich dem angegebenen Wert. Wird häufig beim Vergleich von Datum oder Datum verwendet.
Beispiel: |
|
GREATER THAN OR EQUAL TO (>=)
|
Der Wert des Ressourcenfelds ist größer oder gleich dem angegebenen Wert. Wird häufig beim Vergleich von Datum oder Datum verwendet.
Beispiel: |
|
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: |
|
Wenn für das Feld in der Beschreibung des Parameters keine Operatoren angegeben sind, können Sie nur den Operator EQUALS (=) verwenden. Einige Felder unterstützen mehrere Operatoren.
Für einige filterbare Felder, z. B. für Datum und Uhrzeit, muss der Vergleichswert einem bestimmten Format entsprechen. Das Format wird neben dem Feld in der Beschreibung des Parameters filter angegeben.
Logik zwischen Einschränkungen
Sie können mehrere Einschränkungen kombinieren, um die Antwort auf Ihre LIST-Anfrage einzugrenzen oder zu erweitern.
Sie können in der Regel mehrere Einschränkungen mit den logischen Operatoren AND und OR kombinieren. Jede LIST-Methode gibt an, welche Operatoren unterstützt werden.
Einige Methoden unterstützen nur die Verwendung einer einzigen Einschränkung im filter-Parameter.
Beachten Sie beim Erstellen von Filterstrings mit den logischen Operatoren AND oder OR die folgenden Einschränkungen:
ANDmuss für Einschränkungen oder Gruppen von Einschränkungen verwendet werden, die unterschiedliche Felder oder dasselbe Feld unterschiedlich filtern. Hier einige 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")
ORmuss 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")
Es ist nicht möglich, zwei Einschränkungsgruppen mit
ORzu kombinieren. Verwenden Sie stattdessen mehrereLIST-Anfragen mit unterschiedlichen Filterwerten. Verwenden Sie beispielsweise die folgenden separatenLIST-Anfragen:(lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")(lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")
Kombinieren Sie sie nicht mit dem 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 sein, wenn Sie sie nicht zum Gruppieren von Einschränkungen in einem Filterstring verwenden. Beispielsweise würde der folgende Filterstring:
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")