Filtry

Interfejs Ad Manager API obsługuje filtrowanie według metod List. Składnia ciągu filtra jest formalnie zdefiniowana w gramatyce EBNF.

Na początek podajemy kilka przykładów typowych zastosowań.

Przykład Znaczenie
orders.updateTime > "2024-01-01T00:00:00-5:00" Wyświetla zamówienia z wartością updateTime po 1 stycznia 2024 r. w czasie standardowym (UTC-5) wschodnim.
lineItems.targeting.geoTargeting.targetedGeoIds:2840 Wyświetla listę elementów zamówienia z kierowaniem geograficznym obejmującym Stany Zjednoczone (identyfikator kierowania geograficznego 2480)
lineItems.displayName = "*_interstitial" Wyświetla listę elementów zamówienia, których nazwa wyświetlana kończy się ciągiem znaków _interstitial.
orders.displayName = "*video*" Wyświetla zamówienia, których wyświetlana nazwa zawiera ciąg znaków video.
displayName:"video" Wyświetla zamówienia, których wyświetlana nazwa zawiera ciąg znaków video (alternatywna składnia)

Literals

Wartość literału naładowanego (np. 42, Hugo) to wartość, która ma zostać dopasowana do zapytania. Literały pojawiające się samodzielnie są dopasowane do wszystkich obsługiwanych pól zasobu. Zasoby dokumentują, które pola są uwzględniane w dopasowywaniu w metodzie list. Ta funkcja jest podobna do wyszukiwania uniwersalnego w interfejsie Ad Managera, ale dotyczy tylko jednego typu zasobu.

Ciągi znaków zawierające spacje należy ująć w podwójne cudzysłowy (np. "Foo bar"). Ciągów znaków nie można ująć w pojedyncze cudzysłowy.

Operatory logiczne

Interfejs API Ad Managera obsługuje operatory binarne AND i OR.

Operator Przykład Znaczenie
AND a AND b Prawda, jeśli a i b mają wartość prawda.
OR a OR b OR c Wartość Prawda, jeśli spełniony jest co najmniej jeden warunek: a, b lub c.

Operatory negacji

Interfejs API Ad Managera udostępnia operatory jednoargumentowe NOT i -. Te terminy są używane zamiennie.

Operator Przykład Znaczenie
NOT NOT a Wartość „prawda”, jeśli a nie jest równa true.
- -a Wartość „prawda”, jeśli a nie jest równa true.

Operatory porównania

Interfejs API Ad Managera obsługuje operatory porównywania binarnego =, !=, <, >, <= i >= w przypadku pól ciągu znaków, liczb, daty i czasu oraz pól trwania.

Operator Przykład Znaczenie
= a = true Zwraca wartość „prawda”, jeśli a ma wartość „prawda”.
!= a != 42 Prawda, chyba że a jest równe 42.
< a < 42 Zwraca wartość Prawda, jeśli a jest wartością liczbową mniejszą niż 42.
> a > "foo" Prawda, jeśli a jest uporządkowane leksyko po „foo”.
<= a <= "foo" Prawda, jeśli a to „foo” lub występuje przed nim leksykograficznie.
>= a >= 42 Zwraca wartość Prawda, jeśli a jest wartością liczbową równą co najmniej 42.

Filtry są akceptowane jako ciągi zapytań, dlatego konwersja typu ma miejsce w celu przełożenia ciągu na odpowiednią wartość, która jest poprawnie wpisana:

  • Ciągi znaków wymagają cudzysłowów podwójnych. Przykład: "Foo bar".
  • W przypadku enumów wymagana jest postać ciągu znaków (wielkość liter ma znaczenie).
  • Wartości logiczne oczekują wartości true i false.
  • Liczby powinny być podane w standardowej postaci liczby całkowitej lub zmiennoprzecinkowej. W przypadku liczb zmiennoprzecinkowych obsługiwane są wykładniki. Przykład: 2.997e9.
  • Czas trwania wymaga wartości liczbowej z sufiksem s (dla sekund). Przykłady: "20s", "1.2s".
  • Sygnatury czasowe oczekują ciągu w formacie RFC-3339. Przykład: "2012-04-21T11:30:00-04:00". Obsługiwane są przesunięcia UTC.

Symbole wieloznaczne

Podczas porównywania ciągów znaków pod kątem ich równości interfejs API Ad Managera obsługuje znaki wieloznaczne za pomocą znaku *.

Przykład Znaczenie
a = "*.foo" Zwraca wartość Prawda, jeśli a kończy się ciągiem „.foo”.

Operator przejścia

Interfejs API Ad Managera obsługuje operator ., który wskazuje przemierzanie za pomocą wiadomości, mapy lub struktury.

Przykład Znaczenie
a.b = true Prawda, jeśli a ma pole logiczne b o wartości prawda.
a.b > 42 Zwraca wartość Prawda, jeśli obiekt a ma pole liczbowe b, którego wartość jest większa niż 42.
a.b.c = "foo" Prawda, jeśli obiekt a.b ma pole ciągu znaków c o wartości „foo”.

Przejście jest zapisane przy użyciu nazw pól z zasobu. Poszczególne usługi mogą określać podzbiór pól obsługiwanych przez przeszukiwanie.

Zawiera operatora

Interfejs Ad Manager API obsługuje operator :, który oznacza „ma”. Można go używać w przypadku kolekcji (powtarzających się pól lub map), wiadomości i ciągów znaków. Jego działanie różni się nieco w zależności od kontekstu.

Zapytanie dotyczące pól ciągu znaków, aby sprawdzić, czy ciąg znaków zawiera pasujący podłańcuch:

Przykład Znaczenie
r.displayName:"_250x250" Prawda, jeśli pole ciągu znaków r.displayName zawiera podciąg _250x250.

Zapytanie dotyczące pól powtarzanych, aby sprawdzić, czy powtarzana struktura zawiera pasujący element:

Przykład Znaczenie
r:42 Prawda, jeśli r zawiera wartość 42.
r.foo:42 Zwraca wartość Prawda, jeśli r zawiera element e taki, że e.foo = 42.

Mapy, struktury i wiadomości mogą wysyłać zapytania o obecność pola w mapie lub o konkretną wartość:

Przykład Znaczenie
m:foo Prawda, jeśli m zawiera klucz „foo”.
m.foo:* Wartość „prawda”, jeśli m zawiera klucz „foo”.
m.foo:42 Prawda, jeśli m.foo ma wartość 42.

Podczas przeglądania wiadomości pole jest uważane za obecne tylko wtedy, gdy ma wartość inną niż domyślna.

Ograniczenia

Oprócz tego, co zostało określone tutaj, poszczególne usługi mogą określać dalszą strukturę lub ograniczenia dotyczące zapytań filtrujących.

Zamówienie

Interfejs Ad Manager API obsługuje sortowanie według metody List. Składnia pól orderBy to lista nazw pól rozdzielona przecinkami. Na przykład: "foo,bar".

Domyślna kolejność sortowania to rosnąco. Aby określić kolejność malejącą dla pola, dodaj sufiks " desc". Na przykład: "foo desc, bar".

Zbędne znaki spacji w składni są ignorowane. Wartości "foo, bar desc", " foo , bar desc " i "foo,bar desc" są równoważne.

Pola podrzędne określa się za pomocą operatora przemierzania. Na przykład foo.bar lub address.street.