Filtry

Interfejs API typu REST Ad Managera obsługuje filtrowanie według metod List. Składnia ciągu filtra jest formalnie zdefiniowana w gramacie EBNF.

Na początek przyjrzyjmy się kilku przykładom najczęstszych zastosowań.

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

Literały

Jednoznaczna wartość literału (przykłady: 42, Hugo) to wartość, do której należy dopasować tekst. Literały występujące samodzielnie są przybliżone dopasowane do wszystkich obsługiwanych pól zasobu. Zasoby dokumentują pola, które są uwzględniane w dopasowywaniu w metodzie list. Ta funkcja jest porównywalna z wyszukiwaniem uniwersalnym w interfejsie Ad Managera, ale jest ograniczona do jednego typu zasobu.

Literały ciągów zawierające spacje powinny być umieszczone w cudzysłowach podwójnych (np. "Foo bar"). Pojedynczych cudzysłowów nie można używać do zawijania literałów ciągów.

Operatory logiczne

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

Operator Przykład Znaczenie
AND a AND b Prawda, jeśli a i b są prawdziwe.
OR a OR b OR c Prawda, jeśli spełniony jest dowolny z tych warunków: a, b lub c.

Operatory negacji

Interfejs API typu REST Ad Managera udostępnia jednoargumentowe operatory NOT i -. Mogą być używane wymiennie.

Operator Przykład Znaczenie
NOT NOT a Prawda, jeśli a nie jest prawda.
- -a Prawda, jeśli a nie jest prawda.

Operatory porównania

Interfejs API typu REST Ad Managera obsługuje operatory porównania binarne =, !=, <, >, <= i >= w polach z ciągami znaków, ciągami liczbowymi, sygnaturami czasowymi i czasem trwania.

Operator Przykład Znaczenie
= a = true Prawda, jeśli a ma wartość prawda.
!= a != 42 Prawda, chyba że a równa się 42.
< a < 42 Prawda, jeśli a jest wartością liczbową mniejszą niż 42.
> a > "foo" Prawda, jeśli pole a jest uporządkowane leksykowo po „foo”.
<= a <= "foo" Prawda, jeśli a jest „foo” lub leksykatycznie przed nim.
>= a >= 42 Prawda, jeśli a ma wartość liczbową równą 42 lub większą.

Filtry są akceptowane jako ciągi zapytań, więc konwersja typu ma miejsce, aby przetłumaczyć ciąg na odpowiednią wartość o silnym wpisywaniu:

  • Ciągi znaków wymagają podwójnych cudzysłowów. Przykład: "Foo bar".
  • Wyliczenia wymagają reprezentacji ciągu znaków enum (wielkość liter ma znaczenie).
  • Wartości logiczne wymagają wartości literałów true i false.
  • Liczby oczekują standardowej reprezentacji liczby całkowitej lub liczby zmiennoprzecinkowej. W przypadku liczb zmiennoprzecinkowych obsługiwane są wykładniki. Przykład: 2.997e9.
  • Czasy trwania oczekują reprezentacji liczbowej, po której następuje sufiks s (sekundy). Przykłady: "20s", "1.2s".
  • Sygnatury czasowe wymagają ciągu znaków w formacie RFC-3339. Przykład: "2012-04-21T11:30:00-04:00". Obsługiwane są przesunięcia względem czasu UTC.

Symbole wieloznaczne

Podczas porównywania ciągów znaków równości interfejs API REST Ad Managera obsługuje symbole wieloznaczne przy użyciu znaku *.

Przykład Znaczenie
a = "*.foo" Prawda, jeśli a kończy się na „.foo”.

Operator przemierzania

Interfejs API typu REST Ad Managera obsługuje operator ., który wskazuje przemierzanie wiadomości, mapy lub elementu struct.

Przykład Znaczenie
a.b = true Prawda, jeśli a zawiera pole b o wartości logicznej „true” (prawda).
a.b > 42 Prawda, jeśli pole a ma liczbowe pole b większe niż 42.
a.b.c = "foo" Prawda, jeśli a.b ma pole c z ciągiem tekstowym „foo”.

Szybkość przemierzania jest zapisywana przy użyciu nazw pól z zasobu. Poszczególne usługi mogą określać podzbiór pól obsługiwanych na potrzeby przemierzania.

Zawiera operator

Interfejs API typu REST Ad Managera obsługuje operator :, co oznacza „hasła”. Można go używać z kolekcjami (powtarzającymi się polami lub mapami), wiadomościami i ciągami znaków. Za każdym razem działa nieco inaczej.

Zapytanie, które pozwala sprawdzić, czy ciąg zawiera pasujący podłańcuch:

Przykład Znaczenie
r.displayName:"_250x250" Prawda, jeśli pole ciągu znaków r.displayName zawiera podłańcuch _250x250.

Powtórzone zapytanie dotyczące pól w celu sprawdzenia, czy powtórzona struktura zawiera pasujący element:

Przykład Znaczenie
r:42 Prawda, jeśli r zawiera 42.
r.foo:42 Prawda, jeśli r zawiera element e taki jak e.foo = 42.

Mapy, obiekty struct 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 przemierzania wiadomości pole jest uznawane za obecne tylko wtedy, gdy ma wartość inną niż domyślna.

Ograniczenia

Poza tym, co zostało tu zdefiniowane, poszczególne usługi mogą określać dodatkową strukturę lub ograniczenia zapytań filtrów.

Zamówienie

Interfejs API typu REST Ad Managera obsługuje sortowanie według metod List. Składnia pól orderBy to rozdzielona przecinkami lista nazw pól. Przykład: "foo,bar".

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

Nadmiarowe spacje 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. Przykład: foo.bar lub address.street.