W tym przewodniku opisano składnię filtrów listy i sposób filtrowania różnych typów zasobów.
Niektóre metody interfejsu API mogą akceptować filtr w celu ograniczenia liczby zasobów zwracanych w odpowiedzi.
Podsumowanie
W tej sekcji znajdziesz krótkie omówienie struktury składni filtra listy.
Filtr to ciąg znaków zawierający
expression
.expression
to kombinacja wartości logicznych porównań:expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )
comparison
pasuje do pola zasobu z określoną wartością. Możesz używać wszystkich popularnych operatorów porównania.comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
Operator
has
, dwukropek (:
), może być używany w ciągach tekstowych i polach powtarzanych. Więcej informacji znajdziesz w sekcji Stosuj operator.W filtrach możesz używać tych typów wartości:
- Numbers
- Ciąg znaków
- Wyrażenia w nawiasach
value = number| string | "*" | "(" expression ")"
Ciągi tekstowe mogą reprezentować:
- Dowolny tekst
- Wartość logiczna
- Wartości w kolumnie Enum
- Sygnatury czasowe
Wyrażenia logiczne
expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}
Operacje są wykonywane w następującej kolejności:
NOT
OR
AND
Na przykład te wyrażenia są równoważne:
a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)
Operator AND
możesz pominąć w porównaniach. Na przykład te filtry są takie same:
c=d AND e=f
c=d e=f
Zamiast łącznika NOT
możesz użyć łącznika (-
). Między myślnikiem (-
) a tym porównaniem nie może być spacji. Na przykład te filtry są takie same:
NOT e=f
-e=f
Porównania
W tej sekcji opisano takie porównania funkcji "name OP value"
:
comparison = name OP value
gdzie
OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"
Lewa strona porównania to nazwa ścieżki pola zasobu interfejsu API.
Nazwa składa się z serii identyfikatorów zasobów połączonych kropką (.
). Po każdym identyfikatorze pola następuje następny poziom jego nazwy. Załóżmy na przykład, że zasób ma pole złożone item
, które ma inne złożone pole tool
, które ma pole o nazwie shape
. W filtrze dla tego zasobu odwołasz się do kształtu o nazwie item.tool.shape
.
Prawa strona to zwykle wartość skalarna, która jest konwertowana na typ pola i porównywana z nią. Więcej informacji znajdziesz w sekcji Typy literatury wartości.
Prawą stronę porównania można też zapisać w nawiasach jako kombinację wartości literałów lub wyrażeń logicznych, które zawierają tylko wartości literackie (poprzedzone znakiem NOT
lub nie). Do każdej z tych wartości stosowany jest nazwa po lewej stronie i operator porównania. Na przykład te filtry są takie same:
deal.name = ("test 1" OR "test 2")
deal.name = "test 1" OR deal.name = "test 2"
Oto kolejny, bardziej złożony przykład dwóch równoważnych filtrów:
deal.name = ("test 1" OR "test 2" AND (NOT "test3" OR "test4"))
(deal.name = "test 1" OR deal.name = "test 2") AND ( (NOT deal.name = "test3") OR deal.name = "test4")
Typy literałów wartości
Wartość po prawej stronie operatora porównania można podzielić na literały liczbowe i ciągi znaków.
Liczby
W tej sekcji opisano sposób reprezentacji literałów liczbowych.
Typ | Definicja | Przykłady |
---|---|---|
Double | Każda liczba z separatorem dziesiętnym oraz znakiem „-” lub bez niego jest traktowana jako liczba zmiennoprzecinkowa. |
|
Liczba całkowita | Każda liczba bez separatora dziesiętnego (ze znakiem „-”) lub bez niego jest traktowana jako liczba całkowita. |
|
Ciąg znaków
W tej sekcji opisujemy typy, które można zapisać jako literał ciągu znaków w składni filtra.
Typ | Definicja | Przykłady |
---|---|---|
Wartość logiczna | TRUE lub FALSE (wielkość liter nie jest rozróżniana). |
|
Enum | Nazwa literału typu wyliczeniowego. W wyliczeniach wielkość liter ma znaczenie. |
FINALIZED to nie to samo co Finalized
|
Ciąg znaków | Dowolny ciąg znaków zawierający tekst zakodowany w standardzie UTF-8 lub 7-bitowy tekst ASCII. Znaczenie osadzonego cudzysłowu musi być zmienione za pomocą ukośnika lewego. Ciągi bez cudzysłowów ze spacjami są traktowane jako niejawne operatory „AND” wśród wszystkich słów po podzieleniu ciągu znaków spacjami. |
|
Sygnatura czasowa | Ciąg znaków w standardowym formacie ISO8601. |
"2014-10-02T15:01:23.045Z"
|
Operatory porównania
Operatory porównania:
- Mniejsze lub równe:
"<="
- Mniejsze niż:
"<"
- Większe lub równe:
">="
- Większe niż:
">"
- Różne od:
"!="
- Równa się:
"="
- Ma:
":"
Te operatory mają zastosowanie do wartości typu liczba kwadratowa, liczba całkowita, wartość logiczna, Enum i sygnatura czasowa.
Zawiera operatora
Operatora HAS
(:
) możesz używać do wykonywania operacji specjalnych w tych polach:
- Podłańcuchy
- Jeśli używasz operatora
HAS
do porównywania wartości w kolumnie z ciągiem znaków z ciągiem, operator działa jako operacja podłańcucha. Na przykład funkcjaname:"abcd"
zwraca wszystkie wystąpienia, w którychname
jest ciągiem znaków zawierającym"abcd"
. - Sprawdzanie obecności
- Gdy używasz operatora
HAS
ze znakiem specjalnym*
, operatorHAS
szuka wartości niepustych. Na przykład funkcjaname:*
zwraca wszystkie instancje, w którychname
nie ma wartości null, nie ma żadnej wartości ani nie jest zdefiniowana. - Użycie operatora
HAS
z wartościami innymi niż ciągi znaków działa tak samo jak operatorEQUALS
(=
). Na przykładisCompleted:true
działa tak samo jakisCompleted = true
. - Pola powtarzane
Możesz użyć operatora
HAS
(:
) do filtrowania powtórzonego pola zasobu interfejsu API, o ile spełnione są te warunki:- w ścieżce identyfikatora pola jest tylko jeden powtórzony komponent.
- Ostatni identyfikator ścieżki pola jest typu skalarnego
Filtrowanie zagnieżdżonych pól powtarzanych nie jest obsługiwane.
Oto przykład:
item
ma polecolors
, które zawiera wartości ciągów znaków takie jak"red"
,"blue"
i"yellow"
.item.colors:("red")
zwraca wszystkie elementy, które mają w polucolors
wartość"red"
.item.colors:("red" "yellow")
zwraca wszystkie elementy, które w polucolors
mają zarówno"red"
, jak i"yellow"
.item.colors:("red" OR "yellow")
zwraca wszystkie elementy, które mają w polucolors
wartość"red"
lub"yellow"
.
item
ma też powtarzane poletools
, które jest obiektem złożonym ze polem skalarnymshape
, którego wartości mogą być"square"
lub"round"
.item.tools.shape:("square")
zwraca wszystkie elementy, które mają narzędzia w kształcie"square"
.item.tools.shape:("square" "round")
zwraca wszystkie elementy, które zawierają zarówno narzędzie w kształcie"square"
, jak i narzędzie w kształcie"round"
.item.tools.shape:("square" OR "round")
zwraca wszystkie elementy, które mają narzędzie kształtu"square"
lub narzędzie w kształcie"round"
.
Niewypełnione pola zagnieżdżone
Pola zagnieżdżone to pola podrzędne pól najwyższego poziomu, np. shape
w item.tools.shape
to zagnieżdżone pole na poziomie items.tools
.
Pola najwyższego poziomu domyślnie mają wartość Fałsz. Zagnieżdżone pola są domyślnie niepełne.
Obiekty z niewypełnionymi polami zagnieżdżonymi nie są zwracane przez filtry ujemne (!=
).
Oto przykład:
item.tools
zawiera wyliczenie size
, którego wartość można ustawić na "SMALL"
, "MEDIUM"
lub "LARGE"
.
Jeśli masz te elementy:
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
},
{
"name": "item3"
}
Wywołanie items.list
z filtrem ujemnym "tools.size != SMALL"
zwraca takie wyniki:
{
"items": [
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
}
]
}
Ponieważ filtr item.tools.size
nie ma ustawionego atrybutu item3
, filtr ujemny nie zwraca obiektu item3
.
Przykłady
Przykład | Opis |
---|---|
externalDealId = "123456789" |
externalDealId z wartością „123456789”. |
advertiserId:93641 |
advertiserId , który ma liczbę całkowitą 93641. |
isSetupComplete = true |
isSetupComplete ma wartość TRUE. |
updateTime > "2018-02-14T11:09:19.378Z" |
updateTime jest późniejszy niż 14.02.2018, o godz. 11:09:19,378 czasu UTC |
displayName = "proposal" AND proposalRevision = 3 |
Ciąg znaków displayName ma identyczną wartość „oferta pakietowa” ORAZ wartość oferty pakietowej jest równa 3. |
displayName = "proposal" OR proposalRevision = 3 |
displayName zawiera ciąg znaków „oferta pakietowa” LUB wartość oferty pakietowej wynosi 3. |
NOT displayName = "proposal" |
displayName to nie to samo co „oferta pakietowa”. |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState ma wartość wyliczeniową, która jest równa PROPOSED LUB BUYER_APPLICATIONED. |
proposalState = (PROPOSED AND BUYER_ACCEPTED) |
proposalState ma wartość wyliczeniową, która jest równa PROPOSED ORAZ BUYER_AKCEPTOWANEJ |
dealName = Test Deal |
INVALID wyrażenie |
dealName = "Test Deal" |
Wartość dealName jest równa „Umowa testowa”. |
dealName = (Test Deal) |
dealName jest równe „Testowe”, a także równa „Umowa”. |
dealName = ("Test1" OR "Test2") |
dealName ma wartość równą „Test1” lub równa „Test2”. |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName zawiera podłańcuch „test”. |
dealName:("A B") |
dealName zawiera podłańcuch „A B”. |
dealName:(A B) |
dealName zawiera podłańcuch „A” i podłańcuch „B”. |
dealName:("A" OR "B" AND "C") |
dealName zawiera podłańcuch „A” LUB „B” ORAZ zawiera też podłańcuch „C” |
dealName:("A B" C) |
dealName zawiera podłańcuch „A B” i podłańcuch „C”. |
dealName:("A B" OR C D) |
dealName zawiera podłańcuch „A B” lub „C” oraz podłańcuch „D”. |
dealName:(NOT "A" B) |
dealName nie zawiera żadnego podłańcucha „A” i zawiera też podłańcuch „B”. |
dealName:(NOT "A" OR "B") |
dealName nie zawiera żadnego podłańcucha „A” ani podłańcucha „B”. |