Filtruj odpowiedzi na liście

Większość usług w interfejsie Display & Video 360 API udostępnia metodę LIST do zbiorczego pobierania zasobów. Te metody LIST zwykle obsługują filtrowanie wyników za pomocą parametru zapytania filter. Używaj tego parametru, aby optymalizować korzystanie z interfejsu API, pobierając tylko te dane, których potrzebujesz.

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

Struktura filtra

Wartość parametru filter to ciąg znaków zawierający co najmniej jedną restrykcyjną regułę, którą można łączyć z operatorami AND lub OR i która jest pogrupowana 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 znaków filtra przekracza 500 znaków, wykonaj jedną z tych czynności:

  • Podziel logikę na wiele ciągów tekstowych filtra i pobieraj zasoby za pomocą oddzielnych żądań LIST.
  • Usuń część logiki z ciągu znaków filtra i użyj go do filtrowania zasobów pobieranych lokalnie.

Umieszczaj wartości ograniczeń w cudzysłowie, aby mieć pewność, że logika zostanie zastosowana prawidłowo.

Koduj ścieżki filtra w formacie URL, jeśli wywołujesz metody LIST bezpośrednio, bez korzystania z biblioteki klienta.

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

Pola, które można filtrować

Pola, według których można filtrować dane w przypadku każdej metody LIST, są wymienione w opisie parametru filter. W większości przypadków możesz filtrować według podzbioru standardowych pól zasobu. W niektórych rzadkich przypadkach dostępne są dodatkowe pola, których można używać tylko do filtrowania.

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

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

Przykład: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) Wartość pola zasobu jest mniejsza lub równa podanej wartości. Często używane podczas porównywania daty lub daty i godziny.

Przykład: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) wartość pola zasobu jest większa lub równa podanej wartości; Często używane podczas porównywania daty lub daty i godziny.

Przykład: updateTime>="2023-03-01T12:00:00Z"
HAS (:) Wartość pola zasobu zawiera podana wartość. Jeśli pole zasobu jest ciągiem znaków, sprawdza, czy podana wartość jest istniejącym podciągiem znaków. Jeśli pole zasobu jest tablicą, sprawdza, czy tablica zawiera podana wartość.

Przykład: lineItemIds:"1234"

Jeśli w opisie parametru nie ma określonych operatorów dla danego pola, możesz użyć tylko operatora EQUALS (=). Niektóre pola obsługują wiele operatorów.

Niektóre pola, które można filtrować, np. pola dat i godzin, wymagają, aby porównywalna wartość była w określonym formacie. Format jest określony obok pola w opisie parametru filter.

Logika między ograniczeniami

Aby zawęzić lub rozszerzyć zakres odpowiedzi na żądanie LIST, możesz połączyć kilka ograniczeń.

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

Podczas tworzenia ciągów znaków filtra za pomocą operatorów logicznych AND lub OR należy wziąć pod uwagę te ograniczenia:

  • Musisz użyć elementu AND między ograniczeniami lub grupami ograniczeń, które filtrują różne pola lub filtrują to samo pole na różne sposoby. 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")
  • Musisz użyć znaku OR między poszczególnymi ograniczeniami, które filtrują według tego samego pola. 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żyć OR do połączenia 2 grup ograniczeń. Zamiast tego użyj wielu LIST z różnymi wartościami filtra. Użyj na przykład tych 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 tych operatorów:

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

  • Jeśli nie używasz nawiasów do grupowania ograniczeń w ciągu filtra, mogą one być domyślnie dodawane. Na przykład ten ciąg znaków:

    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")