Filtruj odpowiedzi na liście

Większość usług dostępnych w interfejsie Display & Video 360 API zapewnia metodę LIST do zbiorczego pobierania zasobów. Te metody LIST zwykle obsługują filtrowanie wyników za pomocą parametru zapytania filter. Użyj tego parametru, aby zoptymalizować wykorzystanie interfejsu API przez pobieranie tylko tych danych, które są Ci potrzebne.

Z tego przewodnika dowiesz się, jak skutecznie korzystać z parametru filter.

Struktura filtra

Wartość parametru filter jest ciągiem znaków zawierającym co najmniej jedno ograniczenie, które można łączyć za pomocą operatorów AND lub OR i grupować za pomocą nawiasów.

Ograniczenia mają postać {field} {operator} {value}. Oto przykład:

entityStatus="ENTITY_STATUS_ACTIVE"

Długość ciągu filtra nie może przekraczać 500 znaków. Jeśli ciąg filtra przekracza 500 znaków, wykonaj jedną z tych czynności:

  • Podziel logikę na kilka ciągów filtra i pobierz zasoby za pomocą oddzielnych żądań LIST.
  • Usuń część logiki z ciągu filtra i użyj jej do lokalnego filtrowania pobranych zasobów.

Zawijaj wartości ograniczeń w cudzysłowy, aby mieć pewność, że logika jest stosowana prawidłowo.

Zakoduj ciągi filtrów w adresie URL, jeśli wykonujesz wywołania LIST bezpośrednio bez korzystania z biblioteki klienta.

Więcej informacji o formatowaniu zapytań znajdziesz w sekcji Logika między ograniczeniami.

Pola możliwe do filtrowania

Pola możliwe do filtrowania w każdej metodzie LIST są wymienione w opisie parametru filter metody. W większości przypadków możesz filtrować podzbiór standardowych pól zasobu. W rzadkich przypadkach istnieją dodatkowe pola, których możesz używać tylko do filtrowania.

Każde pole w opisie parametru obsługuje co najmniej 1 z tych porównywalnych operatorów:

Operatory porównywalne
EQUALS (=) Wartość pola zasobu jest równa podanej wartości.

Przykład: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) Wartość w polu zasobu jest mniejsza od podanej wartości lub jej równa. Ta opcja jest często używana do porównywania daty lub daty i godziny.

Przykład: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) Wartość w polu zasobu jest większa od podanej wartości lub jej równa. Ta opcja jest często używana do porównywania daty lub daty i godziny.

Przykład: updateTime>="2023-03-01T12:00:00Z"
HAS (:) Wartość pola zasobu zawiera podaną wartość. Jeśli pole zasobu jest ciągiem tekstowym, sprawdzi, czy podana wartość jest istniejącym podłańcuchem. Jeśli pole zasobu jest tablicą, sprawdzi, czy tablica zawiera określoną wartość.

Przykład: lineItemIds:"1234"

Jeśli w polu w opisie parametru nie określono żadnych operatorów, możesz użyć tylko operatora EQUALS (=). Niektóre pola obsługują większą liczbę operatorów.

Niektóre pola możliwe do filtrowania, takie jak daty i godziny, wymagają, aby porównywalna wartość miała określony format. Format jest podany obok pola w opisie parametru filter.

Logika między ograniczeniami

Możesz połączyć kilka ograniczeń, aby zawęzić lub rozszerzyć odpowiedź na żądanie LIST.

Zwykle możesz połączyć wiele ograniczeń za pomocą operatorów logicznych AND i OR. Każda metoda LIST określa, które operatory obsługuje. Niektóre metody obsługują tylko jedno ograniczenie w parametrze filter.

Tworząc ciągi filtrów z operatorami logicznymi AND lub OR, weź pod uwagę te ograniczenia:

.
  • Pole AND musi być używane między ograniczeniami lub grupami ograniczeń, które filtrują różne pola lub w różny sposób odfiltrowują to samo pole. Oto kilka przykładów:
    • 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")
  • Między poszczególnymi ograniczeniami filtrowanymi według tego samego pola należy stosować parametr OR. Oto przykład:
    • (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")

  • Nie możesz używać OR do łączenia 2 grup ograniczeń. Zamiast tego użyj wielu żądań LIST z innymi wartościami filtrów. Możesz na przykład użyć tych osobnych żądań LIST:

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

    Nie używaj operatora OR do łączenia:

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

  • Nawiasy mogą być domniemane, jeśli nie używasz ich do grupowania ograniczeń w ciągu filtra. Na przykład ten 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")