Mit list-Methoden werden mehrere Ressourcen eines bestimmten Typs abgerufen. Mit dem Abfrageparameter filter können Sie Kriterien angeben, die die abgerufenen Ressourcen erfüllen müssen.
Filterstruktur
filter-Parameterwerte sind Strings. Diese Strings bestehen aus einem oder mehreren Kriterien. Kriterien werden mit den Operatoren AND oder OR verknüpft.
Ein einzelnes Kriterium hat die Form {field} {operator} {value}. Beispiel:
entityStatus="ENTITY_STATUS_ACTIVE"
Filterstrings sind auf 500 Zeichen begrenzt. Wenn Ihr String zu lang ist:
- Teilen Sie die Logik in separate Strings auf. Rufen Sie
listmit jedem Filterstring auf. Kombinieren Sie die Ergebnisse zu einer einzigen Liste. - Entfernen Sie Kriterien aus dem Filterstring. Verwenden Sie die entfernten Kriterien, um die abgerufenen Ressourcen lokal zu filtern.
Schließen Sie Werte für ein Kriterium in Anführungszeichen ein.
Achten Sie darauf, dass Ihre Filterstrings für die Verwendung in einer URL codiert sind, wenn Sie API-Aufrufe direkt ausführen.
Weitere Informationen zur Struktur von Filterstrings finden Sie im Abschnitt Join-Kriterien.
Filterkriterien
Jede Listenmethode unterstützt bestimmte Filterkriterien. Die Beschreibung für die filter-Parameter der Methode enthält diese Kriterien. Filterkriterien sind oft eine Teilmenge der Felder der abgerufenen Ressource.
Für jedes Kriterium werden ein oder mehrere Operatoren unterstützt:
| Vergleichbare Operatoren | |
|---|---|
EQUALS (=)
|
Das Feld entspricht dem angegebenen Wert. Beispiel: |
LESS THAN OR EQUAL TO (<=)
|
Der Wert des Felds ist kleiner als oder gleich dem angegebenen Wert. Wird häufig verwendet, um nach einem Datum oder einer Datums-/Uhrzeitangabe zu filtern. Beispiel: |
GREATER THAN OR EQUAL TO (>=)
|
Das Feld ist größer als oder gleich dem angegebenen Wert. Wird häufig verwendet, um nach einem Datum oder einer Datums-/Uhrzeitangabe zu filtern. Beispiel: |
HAS (:)
|
Das Feld enthält den angegebenen Wert. Wenn das Feld ein String ist, wird geprüft, ob der angegebene Wert ein Teilstring ist. Wenn das Feld ein Array ist, wird das Array auf den angegebenen Wert geprüft. Beispiel: |
Wenn für ein Kriterium kein Operator angegeben ist, wird nur EQUALS (=) unterstützt.
Bei einem Kriterium wird angegeben, ob ein spezielles Format erforderlich ist.
Teilnahmevoraussetzungen
Sie können mehrere Kriterien kombinieren, um die Antwort von list weiter einzuschränken.
Verknüpfen Sie Kriterien mit den logischen Operatoren AND und OR. In jeder list-Methode wird angegeben, welche unterstützt werden. Einige Methoden unterstützen nur Filter mit einem Kriterium.
Beachten Sie bei der Verwendung mehrerer Kriterien die folgenden Einschränkungen:
| Einschränkungen und Beispiele | |
|---|---|
In AND müssen Einschränkungen oder Gruppen von Einschränkungen kombiniert werden, die unterschiedliche Felder oder dasselbe Feld auf unterschiedliche Weise filtern.
|
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 einzelne Einschränkungen kombinieren, die nach demselben Feld filtern.
|
(entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")
|
OR kann zwei Gruppen von Einschränkungen nicht kombinieren. Verwenden Sie stattdessen mehrere list-Anfragen mit unterschiedlichen Filterwerten.
|
Die folgenden beiden Filterstrings müssen in separaten Anfragen verwendet werden und dürfen nicht mit dem Operator OR kombiniert werden:
|
| Klammern können impliziert werden, um Einschränkungen zu gruppieren, auch wenn sie nicht enthalten sind. |
Der Filterstring updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT" wird als updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT") interpretiert.
|