Składnia i wykorzystanie filtra listy

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:

1. NOT
2. OR
3. 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.	1234.567 -789.0123
Liczba całkowita	Każda liczba bez separatora dziesiętnego (ze znakiem „-”) lub bez niego jest traktowana jako liczba całkowita.	1234 -789

Ciąg znaków

W tej sekcji opisujemy typy, które można zapisać jako literał ciągu znaków w składni filtra.

Uwaga: literał ciągu znaków może być ujęty w cudzysłowy podwójny („ ”) lub bez cudzysłowu. Nie można używać cudzysłowów do reprezentowania literału ciągu. Na przykład „ABC DEF” i ABC DEF to literały ciągów znaków, ale „ABC DEF” już nie.

Typ	Definicja	Przykłady
Wartość logiczna	TRUE lub FALSE (wielkość liter nie jest rozróżniana).	TRUE True "true"
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.	name = "test \"double quotes\"" name=(ABC DEF) jest odpowiednikiem funkcji name=ABC AND name=DEF
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.

Uwaga: w przypadku wartości przechowywanych jako ciągi tekstowe możesz używać tylko operatorów "!=", "=" i ":". W porównaniu ciągów znaków nie jest rozróżniana wielkość liter.

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 funkcja name:"abcd" zwraca wszystkie wystąpienia, w których name jest ciągiem znaków zawierającym "abcd".

Sprawdzanie obecności

Gdy używasz operatora HAS ze znakiem specjalnym *, operator HAS szuka wartości niepustych. Na przykład funkcja name:* zwraca wszystkie instancje, w których name 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 operator EQUALS (=). Na przykład isCompleted:true działa tak samo jak isCompleted = true.

Pola powtarzane

Możesz użyć operatora HAS (:) do filtrowania powtórzonego pola zasobu interfejsu API, o ile spełnione są te warunki:

1. w ścieżce identyfikatora pola jest tylko jeden powtórzony komponent.
2. Ostatni identyfikator ścieżki pola jest typu skalarnego

Filtrowanie zagnieżdżonych pól powtarzanych nie jest obsługiwane.

Oto przykład:

item ma pole colors, 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 polu colors wartość "red".
• item.colors:("red" "yellow") zwraca wszystkie elementy, które w polu colors mają zarówno "red", jak i "yellow".
• item.colors:("red" OR "yellow") zwraca wszystkie elementy, które mają w polu colors wartość "red" lub "yellow".

item ma też powtarzane pole tools, które jest obiektem złożonym ze polem skalarnym shape, 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".

Uwaga: nie wszystkie pola powtarzane można filtrować. Więcej informacji o konkretnym zasobie znajdziesz w dokumentacji referencyjnej.

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 = 93641	advertiserId, który ma liczbę całkowitą 93641.
isSetupComplete = true isSetupComplete:TRUE 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 displayName = "proposal" 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 != "proposal"	displayName to nie to samo co „oferta pakietowa”.
proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED	proposalState ma wartość wyliczeniową, która jest równa PROPOSED LUB BUYER_APPLICATIONED.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = 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 = "Test1" OR dealName = "Test2"	dealName ma wartość równą „Test1” lub równa „Test2”.
dealName:*	dealName is not null.
dealName:"test" dealName:test	dealName zawiera podłańcuch „test”.
dealName:("A B") dealName:"A B"	dealName zawiera podłańcuch „A B”.
dealName:(A B) dealName:"A" AND dealName:"B"	dealName zawiera podłańcuch „A” i podłańcuch „B”.
dealName:("A" OR "B" AND "C") dealName:("A" OR "B" "C") dealName:"A" OR dealName:"B" AND dealName:"C" dealName:"A" OR dealName:"B" dealName:"C" (dealName:"A" OR dealName:"B") AND dealName:"C" (dealName:"A" OR dealName:"B") dealName:"C"	dealName zawiera podłańcuch „A” LUB „B” ORAZ zawiera też podłańcuch „C”
dealName:("A B" C) dealName:"A B" AND dealName:"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) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"	dealName nie zawiera żadnego podłańcucha „A” i zawiera też podłańcuch „B”.
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	dealName nie zawiera żadnego podłańcucha „A” ani podłańcucha „B”.