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
ifalse
. - 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
.