Filtry

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

Oto kilka przykładów typowych zastosowań, które pomogą Ci zacząć.

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 elementy zamówienia z kierowaniem geograficznym obejmującym Stany Zjednoczone (identyfikator kierowania geograficznego: 2480).
lineItems.displayName = "*_interstitial" Wyświetla elementy zamówienia, których wyświetlana nazwa 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ść dopasowania to wartość bezwzględna (np. 42, Hugo). Literaly występujące samodzielnie są dopasowywane z dużą dokładnością 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 uniwersalnego wyszukiwania w interfejsie Ad Managera, ale ogranicza się do jednego typu zasobu.

Ciągi znaków zawierające spacje powinny być ujęte w podwójne cudzysłowy (np. "Foo bar"). Nie można otaczać ciągów znaków pojedynczymi cudzysłowami.

Operatory logiczne

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

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

Operatory negacji

Interfejs API Ad Managera udostępnia operatory jednoargumentowe NOT i -. Można ich używać zamiennie.

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

Operatory porównania

Interfejs Ad Manager API obsługuje operatory porównywania binarnego =, !=, <, >, <= i >= w przypadku pól tekstowych, liczbowych, sygnatur czasowych i 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" Wartość „prawda”, jeśli a jest uporządkowana leksykograficznie 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 liczbą o wartości co najmniej 42.

Filtry są akceptowane jako ciągi znaków zapytania, więc następuje konwersja typu, aby przekształcić ciąg znaków w odpowiednią wartość stałą:

  • Ciągi znaków wymagają cudzysłowów podwójnych. Przykład: "Foo bar".
  • W przypadku enumów musisz podać ciąg znaków (wielkość liter ma znaczenie).
  • Wartości logiczne oczekują wartości true i false.
  • Liczby muszą 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 względem UTC.

Symbole wieloznaczne

Podczas porównywania ciągu znaków pod kątem równości interfejs Ad Manager API obsługuje symbole 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 Ad Manager API obsługuje operatora ., który wskazuje na przechodzenie przez wiadomość, mapę lub strukturę.

Przykład Znaczenie
a.b = true Prawda, jeśli a ma pole logiczne b o wartości true.
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 wędrówki.

Ma 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. W każdym z tych przypadków działa on nieco inaczej.

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 Zwraca wartość Prawda, jeśli r zawiera 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:* 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

Większość zasobów obsługuje sortowanie według metody List. Aby dowiedzieć się więcej o zachowaniu zasobu i polach obsługiwanych przez metodę List, zapoznaj się z jej dokumentacją.

Składnia pól orderBy to lista nazw pól rozdzielona przecinkami. Przykład: "foo,bar".

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

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

Podpola są określane za pomocą operatora przechodzenia. Na przykład foo.bar lub address.street.