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