Filtruj żądania listy

list pobierają wiele zasobów określonego typu. Parametr zapytania filter umożliwia podanie kryteriów, które muszą spełniać pobrane zasoby.

Struktura filtra

Wartości parametru filter to ciągi tekstowe. Ciągi te składają się z co najmniej 1 kryterium. Kryteria są połączone operatorami AND lub OR.

Pojedyncze kryterium ma postać {field} {operator} {value}. Oto przykład:

  entityStatus="ENTITY_STATUS_ACTIVE"

Ciągi tekstowe filtrów mogą mieć maksymalnie 500 znaków. Jeśli ciąg znaków jest za długi:

  • Podziel logikę na osobne ciągi znaków. Wykonaj połączenie list z każdym filtrem string. Połącz wyniki w jedną listę.
  • Usuń kryteria z ciągu filtra. Użyj usuniętych kryteriów, aby lokalnie filtrować pobrane zasoby.

Wartości kryterium umieść w cudzysłowie.

Podczas bezpośredniego wywoływania interfejsu API upewnij się, że ciągi filtrów są zakodowane do użycia w adresie URL.

Więcej informacji o strukturze ciągu filtra znajdziesz w sekcji Kryteria łączenia.

Kryteria filtra

Każda metoda listy obsługuje określone kryteria filtrowania. Opis parametru filter metody zawiera te kryteria. Kryteria filtrowania są często podzbiorem pól pobranego zasobu.

Każde kryterium obsługuje co najmniej 1 operatora:

Porównywalni operatorzy
EQUALS (=)

Pole ma wartość równą podanej wartości.

Przykład: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=)

Pole ma wartość mniejszą lub równą podanej wartości. Często używane do filtrowania według daty lub daty i godziny.

Przykład: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=)

Pole ma wartość większą od podanej wartości lub jej równą. Często używane do filtrowania według daty lub daty i godziny.

Przykład: updateTime>="2023-03-01T12:00:00Z"
HAS (:)

Pole zawiera podaną wartość. Jeśli pole jest ciągiem znaków, sprawdzi, czy podana wartość jest podciągiem. Jeśli pole jest tablicą, sprawdzi, czy zawiera podaną wartość.

Przykład: lineItemIds:"1234"

Jeśli kryterium nie określa operatora, obsługuje tylko wartość EQUALS (=).

Kryterium będzie zawierać informację, czy wymaga specjalnego formatu.

Kryteria dołączenia

Połącz kilka kryteriów, aby jeszcze bardziej ograniczyć list odpowiedź.

Łącz kryteria za pomocą operatorów logicznych AND i OR. Każda metoda list określa, które z nich są obsługiwane. Niektóre metody obsługują tylko filtry z 1 kryterium.

Podczas korzystania z wielu kryteriów pamiętaj o tych limitach:

Ograniczenia i przykłady
AND musi łączyć ograniczenia lub grupy ograniczeń, które filtrują różne pola lub to samo pole w różny sposób. updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
OR musi łączyć poszczególne ograniczenia, które filtrują według tego samego pola. (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")
OR nie może łączyć dwóch grup ograniczeń. Zamiast tego użyj wielu żądań list z różnymi wartościami filtra. Te 2 ciągi tekstowe filtra muszą być używane w osobnych żądaniach i nie mogą być łączone za pomocą operatora OR:
  • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
  • (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")
Nawet jeśli nie są one uwzględnione, nawiasy mogą być domyślnie używane do grupowania ograniczeń. Ciąg filtra updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT" jest interpretowany jako updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")